This service lets you integrate CommandersAct's tag container in your Angular applications easily.
- Note: Familiarize yourself with CommandersAct's tag container's primary documentation before proceeding.
- Features
- Angular Version Compatibility
- Installation and Quick Start
- Methods
- Server-side Rendering (SSR)
- API Documentation
- Sample App
- Development
- License
- Automatic page tracking
- Set & Get Variables
- Reloading Containers
- Event triggering
- Multiple containers
The following table gives an overview of which version of ngx-tag-commander
to use depending on your project's Angular version.
- ✅: supported
⚠️ : not explicitly built for but might be working- ❌: not supported
Angular version | [email protected] (current) |
[email protected] |
[email protected] |
---|---|---|---|
17.x.x |
✅ | ❌ | |
16.x.x |
✅ | ❌ | |
15.x.x |
❌ | ✅ | ❌ |
14.x.x |
❌ | ✅ | ❌ |
13.x.x |
❌ | ✅ | ❌ |
12.x.x |
❌ | ✅ | ❌ |
11.x.x |
❌ | ❌ | |
10.x.x |
❌ | ❌ | |
9.x.x |
❌ | ❌ | |
8.x.x |
❌ | ❌ | |
7.x.x |
❌ | ❌ | ✅ |
The quick start is designed to give you a simple, working example for the most common usage scenario. There are numerous other ways to configure and use this library as explained in the documentation.
The plugin doesn't replace the standard setup of a container because you may need to use the containers outside the plugin.
Initialize your datalayer so that it's ready for the container and plugin, without losing any data. Do it as soon as possible on your website like in a <script>
block in the head of your webapp.
tc_vars = []
You can install the module from a package manager of your choice directly from the command line
npm i ngx-tag-commander
...
import { WindowRef } from 'ngx-tag-commander';
...
import { NgxTagCommanderModule } from 'ngx-tag-commander';
@NgModule({
...
imports: [
...
NgxTagCommanderModule
...
],
providers: [WindowRef],
...
})
import { TagCommanderService } from 'ngx-tag-commander';
...
export class AppModule {
constructor(tcService: TagCommanderService) {
...
Promise.all([
tcService.addContainer('container_body', '/assets/tag-commander-body.js', 'body'),// Replace URL by the one of your container
tcService.addContainer('container_head', '/assets/tag-commander-head.js', 'head')
]).then(() => {
//Insert the rest of your code here
});
...
}
}
You are now ready to use the ngx-tag-commander plugin.
Some methods are asynchronous. If you want to ensure that a method has been executed before continuing, you can use the await keyword. Please check the function definition to see if it is asynchronous.
import { TagCommanderService } from 'ngx-tag-commander';
...
export class MyComponent {
constructor(private tcService: TagCommanderService) {
...
}
}
// Adding a container
await tcService.addContainer('my-custom-id', '/url/to/container.js', 'head');
// Removing a container
tcService.removeContainer('my-custom-id');
// Set variables
tcService.setTcVars({ env_template : "shop", env_work: 'dev', ... });
// Update a single variable, you can also overwrite existing variables
tcService.setTcVar('env_template', 'super_shop');
// Get a variable
const myVar = wrapper.getTcVar('env_template');
// Remove a variable
tcService.removeTcVar('env_template');
You can also use the directive SetTcVarsDirective
to set variables directly on any html node:
<div [tcSetVars]="{ env_template: defaultEnv }"></div>
- Refer to the base documentation on events for an understanding of events in general.
- The method
triggerEvent
is the new name of the old methodcaptureEvent
; an alias has been added to ensure backward compatibility.
// Triggering an event
// eventLabel: Name of the event as defined in the container
// htmlElement: Calling context. Usually the HTML element on which the event is triggered, but it can be the component.
// data: event variables
tcService.triggerEvent(eventLabel, htmlElement, data);
- Events can also be triggered by using the
TcEventDirective
. The event will be triggered when clicking the button.
<button [tcEvent]="'test'" [tcEventLabel]="'test'" [tcEventObj]="cartItems">Add Items in ShopCart</button>
Update your container after any variable change.
tcService.reloadContainer(sideId, containerId, options);
Automatic reload can be performed on route change.
- Enable the service's route tracking in the app configuration:
tcService.trackRoutes(true);
- Add the
tcInclude
property to your routes:
const appRoutes: Routes = [
{
path: '',
redirectTo: '/home',
pathMatch: 'full',
data: {
tcInclude: [{
idc: 12,
ids: 4056,
options: {...}
}]
}
},
{
path: 'home',
component: IndexPageComponent,
data: {
tcInclude: [{
idc: 12,
ids: 4056,
options: {...}
}]
}
}
];
You can state an exclusion array to your options object like below:
tcInclude: [{
idc: 12,
ids: 4056,
options: {
exclusions: [
'datastorage',
'deduplication',
'internalvars',
'privacy'
]
}
}];
Please see the container's documentation for other options.
ngx-tag-commander
fully supports Server-side rendering (SSR), as it comes with an internal check to run the code only on the client-side.
This is important as the wrapper is interacting with the DOM objects document
and window
, which are not available on the server.
TagCommanderService.addContainer(id: string, uri: string, node: string): Promise<void>
id
: The id the script node will haveuri
: The source of the scriptnode
: The node on witch the script will be placed. Can either behead
orbody
- Returns a promise which is resolved when the container has been loaded.
TagCommanderService.removeContainer(id: string): void
id
: The id of the container to remove
TagCommanderService.setDebug(debug: boolean): void
debug
: TagCommanderService will display debug messages if set totrue
TagCommanderService.trackRoutes(b : boolean): void
b
: TagCommanderService will reload containers on route change if set totrue
TagCommanderService.setTcVar(tcKey: string, tcVar: any): void
tcKey
: Key of the variable to set or updatetcVar
: Data of the variable
TagCommanderService.setTcVars(vars: object): void
vars
: Object containing the multiple variables to set or update
TagCommanderService.getTcVar(tcKey: string): any
tcKey
: Key of the variable to get
TagCommanderService.removeTcVar(tcKey: string): void
tcKey
: Key of the variable to remove
TagCommanderService.reloadAllContainers(options: object): number
options
: Options passed totC.container.reload(options)
TagCommanderService.reloadContainer(siteId: string, containerId: string, options: object): number
siteId
: Site idcontainerId
: Container Idoptions
: Options passed totC[containerId].reload(options)
TagCommanderService.triggerEvent(eventLabel: string, htmlElement: HTMLElement, data: object)
eventLabel
: Name of the eventhtmlElement
: DOM element where the event is attacheddata
: Data sent with the event
To help you with your implementation we provided a sample application. To run it clone the repo and ensure you have Node.js >=18.x.x installed. Then run in the base folder:
npm install
npm start
After that, visit http://localhost:4200/.
The implementation of the ngx-tag-commander
library can be found in /projects/ngx-tag-commander
. Changes can be tested using the sample app described above.
Useful commands (ensure you have Node.js >=18.x.x installed & run in the base folder):
- Setup development environment:
npm install
- Run sample app:
npm start
- Run linter:
npm run lint
- Run library tests:
npm run test
- Run sample app tests:
npm run test-sample-app
- Build library:
npm run build
To contribute to this project, please read the CONTRIBUTE.md file.
As Angular itself, this module is released under the permissive MIT License. Your contributions are always welcome.