Implement the Web JS Source

Latest Version

4.0.8

Overview

The zeotap.js JavaScript file helps you to send data from your websites to your Zeotap account. This web JS is a client-side library that can be implemented on websites to track events, page visit information, user logins and user details or any other information relating to the product or services offered on the site. This data can then be made actionable by creating user segments, viewing insights and targeting them on your preferred platforms.

Prerequisites

Before proceeding to the integration process for the SDK into a client’s website, ensure that the following prerequisites are met:

Access to the Zeotap CDP (Customer Data Platform) instance is required.
CMP (Consent Management Platform) integration on the client’s website is necessary, especially if the consent strategy is not set as the default option.

Get Started

Follow the step-by-step process outlined below to integrate the zeotap.js library into your website:

Create a Web JS Source

Add the Snippet

Track Activities

Step 1 – Create a Web JS Source

To start with, you need to create a Web JS source on the Zeotap’s platform. To do so, perform the following steps:

Log into the Zeotap CDP App and go to the Sources application.

Create a source with the following details:a. Category – Website Eventsb. Data Source – Web JavaScript

Go to the IMPLEMENTATION DETAILS tab and copy the snippet provided along with the write_key.

Note:In the case of a single-page application, you can add it in the root, index.html.

Step 2 – Add the JS Snippet

Next, you have to paste the copied snippet into the <head> tag of your website (between <head> and </head>). Sample JS Snippet

Code

<script type="text/javascript">!function(e,t){var 
n=t.createElement("script");
n.type="text/javascript",n.crossorigin="anonymous",n.async= !0,n.src="<SRC>",n.onload=function(){};
var s=t.getElementsByTagName("script") [0];
s.parentNode.insertBefore(n,s);
function o(e,t,n){function s(t){e[t]=function() {e[n].push([t].concat(Array.prototype.slice.call(arguments,0)))}}for(var o=0;o<t.length;o++)s(t[o])}var r=e.zeotap||{_q:[],_qcmp:[]};
o(r, 
["init","setEventProperties","setUserProperties","setPageProperties","setMetaProperties ","setUserIdentities","unsetUserIdentities","setZI"],"_q"),o(r, 
["setConsent","addAskForConsentActionListener"],"_qcmp"),e.zeotap=r}(window,document); </script><script type="text/javascript">window.zeotap.init("YOUR_WRITE_KEY");
</script>

Then, replace the “YOUR_WRITE_KEY” key mentioned in the sample snippet with the Zeotap issued write key for your Source. You can find the write key from the IMPLEMENTATION DETAILS tab on Sources. This write key makes the Zeotap variable available in your page’s Global context. You can access it through window.zeotap. Note that the above-mentioned snippet initializes the SDK with the write_key and the default options. To know more about the options available in the system while intialising the SDK, refer here.

Step 3 – Tracking Methods

The following are the tracking methods that constitute the foundational elements of your tracking strategy:

Set Page Properties

Set Event Properties

Set User Properties

Set User Identities

Unset User Identities

Track User Consent

Set Page Properties

After integrating the zeotap.js library, you can use this method to log the users’ page view events by calling setPageProperties(properties) and sending all page related information as key=value properties on the page load event. All further user events on the same page are then attached with these page properties.

Parameter	Type	Description
properties	Object	This indicates the page specific properties.

Below is an example showing how to capture user viewing a Product page: zeotap.setPageProperties({name: 'Product'}) This example creates the following payload:

Code

{
  "event": {
    "eventName": "pageView",
    "eventTimestamp": 1584350000
  },
  "page": {
    "name": "Product Page",
    "url": "https://www.xyz.com/products",
    "path": "/products"
  },
  "User": {
    "zi": "user_123",
    "zs": "session_123"
  }
}

If the page view is not recorded this way, then while other events are recorded (refer to the To Track User Actions section), the SDK attaches the page URL, path and referrer URL by default to the payload.

Set Event Properties

You can use this method to track events after tracking the page views. Use the setEventProperties method to track different user actions on the website (for example, the selectVariant event with colour as a property) and properties relating to the event (for example, a viewCart event with cartVal as a property).

Parameter	Type	Description
`eventName`	String	This is the name of the event.
`eventProperties`	Object	This is the object containing any properties for a particular event.

Below is an example showing how to track a product being viewed, which can be triggered on the view product event.

Code

zeotap.setEventProperties('view product', { 
 productID: '1234' 
}); 

This example creates the following payload:

Code

{ "event":{ 
 "eventName":"viewProduct", 
 "productID":"prod_123", 
 "eventTimestamp":1584350000 
 }, 
 "page":{ 
 "url":"https://www.xyz.com/products/?pid=prod_123", 
 "path":"/products/?pid=prod_123" 
 }, 
 "User":{ 
 "zi":"user_123", 
 "zs":"session_123" 
 } 
} 

Set User Properties

If you have any other information you want to send about the user on the site, you can send the same using setUserProperties method. This is sent to the API with the default user zi ID, along with any other identities set using setUserIdentities.

Note:The records for the country and city columns are blacklisted for ingestion because SPL uses the user’s IP address to find out the country and city automatically. For the complete list of blacklisted fields, click here.

Below is an example showing how to pass the user profile information.

Code

zeotap.setUserProperties({ 
 age: 25,  
 gender: 'Male',  
 country: 'IND' 
}) 

This example creates the following payload:

Code

{
  "event": {
    "eventName": "set_user_properties",
    "eventTimestamp": 1584350000
  },
  "page": {
    "url": "https://www.xyz.com/post_login",
    "path": "/post_login"
  },
  "User": {
    "age": 25,
    "gender": "Male",
    "country": "IND",
    "zi": "user_123",
    "zs": "session_123",
    "email": {
      "sha256": "f42d22f9a2de86d9ee38e8e7dee54ecfefca679b8276991a4ecb056f2cd008cb",
      "sha1": "7790bb717a66e6c379fd46b4b687cdef3ec0d98b",
      "md5": "a8c358b62218df2b0319828ef89949e2"
    },
    "cellno": {
      "sha256": "e0f83d781529bf49eaf6d907ed307d942c040eb8791e02767441344db36fa774",
      "sha1": "51440fde8f0c0498432509cdf279bdba72d747f2",
      "md5": "a67e0b4bddae5fc871060976b7c95579"
    }
  }
}

If you want to treat the pre-login, post-login and post-logout users as the same user, then you can choose to send user identities like email, cell phone number using setUserProperties instead of setUserIdentities. Similar to setUserIdentities, any string provided with the reserved keys such as loginid, email address, fpuid and cell phone number are hashed before sending them to the API. If the cell phone number is added along with property countrycode, then we clean the string value for any special characters and hash the cleaned value as follows:

cellno_without_country_code (hashed value of only cellno)

#deprecated key

cellno_with_country_code ( hashed value with countrycode + cellno)

Set User Identities

You can use this method to capture user identities. The user identities can be categorised as below.

Personal Identifiable Information (PII)
- Raw User PII
- Hashed User PII
Custom Identities

Note:Identities passed using setUserIdentities will be stamped in storage and persisted in subsequent server calls.

Personal Identifiable Information (PII)

Personal Identifiable Information (PII) is any data that confirms an individual’s identity. Examples of PII include name, email address, telephone number, address and other attributes of an individual’s demographic, financial, health and any other personal details. PII can be categorised as Raw User PII and Hashed User PII.

Raw User PII

The client captures user PII in the raw form and may or may not want Zeotap to hash them. Refer to the table below to understand the scenarios, the SDK options that are involved and a sample to invoke the setUserIdentities method.

Scenario	SDK Options	setUserIdentities
Client sends raw user PII and they do not want Zeotap to hash them	The following SDK options are involved in this scenario: • `areIdentitiesHashed`: `false`, • `hashIdentities`: `false`	`zeotap.setUserIdentities({` `email: 'john.doe@gmail.com',` `cellno: '45454545'` `});`
Client sends raw user PII but they want Zeotap to hash them	The following SDK options are involved in this scenario: • `areIdentitiesHashed`: `false`, • `hashIdentities`: `true`	`zeotap.setUserIdentities({` `email: 'john.doe@gmail.com',` `cellno: '45454545'` `});`

When the client has captured the raw user PIIs, the setUserIdentities method considers the properties as mentioned in the table below.

Parameter	Type	Description
`properties`	Object	This is the object containing the PII.
`[properties.fpuid]`	String	This is the first-party ID for a given user, such as a CRM ID or DB ID.
`[properties.email]`	String	This is the user’s raw email address. The SDK either captures as is or converts to `sha256` lowercase and uppercase hashed values, based on the SDK configurations.
`[properties.cellno]`	String	This is the user’s raw cell phone number. The SDK either captures as is or converts to `sha256` without the country code, based on the SDK configurations. Recommended format: code<space>number
`[properties.loginid]`	String	This is the user’s login ID that is hashed and logged.
`[properties.cellno_cc]`	String	This parameter is deprecated but the existing clients can continue to use it as it is. This is the user’s raw cell phone number. The SDK either captures as is or converts to `sha256` with the country code, based on the SDK configurations. This parameter is deprecated but the existing clients can continue to use it as it is.
`[isHashed]`	Boolean	This parameter is deprecated but the existing clients can continue to use it as it is. If this option is set to true, then the IDs are assumed to be hashed in `sha256` after converting them in lower case and with country code for cell phone number. `sha256` hashing must be HEX code with 64 characters. For example, `f660ab912ec121d1b1e928a0bb4bc61b15f5ad44d5efdc4e1c92a25e99b8e44a`

Note:In case of the following selections, by default, the raw identities are hashed to sha256:

When areIdentitiesHashed: false
When [options.optOut] is set to false

Hashed User PII

The client only sends in user PII that are hashed using algorithms like “SHA256, SHA1andMD5

. In this scenario, refer to the table below to understand the scenario in detail, the SDK options that are involved and a sample for the

setUserIdentities` property.

Scenario	SDK Options	setUserIdentities
Client sends hashed user PII only	The SDK option involved in this scenario is areIdentitiesHashed: true	`zeotap.setUserIdentities({` `email_sha256_lowercase: 'john.doe@gmail.com',` `cellno_with_country_code_sha256: '45454545'` });`

When the client has captured the raw email and phone number of the users, the setUserIdentities property is configured with properties as mentioned in the table below.

Parameter	Type	Description
`properties`	Object	This is the object containing the PII.
`[properties.fpuid]`	String	This is the first-party ID for a given user, such as a CRM ID or DB ID.
`[properties.email_sha256_lowercase]`	String	This is the user’s email address hashed to `sha256` after converting it to lowercase.
`[properties.email_sha256_uppercase]`	String	This is the user’s email address hashed to `sha256` after converting it to uppercase.
`[properties.email_md5_lowercase]`	String	This is the user’s email address hashed to `md5` after converting it to lowercase.
`[properties.email_md5_uppercase]`	String	This is the user’s email address hashed to `md5` after converting to uppercase.
`[properties.email_sha1_lowercase]`	String	This is the user’s email address hashed to `sha1` after converting to lowercase.
`[properties.email_sha1_uppercase]`	String	This is the user’s email address hashed to `sha1` after converting to uppercase.
`[properties.cellno_without_country_code_sha256]`	String	This is the user’s cell phone number without the country code and hashed to `sha256`.
`[properties.cellno_without_country_code_md5]`	String	This is the user’s cell phone number without the country code and hashed to `md5`.
`[properties.cellno_without_country_code_sha1]`	String	This is the user’s cell phone number without the country code and hashed to `sha1`.
`[properties.cellno_with_country_code_sha256]`	String	This is the user’s cell phone number with the country code and hashed to `sha256`.
`[properties.cellno_with_country_code_md5]`	String	This is the user’s cell phone number with the country code and hashed to `md5`.
`[properties.cellno_with_country_code_sha1]`	String	This is the user’s cell phone number with the country code and hashed to `sha1`.
`[properties.loginid_sha256_lowercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to `sha256` after converting to lowercase.
`[properties.loginid_sha256_uppercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to `sha256` after converting to uppercase.
`[properties.loginid_md5_lowercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to `md5` after converting to lowercase.
`[properties.loginid_md5_uppercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to `md5` after converting to uppercase.
`[properties.loginid_sha1_lowercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to `sha1` after converting to lowercase.
`[properties.loginid_sha1_uppercase]`	String	This is the user’s login ID that is logged. The login ID is hashed to sha`1 after converting to uppercase.

Custom Identities

Custom identities are the identities that the client chooses to input and can be any of their first-party identifiers. Note that the hashing configurations are not applicable for custom identities. Some examples of custom identities are crmID, ECIDandvisitorID`. You can pass the custom identities in the format shown below. zeotap.setUserIdentities({crmId:'...'})

Note:To know about the hashing guidelines for email and cell phone numbers, refer here.

Unset User Identities (Log out communication)

If you no longer wish to attach these identities to the events (for example, when the user logs out) you can communicate this by using unsetUserIdentities method and then choosing the identities that you want to remove. Call the method as follows: zeotap.unsetUserIdentities([removedPropertyKeys]) If no properties are specified, then all the identities are removed.

Parameter	Type	Description
`[removedPropertyKeys]`	Array	If provided only these keys in the array are removed.

The zeotap.js library supports the different methods of communicating the consent. At the time of initialization, you can set the options for the SDK to consume consent according to your requirements.

Parameter	Type	Default	Description
`apiKey`	String		This is the API key for the source. Log into Sources, click on a particular source and access the key from the IMPLEMENTATION DETAILS section.
`[options]`	String		This option is passed during initialization.
`[options.optOut]`	Boolean	`false`	This option gives the signal on whether the SDK is allowed to record events or not. If set to `true` no events are posted to the backend. This option is then used as a fallback when user consent is not specified.
`[options.useConsent]`	Boolean	`false`	If this option is set to true, then the SDK waits to receive a consent signal and uses that consent to manage actions. This consent signal is determined by options: `checkForCMP`.
`[options.checkForCMP]`	Boolean	`true`	If this option is set to true, then we check for the presence of the `__cmp` variable in the global scope and the `cmp.js` script. If the `__cmp` variable is present, then we query the CMP API and check for the publisher’s consent. If this option is set to `false`, then we use the set consent signal using the `setConsentmethod`.

The consent that you provide is used for the following two primary purposes:

User identification
Tracking user data
Cookie syncing

Web JS has three different ways to determine user consent that enable the collection, documentation and management of your user’s privacy choices in order to ensure legal compliance. Zeotap stores the consent information in the customer profile against their Unique Customer ID.

Note:For Default Opt-in and GDPR consent types, the setConsent string (including the Track, Cookie Sync, and Identify fields) is ignored for resolution. It is only considered for resolution in the Custom consent type. However, you can send Brand Consent in any of these consent types.

Default Opt-in

In this scenario, you directly provide consent to Zeotap by setting the optOut flag to true or false. For all these three purposes, if the optOut flag is set to true, then it indicates that you have not granted access to Zeotap. Here, SDK is not allowed to perform user identification or tracking user data. However, if the optOut flag is set to false, then the SDK is allowed to perform all the above actions. In this consent type, you can pass the setConsent method in the format setConsent({track: true, cookieSync: true, brand1Consent: true, brand2Consent: true}). However, only Brand Consent is considered , while the Track, Cookie Sync fields are ignored, even if they are set to true.

Function	Type	Value	Description
optOut	Boolean	`false`	This is an explicit consent signal that you set. When enabled, the SDK cannot perform any actions for user identification, cookie syncing or event capturing.

If you already have a TCF 2.0 Consent Management Platform (CMP) implemented on your website, then the SDK automatically checks for the same. To do this, both the useConsent and checkForCMP flags are set to true. The SDK also queries the TCF consent string to fetch the Publisher’s consent before recording the events. In this consent type, you can pass the setConsent method in the format setConsent({track: true, cookieSync: true, brand1Consent: true, brand2Consent: true}). However, only Brand Consent is considered, while the Track, Cookie Sync fields are ignored, even if they are set to true. The below table describes the keys/parameters that need to be configured while using the GDPR consent module.

Function	Type	Value	Description
`useConsent`	`Boolean`	`true`	If this option is set to `true`, then the SDK waits to receive a consent signal and uses that consent to manage actions. This consent signal is determined by the `checkForCMP` flag.
`checkForCMP`	`Boolean`	`true`	If this option is set to `true`, then we check for the presence of the TCF API. If the TCF 2.0 API is present, then we query the CMP API and check for the publisher’s consent. If this option is set to `false`, then we use the set consent signal using the `setConsent` method.
`purposesForTracking`	`number[]`	[1,3,4]	This option is used to pass a list of purpose IDs, based on which you can manage the consent for tracking. Note: To know more about the purposes for tracking and the associated IDs, refer to the “Appendix A: Purposes and Features Definitions” section of this topic.
`purposesForCookieSyncing`	`number[]`	[1,3,4]	This option is used to pass a list of purpose IDs, based on which you can manage the consent for Cookie Syncing. Note: To know more about the purposes for cookie syncing and the associated IDs, refer to the “Appendix A: Purposes and Features Definitions” section of this topic.

You may not want to explicitly give consent or even use the TCF API. Instead, you need to have a custom consent flow. The following initial configurations activate the Custom Consent flow:

The useConsent flag is set to true
The checkForCMP option is set to false
The setConsent method is used to resolve the user consent

The user consent is then stored in cookie storage and used as the user’s consent status for the subsequent event log until a new status is set using the same.

Call the setConsent Method

Call the setConsent method as mentioned below.

Code

zeotap.setConsent(value)

#deprecated
zeotap.setConsent(value, [expiry], [purpose])

Parameter	Type	Default	Required	Description
`value`	Boolean/Object		Yes	• Object – Granular consent allows passing value as a JSON object. `{primaryConsent, brandConsent}`. Primary consent keys: track, cookieSync, identify. Anything other than primary consent keys will be treated as brand consent. Boolean type is deprecated but the existing clients can continue to use it as it is. • Boolean – Basic Consent allows passing the value as a Boolean set to `true` or `false` to indicate the user’s consent choice.
`[expiry]`	Number	365	Optional	This is the number of days for which the consent is valid.
`[purpose]`	String /Object	All	Optional	Note: This parameter is deprecated but the existing clients can continue to use it as it is. This can be a comma-separated string or an actual JSON. Examples: • comma separated – ‘purpose_1, purpose_2’; • JSON – `{ purpose_1: true, purpose_2: false}`

The user consent is then stored in cookie storage and used as the user’s consent status for the subsequent event log until a new status is set using the same. The following are the primary consent keys that are accepted in user consent:

Key	Type	Description
`track`	Boolean	If the value of the key is `true`, then you can track any user data
`cookieSync`	Boolean	If the value of the key is `true`, then you can `cookieSync`

Custom Consent can be further categorized into the following:

Basic Consent

Granular Consent

In Basic Consent, the client provides a single consent decision that applies to all SDK purposes. Instead of specifying consent for each individual purpose, the client sets a general consent value as either true (consent granted) or false (consent denied). How It Works:

The setConsent method accepts a boolean value (true or false) to apply to all SDK purposes.
Optionally, the client can specify a duration (in days) for how long the consent remains valid.
Additionally, the client can pass a purpose-specific consent object, where individual purposes can be explicitly set.

Example for Basic Consent:

Code

setConsent({track: true, cookieSync: true}) //provides primary consent values only
setConsent({track: true, brand1Consent: true}) //provides primary consent as well as brand consent


#Deprecated
setConsent(true) // Grants consent for all purposes  
setConsent(true, 365) // Grants consent for all purposes, valid for 365 days  
setConsent(true, 365, { p1: true, p2: false }) // Grants consent for all, with specific overrides  

Note:Granular consent can be used for all consent strategies, primary consent will only be considered if custom consent strategy is chosen

In Granular Consent, a client provides access to a specific consent signal based on their requirement. The consent is passed in the form of a JSON object. Granular Consent has the following consent signals:

Track – This consent signal is used to track and record user activities. Any consent cookie created to store consents can use this permission, as it precedes all other data collection.
Cookie Sync – This consent signal is used to perform cookie sync with the configured advertising partners by firing cookie syncs of the configured Channels. If this signal is set to false, then cookie syncing does not take place.

In granular consent, you can provide access to one or more consent signals. For example, of all the three consent signals you may provide access to Tracking and Cookie Sync but not for Identification. The consent is passed in the form of a JSON value with the particular signal marked as true or false. Going by the above example, the JSON would be set to true for Tracking and Cookie Sync and false for Identification. Example for Granular Consent:

Code

setConsent({track: true, cookieSync: false, p1: true, p2: false})

Recommended Format to call `setConsent` Method

While the above formats are supported, we recommend to call the setConsent method in the following format, which allows you to send Brand Consent along with Primary Consent fields (track, cookieSync):

Code

setConsent({track: true, cookieSync: true, brandConsent: true})

Additional `init()` Properties

In this section, you can find information about all the options available in the system while initialising the SDK. Add the available options in the following format:

Code

init('write_key', {optOut:true, cookieSync:false, ...})

Parameter	Type	Default	Description
`apiKey`	String		This is the API key for the Source. Log into Sources, click on aparticular source and access the key from the IMPLEMENTATION DETAILS section.
`[options]`	String		These options can be passed during initialisation.
`[options.allowCookieSync]`	Boolean	`true`	This option allows cookie syncing with pre-configured channels when set to `true` with a daily cap.
`[options.optOut]`	Boolean	`false`	This option gives the signal on whether the SDK is allowed to record events or not. If set to `true` no events are posted to the backend. This option is then used as a fallback when user consent is not specified.
`[options.useConsent]`	Boolean	`false`	If this option is set to `true`, then the SDK waits to receive a consent signal and uses that consent to manage actions. This consent signal is determined by options: `checkForCMP`.
`[options.checkForCMP]`	Boolean	`true`	If this option is set to `true`, then we check for the presence of the `__cmp` variable in the global scope and the `cmp.js` script. If the `__cmp` variable is present, then we query the CMP API and check for the Publisher’s consent.If this option is set to `false`, then we use the set consent signal using the setConsent method.
`[options.user_country]`	String	null	This option must be set in alpha-iso3 codes, which can then be sent with every request as `user.user_country`. The API defaults the IP to determine the country if the user country is missing. This determines the region where the data is stored.
`[options.storageExpirationDays]`	String	365	We use `cookieStorage` for default user identification and custom consent. This option is used to set the expiry for these cookies.
`[options.domain]`	String	TopLevelDomain	If this option is specified, cookies are stored against the mentioned domain. By default we save all cookies against the top level domain of the current host name. Example – For www.abc.zeotap.com all the cookies are saved against the .zeotap.com domain. This allows all cookie storage to be available for the sub-domain as well as for the top level domain.
`[options.onlySecureCookie]`	String	`true`	We recommend that you do not change this option. This option sets the secure cookies.
`[options.eventUploadThreshold]`	Number	1	This is the maximum number of events that are allowed to remain in the unsent queue when scheduling an event. If the events exceed this threshold, then the next batch is dispatched immediately.
`[options.uploadBatchSize]`	Number	1	This is the number of events that must be posted at once in a batch.
`[options.eventUploadPeriodMillis]`	Number	500ms	If the size of the queue is less than the threshold, then the request to post events is scheduled after `eventUploadPeriodMillis`.
`[options.eventRetryDelayMillis]`	Number	500ms	This is the delay in milliseconds that must be added per back off while trying to retry posting of an event.
`[options.maxRetries]`	Number	3	This is the number of retries to be done before dropping the events.
`[options.debug]`	Boolean	`false`	If this option is set to `true`, then no `logEvent` call is made and all the events are logged in the console.
`[options.allowGAClientId]`	String	`true`	If this option is set to `false`, then the Google Analytics Client ID is not forwarded in the POST calls.
`[options.gaClientIdCookiePrefix]`	String	“‘’”	When the cookie prefix for Google Analytics Client ID is set with this, the GA Client ID cookie fetches the name as `'_ga'`. When the cookie prefix for Google Analytics Client ID is set with `<prefix>`, the GA Client ID cookie fetches the name as `<prefix>_ga`. Example – If `options.gaClientIdCookiePrefix = 'client'`, then cookie searched is `'client_ga'`.
`[options.gaUserIdCookieName]`	String	“‘’”	When the cookie name for Google Analytics User ID is set with this, the GA User ID cookie fetches the name as `'value'`. Example – If `options.gaUserIdCookieName` is set to `userIdCookie`, then the cookie fetched is `userIdCookie`.
`[options.gaUserIdOnlyLoginEvent]`	String	`false`	If this option is set to `false`, then the GA User ID is sent in all event calls. However, if this option is set to `true`, then the GA User ID is sent on `setUserIdentities`.
`[options.areIdentitiesHashed]`	Boolean	`false`	This option indicates whether the identities shared in `setUserIdentities` are hashed or not. This option is applicable only for PII but not `CustomIdentities`.
`[options.hashIdentities]`	Boolean	`false`	This option indicates whether hashing of the raw identities is required or not. This option is applicable only for PII but not `CustomIdentities`.
`[options.persistenceInCookieStorage]	Boolean	`false`	This option indicates whether the SDK stamps consent and identity related data in cookie storage or not. If `false`, data is stamped into session storage.
`[options.includeTCFString]`	Boolean	`false`	This option indicates whether the TCF string is to be passed in the payload. If set to `true`, SDK looks for TCF API and passes the TCF string in the payload. If TCF API is not present on the website, payload doesn’t have TCF string but callsstill go through.

ID5 Integration

To capture the ID5 identifier, you must sign an additional agreement with Zeotap because it involves a third-party tag. Reach out to your Zeotap point of contact (POC) to enable the capture of the ID5 key. Configuration

Step 1: Add the ID5 JavaScript Library

Load the ID5 JavaScript library on the client’s website.
Include the library after the CMP JavaScript and before the Zeotap Collect SDK.

JavaScript

<script src="https://cdn.id5-sync.com/api/1.0/id5-api.js"></script>

Step 2: Add the Zeotap Collect SDK

Include the Zeotap SDK script on the client’s website.
Configure the id5 and id5PartnerID parameters in the SDK configuration.

JavaScript

<script type="text/javascript">
!function(e,t){var n=t.createElement("script");
n.type="text/javascript",n.crossorigin="anonymous",n.async=!0,
n.src="https://content.zeotap.com/sdk/zeotap.min.js",
n.onload=function(){};var s=t.getElementsByTagName("script")[0];
s.parentNode.insertBefore(n,s);
function o(e,t,n){function s(t){e[t]=function(){
e[n].push([t].concat(Array.prototype.slice.call(arguments,0)))}}
for(var o=0;o<t.length;o++)s(t[o])}
var r=e.zeotap||{_q:[],_qcmp:[]};o(r,["init","setEventProperties",
"setUserProperties","setPageProperties","setMetaProperties","setUserIdentities",
"unsetUserIdentites","setZI"],"_q"),o(r,["setConsent",
"addAskForConsentActionListener"],"_qcmp"),e.zeotap=r}(window,document);
</script>
<script type="text/javascript">
window.zeotap.init("your write key",
{userConsent: true, checkForCMP: true, id5: true, id5PartnerID: <id5 partnerid>});
</script>

Step 3: Transmit the ID5 Identifier to Zeotap

Include the encrypted ID5 user ID in the event record under the user identity JSON.
Transmit the event record to Zeotap.
Use the ID5 decryption keys, fetched from the ID5 Decryption API, to decrypt and log the ID5 user ID on the Zeotap platform.

Partner ID Sync

In order for the first-party data to be extensible across the different integrated channels, you have to enable identity syncing and enable cross-channel user identification. Below are a few options for enabling the same.

Note:The partner ID Sync details need to be sent as a part of init function.

You can enable or disable cookie syncs with Zeotapʼs integrated channels by setting the options for the same to true or false. These channels are configured at the time of configuring the Zeotap account. You can also tie this to specific consents in the case of custom consent such that you only switch this to true when users consent to advertise and switch it off to allow only data collection when users consent only to functional cookies.

Parameter	Type	Default	Description
`[options.cookieSync]`	Boolean	`true`	If this option is set to `true`, then cookie sync takes place.

Google Analytics ID

Enable the options mentioned below in your SDK, if you want the SDK to pick the Google Analytics Client ID to set exports from your Zeotap CDP account to your Google Analytics account or Optimise 360.

Parameter	Type	Default	Description
`[options.allowGAClientId]`	String	`true`	If this option is set to `false`, then the Google Analytics Client ID is not forwarded in the POST calls.
`[options.gaClientIdCookiePrefix]`	String	–	This is the cookie prefix for Google Analytics Client ID cookie name. • If set as `'value'`, then the Client ID cookie searched for is ‘`value_ga`’. •If set as empty, then the Client ID cookie searched for is `'_ga'`.
`[options.gaUserIdCookieName]`	String	–	This is the cookie name for Google Analytics User ID. • If set as `'value'`, then we search for the cookie name `'value'` for GA User ID. • If set blank, then the User ID is not picked up.
`[options.gaUserIdOnlyLoginEvent]`	String	`false`	If this option is set to `false`, then the Google Analytics User ID is sent in all the event calls. If this option is set to true, then the Google Analytics User ID is sent only in the `setUserIdentities` calls.

Troubleshooting

The following table provides information on the potential issues that might come up while implementing the Web SDK and their associated troubleshooting steps:

Issue Description	Troubleshooting Steps
The calls are not routing to Zeotap.	Verify the proper execution of the initialization (init) function with appropriate settings and options to enable call routing.
Init is executed. However the calls are still Inactive.	Ensure the accurate implementation of the Transparency and Consent Framework (TCF) on your website.
Init Executed. However the calls are still Inactive (Custom).	If employing a custom consent strategy, ensure the invocation of the `setConsent` function, as it is mandatory for the call flow.
Issue with checking errors and logs.	Activate the debug option in init options to view logs and warnings in the console for error identification.
Failure to hash the PII data.	- Validate the selection of correct PII handling options within the init configuration. - Review the list of permitted PII elements eligible for hashing.

Additional Features & Capabilities

AMP Pages Support

Accelerated Mobile Pages (AMP) is a technique for developing fast-loading web pages that primarily serve static content. AMP aims to enhance the user experience on mobile devices by optimizing web pages for rapid loading and smooth performance. It achieves this through a combination of streamlined HTML, JavaScript and caching strategies. AMP is particularly beneficial for content publishers and website developers who seek to ensure that their web pages load swiftly and efficiently on mobile devices, ultimately improving user engagement and site accessibility.

Integrate the AMP Library

To integrate the SDK into an AMP Page, use the <amp-script> tag to identify a script positioned at your project level. This script includes the zeotap SDK <init> script to facilitate SDK initialization. Additionally, the script includes functions that can receive input, process it based on requirements and then invoke the relevant zeotap SDK functions. Note that you have the flexibility to implement the script differently if needed.

Code

!function(e, t) {

    var n = t.createElement("script");

    n.type = "text/javascript";

    n.crossorigin = "anonymous";

    n.async = !0;

    n.src = "https://content.zeotap.com/sdk/qa/zeotap.min.js";

    n.onload = function() {};

    var s = t.getElementsByTagName("script")[0];

    s.parentNode.insertBefore(n, s);

    function o(e, t, n) {

        function s(t) {

            e[t] = function() {

                e[n].push([t].concat(Array.prototype.slice.call(arguments, 0)));

            }

        }

        for (var o = 0; o < t.length; o++) s(t[o]);

    }

    var r = e.zeotap || { _q: [], _qcmp: [] };

    o(r, ["init", "setEventProperties", "setUserProperties", "setPageProperties", "setMetaProperties", "setUserIdentities", "unsetUserIdentities", "setZI"], "_q");

    o(r, ["setConsent", "addAskForConsentActionListener"], "_qcmp");

    e.zeotap = r;

}(window, document);

window.zeotap.init("<wk>");

You can add additional functions to the same script as shown below.

Code

function setZeotapEventProperties(eventName, eventProperties){

    zeotap.setEventProperties(eventName, eventProperties);

}

function setZeotapUserIdentities(userDetails) {

    zeotap.setUserIdentities(userDetails);

}

function setZeotapPageProperties(pageDetails) {

    zeotap.setPageProperties(pageDetails);

}

function setZeotapUserProperties(userProperties) {

    zeotap.setUserProperties(userProperties);

}

Next, you have to name the script as zeotapSDKSetup.js and integrate it with your amp.html page. To do so, include the following script tag in the <header> of your page to fetch the amp-script component:

Code

<script async custom-element="amp-script" src="https://cdn.ampproject.org/v0/amp-script-0.1.js"></script>

Further to it, add an additional script tag to load the zeotapSDKSetup.js script and give it an ID reference as shown below. For example, zeotap-js and the target is amp-script.

Code

<script id="zeotap-js" src="zeotapSDKSetup.js" target="amp-script"></script>

After adding the script tags to the <head> tag of your website, use the <amp-script> tag within the <body> to incorporate your script into the page as below.

Code

<body>

  <amp-script script="zeotap-js">

    <!-- Your page code here -->

  </amp-script>

</body>

Then, you can start using the functions defined in zeotapSDKSetup.js or directly employ zeotap SDK functions in your AMP page. Below is an example of how to use a function within your page.

Code

<body>

  <amp-script script="zeotap-js">

    <button 

    type="button" 

    onclick="setZeotapEventProperties('addToCart', {'product': 'handbag'})">

    Add to Cart

    </button>

  </amp-script>

</body>

This triggers the setEventProperties function of the SDK with eventName as ‘addToCart’ with properties as product: ‘handbag’.At this point, you can start tracking activities such as page views and other user actions as outlined below.

AMP Page Tracking

You can log the users’ page view events by calling setPageProperties and sending all page related information as key=value properties on the page load event. All further user events on the same page are then attached with these page properties.

Parameter	Type	Description
`properties`	Object	This indicates the page specific properties.

Below is an example showing how to capture user viewing a Product page:

Code

zeotap.setPageProperties({name: 'Product'})

This example creates the following payload:

Code

{
  "event": {
    "eventName": "pageView",
    "eventTimestamp": 1584350000
  },
  "page": {
    "name": "Product Page",
    "url": "https://www.xyz.com/products",
    "path": "/products"
  },
  "User": {
    "zi": "user_123",
    "zs": "session_123"
  }
}

AMP Event Tracking

Use the setEventProperties method to track different user actions on the website (for example, the selectVariant event with colour as a property) and properties relating to the event (for example, a viewCart event with cartVal as a property).

Parameter	Type	Description
`eventName`	String	This is the name of the event.
`eventProperties`	Object	This is the object containing any properties for a particular event.

Below is an example showing how to track a product being viewed, which can be triggered on the view product event.

Code

zeotap.setEventProperties('view product', {productID: '1234'});

This example creates the following payload:

Code

{ "event":{
"eventName":"viewProduct",
"productID":"prod_123",
"eventTimestamp":1584350000
},
"page":{
"url":"https://www.xyz.com/products/?pid=prod_123",
"path":"/products/?pid=prod_123"
},
"User":{
"zi":"user_123",
"zs":"session_123"
}
} 

For information on consent tracking capabilities within AMP, refer here.

Best Practices

This section describes the best practices and recommendations that must be considered when using Web JS Source. If your website has a TCF API on the page, then the consent resolution mechanism must be TCF and not the default Optin. This helps the Zeotap SDK to also capture the gdpr_consent string. In some cases, you may set up a default consent resolution mechanism and invoke the Zeotap JavaScript only if the user performs any action on the CMP. However, note that we do not recommend this step. Even when you invoke the SDK with the TCF Consent Configurations, the JS communicates with the TCF API on the page and only then the JS collects/captures the events. Otherwise, the JS just sits idle. We recommend the following SDK configurations for the above scenario:

Code

{

useConsent: true,

checkForCMP: true

}

If you are setting up a Custom Consent collection on your website, ensure that you also choose the same in the SDK configurations. This is required in order to collect granular consent from the website. The SDK primarily performs the following three main tasks:

Capture user events
Identify user
CookieSync

With the custom consent resolution mechanism, you can provide granular consent instead of a blanket boolean (yes/no) for all SDK purposes. We recommend the following SDK configurations for the above scenario:

Code

{

useConsent: true,

checkForCMP: false

}

After you have set up the SDK configurations, you can invoke the setConsent method as mentioned below.

window.zeotap.setConsent({ track: true, cookieSync: true })

Capturing User Identities

With Collect SDK, you can collect User Identities (PIIs like email and cellphone number along with Custom Identities). The identities collected are then persisted across all the upcoming event-capturing calls. To persist user identities across the event payloads, invoke the setUserIdentities method and not the setUserProperties method. In order to persist user identities, you can use the setUserIdentities method as follows:

Case 1: Incoming identities are raw and can be sent to Zeotap CDP as is

SDK Configurations:

Code

{

areIdentitiesHashed: false,

hashIdentities: false

}

setUserIdentities method:

window.zeotap.setUserIdentities({

email: 'xyz@gmail.com', // User PII

crmID: '12345' // Custom Identity

})

Case 2: Incoming identities are raw and need be sent to Zeotap CDP after hashing

SDK Configurations:

Code

{

areIdentitiesHashed: false,

hashIdentities: true

}

setUserIdentities method:

window.zeotap.setUserIdentities({

email: 'xyz@gmail.com', // User PII, will be hashed

crmID: '12345' // Custom Identity, consumed as is

})

Case 3: Incoming identities are hashed

SDK Configurations:

Code

{

areIdentitiesHashed: true

}

setUserIdentities method:

window.zeotap.setUserIdentities({

email_sha256_lowercase: '32e19a491662fd86de7d3806b1199b76f0ee44e928d3475f05b0c8a59912c097',

crmID: '12345' // Custom Identity, consumed as is

})

Google Analytics Settings

With the Collect SDK, you can provision optional capturing of the GA client Id and user Id cookies for retargeting purposes on platforms like Optimize 360. To allow the SDK to capture the GA cookies, add the following configurations to the window.zeotap.init(WRITE_KEY, { .... }) call:

Code

{

//If set to false , Google Analytics ClientId will not be forwarded in POST calls allowGAClientId: true,

// cookie prefix for Google Analytics Client ID, if set with <value>, GA Client Id cookie fetch with name as '<value>_ga' gaClientIdCookiePrefix: 'client',

// cookie name for Google Analytics User ID, if set with <value>, GA User Id cookie fetch with name as 'value' gaUserIdCookieName: 'user_ga'

}

Contextual Information

Zeotap records additional information relating to an event triggered or a page being loaded and then supplements details to the data point being captured. The following are the contextual information that Zeotap captured:

IPAddress-derived – IPCountry, WiFi/Cellular, Operator/Carrier
UserAgent-derived – deviceOS, device model, device manufacturer, device type, browser type
pageURL-derived – URL, domain, path

​Latest Version

​Overview

​Prerequisites

​Get Started

​Step 1 – Create a Web JS Source

​Step 2 – Add the JS Snippet

​Step 3 – Tracking Methods

Set Page Properties

Set Event Properties

Set User Properties

Set User Identities

Unset User Identities

Track User Consent

​Set Page Properties

​Set Event Properties

​Set User Properties

​Set User Identities

​Personal Identifiable Information (PII)

​Raw User PII

​Hashed User PII

​Custom Identities

​Unset User Identities (Log out communication)

​Track User Consent

​Default Opt-in

​GDPR TCF CMP

​Custom Consent

​Call the setConsent Method

​Keys for Primary Consent

​Categorisation of Custom Consent

Basic Consent

Granular Consent

​Basic Consent

​Granular Consent

​Recommended Format to call setConsent Method

​Additional init() Properties

​ID5 Integration

​Step 1: Add the ID5 JavaScript Library

​Step 2: Add the Zeotap Collect SDK

​Step 3: Transmit the ID5 Identifier to Zeotap

​Partner ID Sync

​Cookie Sync with Channels

​Google Analytics ID

​Troubleshooting

​Additional Features & Capabilities

​AMP Pages Support

​Integrate the AMP Library

​AMP Page Tracking

​AMP Event Tracking

​AMP Consent Tracking

​Best Practices

​Appropriate Consent Configurations

​TCF Consent

​Custom Consent

​Capturing User Identities

​Case 1: Incoming identities are raw and can be sent to Zeotap CDP as is

​Case 2: Incoming identities are raw and need be sent to Zeotap CDP after hashing

​Case 3: Incoming identities are hashed

​Google Analytics Settings

​Contextual Information

Latest Version

Overview

Prerequisites

Get Started

Step 1 – Create a Web JS Source

Step 2 – Add the JS Snippet

Step 3 – Tracking Methods

Set Page Properties

Set Event Properties

Set User Properties

Set User Identities

Personal Identifiable Information (PII)

Raw User PII

Hashed User PII

Custom Identities

Unset User Identities (Log out communication)

Track User Consent

Default Opt-in

GDPR TCF CMP

Custom Consent

Call the setConsent Method

Keys for Primary Consent

Categorisation of Custom Consent

Basic Consent

Granular Consent

Recommended Format to call `setConsent` Method

Additional `init()` Properties

ID5 Integration

Step 1: Add the ID5 JavaScript Library

Step 2: Add the Zeotap Collect SDK

Step 3: Transmit the ID5 Identifier to Zeotap

Partner ID Sync

Cookie Sync with Channels

Google Analytics ID

Troubleshooting

Additional Features & Capabilities

AMP Pages Support

Integrate the AMP Library

AMP Page Tracking

AMP Event Tracking

AMP Consent Tracking

Best Practices

Appropriate Consent Configurations

TCF Consent

Custom Consent

Capturing User Identities

Case 1: Incoming identities are raw and can be sent to Zeotap CDP as is

Case 2: Incoming identities are raw and need be sent to Zeotap CDP after hashing

Case 3: Incoming identities are hashed

Google Analytics Settings

Contextual Information