Integrating the SDK
The Kochava Web SDK is available as a first-class Angular library. The SDK itself operates as an Angular service singleton, available within the KochavaAngularModule.
- Install via Angular CLI.
- Import KochavaAngularModule to the root component’s module file (typically app.module.ts) and add the KochavaAngularModule.forRoot() entry to your app.module’s import section.
- In your root component, import the KochavaAngularService and inject it into the constructor. Finally, set its required provider entries.
- 'app_id' — Replace ‘YOUR_APP_GUID’ with your Kochava App GUID. For more information on locating your App GUID, refer to our Locating your App GUID support documentation.
- 'verbose' — Set to true for verbose logging to the console. Set to false to suppress all logging.
- 'use_cookie' — Set to true to drop Cookie on the website to track a device across sub-domains. Set to false to not drop the Cookie and rely only on local storage for tracking.
- 'custom_traits' — Set to an object of key-value pairs that provides a means for linking different identities with Kochava devices. E.g., {“User ID”: “123456789”, “Login”: “username”}.
- 'disable_auto_install' — Set this value to true to stop the SDK from automatically signaling an install when the SDK is initialized for the first time.
- For any additional components which utilize the SDK, import the KochavaAngularService service and inject it into the component constructor. No provider entries are required.
Run ng add kochava-angular from the root of your project (which contains your package.json). This will pull in the latest version of the SDK.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 | import { NgModule } from '@angular/core'; import { BrowserModule } from '@angular/platform-browser'; import { AppComponent } from './app.component'; import { KochavaAngularModule } from 'kochava-angular'; @NgModule({ declarations: [ AppComponent ], imports: [ BrowserModule, KochavaAngularModule.forRoot(), ], providers: [], bootstrap: [AppComponent] }) export class AppModule { } |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 | import { Component } from '@angular/core'; import { KochavaAngularService } from 'kochava-angular'; @Component({ selector: 'app-root', templateUrl: './app.component.html', styleUrls: ['./app.component.css'], providers: [ KochavaAngularService, {provide: 'app_id', useValue: 'YOUR_APP_GUID'}, {provide: 'verbose', useValue: true }, {provide: 'use_cookie', useValue: true }, {provide: 'custom_traits', useValue: {} }, {provide: 'disable_auto_install', useValue: false }, ] }) export class AppComponent { constructor(kochava: KochavaAngularService) { } } |
1 2 3 4 5 6 7 | import { KochavaAngularService } from 'kochava-angular'; ... export class AppComponent { constructor(kochava: KochavaAngularService) { } } |
NOTE: You do not need to worry about multiple instances of the Kochava service, as it is a singleton. There is only ever one KochavaAngularService in existence, which is initialized in your root component.
Using the SDK
Once you have completed integration, access the Kochava service to perform the following optional functionality.
The Kochava service works just like other angular services you may have used before. After integration, you can access the Kochava service in a number of ways. For example, while not required, you can assign the service to a class member in order to use it outside of your component constructor.
Example — (Assign the Kochava Service to a Class Member for External Usage)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 | import { Component, OnInit } from '@angular/core'; import { KochavaAngularService } from 'kochava-angular'; @Component({ selector: 'kochava-second', templateUrl: './second.component.html', styleUrls: ['./second.component.css'] }) export class SecondComponent implements OnInit { kochava: KochavaAngularService; constructor(kochava: KochavaAngularService) { this.kochava = kochava; } ngOnInit(): void { this.kochava.page("custom_page", {}, (e,t)=>console.log(t)); } buttonPressed(): void { this.kochava.activity("clickid123", {"item":"123"}, (e,t)=>console.log(t)); } } |
Page:
The page function allows you to record page views on your website, along with optional metadata information about the page being viewed. If you do not specify a page name, Kochava will dynamically collect the page from the URL. Optional metadata must be provided as an object of key value pairs. The callback parameter is optional and may be safely omitted if not desired.
Example — (Record a Page View Manually)
1 | kochava.page("my_custom_page", {}, callback); |
Example — (Record a Page View Manually with Event Data)
1 | kochava.page("my_custom_page", {"item":"123456789"}, callback); |
Autopage —
If you would like to record page views automatically whenever the user loads a new page, this can be accomplished by calling the kochava.page() function in the root component (usually app.component.ts) constructor.
Example —(Automatically Record all Page Views Using the Current URL)
1 2 3 4 5 | export class AppComponent { constructor(kochava: KochavaAngularService) { kochava.page(); } } |
Identify (Identity Link):
The identify function tells Kochava who the current user is. This method provides Kochava with a unique user ID and any other user specific data available. Calls to kochava.identify() will send the user data to the Kochava Identify API, allowing the data to be used for attribution. The callback parameter is optional and may be safely omitted if not desired.
NOTE: If a string is passed instead of an object, that value will be associated with the key custom_id.
Example —(Identify with Only a String Value)
1 | kochava.identify("my_custom_id", callback); |
Example —(Identify with a Key Value Pair)
1 | kochava.identify({"my_custom_key":"my_custom_id"}, callback); |
Activity (Event):
The Activity function allows you to record custom actions or events which your users are performing or completing throughout your site. Every integrated action or event that is triggered can include optional metadata properties which can be exposed via reporting and analytics. These integrated activities can also act as engagement/conversion events through the tracking URL creation process. The “callback” parameter is optional and may be safely omitted if not desired.
Example —(Track an Activity)
1 | kochava.activity("my_activity_name", {"my_custom_key":"my_custom_value"}, callback); |
NOTE: The SDK collects the time on page which is sent with any custom events implemented. The time that is returned is in seconds and starts once the page is loaded until the custom event is sent/completed. The “event_name” parameter is required but all other parameters are optional and may be safely omitted if not desired.
NOTE: For more information on standard events within Kochava, refer to our Post-Install Event Examples support documentation.
Install:
The install is automatically sent for you and you do not need to perform this activity unless you have set Disable Auto Install to true. If you have set this value to true, you must manually send the install only once, and do so before sending any other activities or events. It is your responsibility to ensure this function is called only once per user.
Example —(Install)
1 | kochava.install(callback); |
Alternatively, if you have an identity link in scope at the moment you wish to send the install, call installWithIdentity() with an object containing identity key and value pairs as the first parameter. This will ensure the identity link is included directly within the manually triggered install payload.
Example —(Install with an Identity Key Value Pair)
1 | kochava.installWithIdentity({"my_identity_key":"my_identity_value"}, callback); |
