Important Notice:If the new architecture is enabled in a React Native application, use SDK version 1.3.0 or higher with the required new architecture configurations. If you experience issues with a higher version, contact our support team at support@zeotap.com.
Latest Version
1.3.3Overview
React Native is a popular JavaScript framework for building mobile applications. It allows developers to write code once and deploy it on multiple platforms, such as iOS and Android. This section addresses the integration of the zeo-collect package into your React Native project, the setup of Android and iOS SDKs and the configuration of the package to receive events.Get Started
To start with, you have to create Android and iOS sources in the Collect application within Zeotap and obtain thewrite_keys for the same. Once done, you can then integrate the zeo-collect package into your React Native project as follows:
- Integrate the
zeo-collectPackage - Set up Zeotap Android SDK
- Set up Zeotap iOS SDK
- Configure the React Native Package
- Send Events to Zeotap
Step 1 - Integrate zeo-collect Package
Perform the following steps to integrate the zeo-collect package into your React Native project:
Step 2 - Set up Zeotap Android SDK
Next, you have to set up theZeotapCollect Android SDK using the Dependency Manager. To do so, perform the following steps:
Note:The Android SDK version and the
Gradle tool version mentioned in the integration steps are for reference purposes only. Ensure to use the latest version during the setup process.At the project level of the
build.gradle file or settings.gradle file
(Project root > build.gradle or Project root > settings.gradle),
add the Maven URL given below in the repositories block:Code
In the app level
build.gradle file (Project root > app > build.gradle), add the following in the dependencies block:Code
If you have obtained the b. For applications targeting Android versions lower than 13, the SDK automatically retrieves the
AdID yourself, then you can use the setAdID method to apply it. However, if you prefer the SDK to retrieve the AdID, then perform the following steps:a. For applications targeting Android version 13 or higher, include the following dependency in the app-level dependency block:AdID on its own.Ensure that you add following dependency in app level dependency block, if you are not using json dependency in your project.
Step 3 - Set up iOS SDK
Next, perform the following steps to set up theZeotapCollect iOS SDK using Cocoa Pods:
Note:To ensure whether CocoaPods is installed in your system or not, follow the instructions below:
- To check if CocoaPods is installed, run the command
pod --version. With CocoaPods installed, you can see the version number displayed, as shown in the image below. - If CocoaPods is not installed, then you can add it to your project by following the instructions at https://guides.cocoapods.org/using/using-cocoapods.html.
ZeotapCollect iOS SDK:
Navigate to the iOS directory within your project and execute the command
cd ios to access the iOS folder from the project root:Step 4 - Configure the React Native Package
Once you have successfully set up Zeotap Android and iOS SDKs, you can configure the React Native package by performing the following steps:- Initialise the
Zeo-collectpackage by passing the options object in the initialiseZeoCollect function. Note that the options object must include the required package options (settings) as key-value pairs. The function also accepts an optional callback parameter, which receives a data object containing{status, message}and executes the implementation. - Invoke the
initialiseZeoCollectfunction from your app’s entry point, within theuseEffecthook in theApp.jsfile as shown in the example below.
Code
Note:Ensure that the key names are used exactly as provided in the table below. Note that the
write_keys are of the data type String only.zeo-collect package:
| Key Name | Value Data Type | Description |
|---|---|---|
android_write_key | String | This is the Android write key generated after you create an Android source. |
ios_write_key | String | This is the iOS write key generated after you create an iOS source. |
batch_size | Integer | This is the maximum number of events allowed to remain in the unsent queue when scheduling an event. If the event exceeds this threshold, then the next batch is dispatched immediately. The default value is 30. The minimum value for the batch size is 10 and the maximum value can be 50. |
service_interval | Integer | This is the time interval for scheduling events. If the size of the queue is less than the threshold, then the request to post events is scheduled after the service interval. The default value is 90 seconds. |
max_cache_size | Integer | This is the maximum number of events allowed to be stored in the local memory in case of network issue or delayed consent. The default value is 100 and the maximum value can be 200. |
opt_out | Boolean | This option acts as a fallback when consent is not used. If set to true, then no events are posted to Zeotap. The default value is false. |
use_consent | Boolean | This option manages actions based on the based on received consent. |
check_for_cmp | Boolean | This option manages consents based on the CMP data. If check_for_cmp is set to true along with use_consent, then you can look for CMP data stored by other CMPs. Subsequently, you can manage consents based on this CMP data. |
are_identities_hashed | Boolean | This option indicates whether the identities shared in setUserIdentities are hashed or not.The default value is false. |
hash_identities | Boolean | This option indicates whether or not the hashing of the raw identities is required. The default value is false. |
check_zeotap_vendor_consent | Boolean | If this option is set to true, then the package checks for Zeotap Vendor consent, while resolving GDPR consent to send the data. If set to false, then the package ignores the Zeotap Vendor consent.The default value is false. |
logging | Boolean | If set to true, then it displays the info, debug, warning and error log severity levels. Otherwise, it only displays the warning and error log severity levels. |
purposes_for_tracking | List/Array of Integers | This option is used to pass a list of purpose IDs, based on which you can manage the consent for tracking. 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. |
purposes_for_identify | List/Array of Integers | This option is used to pass a list of purpose IDs, based on which you can manage the consent for identification. To know more about the purposes for identification and the associated IDs, refer to the “Appendix A: Purposes and Features Definitions” section of this topic. |
user_country | String | This option determines the region where the data is stored. Note that you have to set this in alpha-iso3 codes. The API defaults the IP to determine the country if the user country is missing. |
Step 5 - Send Events to Zeotap
Perform the following steps to send events to Zeotap using thezeo-collect package:
Note:Ensure to replace the placeholders such as name, description, price and more with actual variables containing the relevant data you wish to send with the events. The functions of the
zeo-collect package allow you to capture and transmit event-specific information to Zeotap for analysis and tracking.- Using the
setEventNamePropertiesfunction:
Code
- Using the
setEventPropertiesfunction:
Code
- Using the
setEventPropertiesfunction along with other methods:
Code
Methods Available in the zeo-collect Package
The following methods are available in the zeo-collect package:
| METHODS | PARAMETERS AND FUNCTIONS USAGE | DESCRIPTION |
|---|---|---|
| setEventNameProperties | @param {string} eventName@param {callback} cbsetEventNameProperties(eventName, cb)Example import {setEventProperties} from 'zeo-collect'...setEventNameProperties("eventName", (res) => {}) | This method is used to send an event to Zeotap with the provided event name. A callback can be added to revise response from the function. |
| setEventProperties | @param {string} eventName@param {jsonObject} eventProperties@param {callback} cbsetEventProperties(eventName, eventProperties, cb)Example import {setEventProperties} from 'zeo-collect'...eventProperties = {prop1: value1, prop2: value2}setEventProperties("eventName", eventProperties, (res) => {}) | This method is used to send an event to Zeotap along with the specified event properties and name. |
| setInstantEventNameProperties | @param {string} name@param {callback} cbsetInstantEventNameProperties(name, cb)Exampleimport {setInstantEventNameProperties } from 'zeo-collect'...setInstantEventNameProperties("eventName", (res) => {}) | This method immediately sends an event with the given event name, without waiting in the queue to be sent as a batch. |
| setInstantEventProperties | @param {string} eventName@param {jsonObject} eventProperties@param {callback} cbsetInstantEventProperties(eventName, eventProperties, cb)Exampleimport {setInstantEventProperties } from 'zeo-collect'...eventProperties = {prop1: value1, prop2: value2}setInstantEventProperties("eventName", eventProperties, (res) => {}) | This method immediately sends an event with the given event name and event properties, without waiting in the queue to be sent as a batch. |
| setUserProperties | @param {jsonObject} userProperties@param {callback} cbsetUserProperties(userProperties, cb)Exampleimport {setUserProperties } from 'zeo-collect'...userProperties = {prop1: value1, prop2: value2}setUserProperties(userProperties, (res) => {}) | This method sends an event with the given user properties along with default user properties. You can use setUserProperties to override the existing user properties. |
| setPageProperties | @param {jsonObject} userProperties@param {callback} cbsetPageProperties(pageProperties, cb)Exampleimport {setPageProperties } from 'zeo-collect'...pageProperties = {prop1: value1, prop2: value2}setPageProperties(pageProperties, (res) => {}) | This method sends an event with the given page properties. Note that all the subsequent events will include a page node with these page properties. You can use setPageProperties to override the existing page properties. |
| setUserIdentities | @param {json [string: string]} userIdentities``@param {callback} cbsetUserIdentities(userIdentities, cb)Exampleimport {setUserIdentities } from 'zeo-collect'...userIdentities = {prop1: value1, prop2: value2}setUserIdentities(userIdentities, (res) => {}) | This method sends an event with the provided user identities. Note that all the subsequent events will include a user node with these user identities. |
| unSetUserIdentities | unSetUserIdentities()Example import {unSetUserIdentities } from 'zeo-collect'...unSetUserIdentities() | This method is used to remove user identities that are set using the setUserIdentities method. |
| pauseCollection | pauseCollection()Exampleimport {pauseCollection } from 'zeo-collect'...pauseCollection() | This method is used to temporarily suspend the package from collecting events for the user’s actions. |
| resumeCollection | resumeCollection()Exampleimport {resumeCollection } from 'zeo-collect'...resumeCollection() | This method restarts event collection in the package if it was previously paused using the pauseCollection() method. |
| setConsent | @param {jsonObject} consentData@param {callback} cb``setConsent(consentData, cb)Example import {setConsent } from 'zeo-collect'...setConsent(consentData, (res) => {}) | This method sets consent in the non-TCF Consent Management Platform included in the package. It also allows passing brand consent to persist forthe user. Additionally, it supports an optional callback function. |
| listenToAskForConsent | @param {Function} callbacklistenToAskForConsent(callback)Example import {listenToAskForConsent} from 'zeo-collect'...listenToAskForConsent(callback) | This function includes a callback that is triggered when the package encounters a consent resolution issue. You can provide a UI callback function as an argument to gather user consent, which can then be set through the setConsent(consentData)function. Note that it is applicable only for custom consent. |
Verify Connection
Upon successful integration, send some events through your app to verify the connection. Once the connection is established and tested, log in to the Zeotap CDP App and navigate to the particular Android or iOS source that you have created and view the data in the PREVIEW tab.Track Page Views
After integrating the package, you can log the users’ page view events by calling setPageProperties({ prop1: value1, prop2: value2 }) 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.
| Function | Parameter Type | Description |
|---|---|---|
| setPageProperties | Object with key as String and value as Any. {String: Any} | This function allows you to specify properties unique to a particular page. |
Code
Note:If the page properties are not defined, then by default, no page property is available on an event payload.
Track User Actions
After tracking the page views, you can start tracking the events. Use thesetEventProperties method to track different user actions on the Application (for example, the selectVariant event with colour as a property) and properties relating to the event (for example, a ViewProduct event with productName, color as a property).
Note:If you need to track only event name, then you can use
setEventNameProperties method.| Function | Type | Description |
|---|---|---|
setEventNameProperties | String | This is the name of the event. |
setEventProperties | Object with key as String and value as Any {String: Any} | This is the object containing any properties for a particular event. |
- System Events
- Custom Events
Note:This granular level of tracking has been enabled since May 14, 2024. Any system event tracked before this date is tagged with the common name SystemEnrichmentEvent which could have been triggered by any of the scenarios listed below.
| Event Name (Tags) | Scenarios |
|---|---|
| Set consent | Triggers the first time a user lands on the app and sets consent |
| Update consent | Triggers when a user changes their consent |
| Set identities | Triggers when a user logs in |
| Update identities | Triggers when a user changes already set identities |
| Event Name (Tags) | Scenarios |
|---|---|
| Add to cart | Triggers when a user adds an item to their shopping cart |
| Remove from cart | Triggers when a user removes an item from their shopping cart |
| Complete purchase | Triggers when a user completes a transaction |
Code
Code
Code
Identify Default Users
The package creates an ID calledzi for user identification. This ID is attached to all the event calls from the package, such as page views and user events. This ID is unique per the application.
UserDefaults is utilised for storing these IDs with an encrypted key that is derived from the <write_key>.
The zi ID is unique to each instance of the package that is write key based. The table below explains certain features available in the package regarding the zi ID.
| Function | Description |
|---|---|
getZI | This is the method to get the zi value. |
resetZI | This is the method to reset the zi value for a user. You can. |
Capture Users Properties
You can use the setUserProperties method to attach user information for a known user who is using the Application. The user information is as follows:- DB ID for the user (recommended)
- Any additional information about the user that you want to identify as a user attribute
setUserProperties(properties) where properties is an object containing user identifiers and attributes that are sent as key=value properties to package events.
Below is an example showing how to add user attributes of the user visiting the app:
Code
Note:The records for the country and city columns are blacklistedfor 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.
Capture User Identities
ThesetUserIdentities method identifies the object that is set by the user and saved in the user storage. The following are the keys that are accepted in user Identities:
| Name | Type | Description |
|---|---|---|
email | String | This is the email address of the user. |
loginid | String | This is the login id of the user. |
cellno | String | This is the cell phone number of the user. Ensure that you provide the cell phone number in the following format [country_code][space][cell_number]. For example,49 1234567890. We recommend that you always send cell phone number in this format. Do not include ‘+’ while sending the cell phone numbers. |
cellno_cc | String | This is the cell phone number of the user with the country code. We recommend that you do not provide cell phone numbers with country code. |
Code
Raw User Identities
While capturing user identities in the raw form, you may or may not want Zeotap to hash them. Refer to the table below to understand the scenarios, the package options that are involved and a sample to invoke thesetUserIdentities method.
| Scenario | Package Options | setUserIdentities |
|---|---|---|
| You send raw user identities, but do not want Zeotap to hash them. | The following package options are involved in this scenario:"are_identities_hashed": false,"hash_identities": false | let userIdentities = {"email": "test@gmail.com","cellno": "49 1234567890"}setUserIdentities(userIdentities); |
| You send raw user identities and want Zeotap to hash them. | The following package options are involved in this scenario:"are_identities_hashed": false,"hash_identities": true | let userIdentities = {"email": "test@gmail.com","cellno": "49 1234567890"} setUserIdentities(userIdentities); |
Note:By default, if you want Zeotap to hash to user identities, we hash the raw identities to sha256, sha1 and md5.
Hashed User Identities
You may only send in user identities that are hashed using algorithms likeSHA256, SHA1 and MD5. In this scenario, refer to the table below to understand the scenario, the package options that are involved and a sample for the setUserIdentities property.
| Scenario | Package Options | Description |
|---|---|---|
| You send hashed user identities only | The package option involved in this scenario is "are_identities_hashed": true, | let userIdentities = {"email_sha256_lowercase": "b0492275843c15593bba8a749c3379e3b5067aab173e91fcb37d840ca8b1738d","cellno_with_country_code_sha256":"91-1234890987"}setUserIdentities(userIdentities); |
| Key name | Key and Value Type | Description |
|---|---|---|
email_sha256_lowercase | String | This is the user’s email address hashed to sha256 after converting it to lowercase |
email_sha256_uppercase | String | This is the user’s email address hashed to sha256 after converting it to uppercase |
email_md5_lowercase | String | This is the user’s email address hashed to md5 after converting it to lowercase |
email_md5_uppercase | String | This is the user’s email address hashed to md5 after converting it to uppercase |
email_sha1_lowercase | String | This is the user’s email address hashed to sha1 after converting it to lowercase |
email_sha1_uppercase | String | This is the user’s email address hashed to sha1 after converting it to uppercase |
cellno_without_country_code_sha256“ | String | This is the user’s cell phone number without the country code and hashed to sha256. |
cellno_without_country_code_md5“ | String | This is the user’s cell phone number without the country code and hashed to md5. |
cellno_without_country_code_sha1 | String | This is the user’s cell phone number without the country code and hashed to sha1. |
cellno_with_country_code_sha256“ | String | This is the user’s cell phone number with the country code and hashed to sha256. |
cellno_with_country_code_md5“ | String | This is the user’s cell phone number with the country code and hashed to md5. |
cellno_with_country_code_sha1 | String | This is the user’s cell phone number with the country code and hashed to sha1. |
cellno_e164_sha256“ | String | This is the user’s cell phone number in e164 format hashed to sha256. |
cellno_e164_md5“ | String | This is the user’s cell phone number in e164 format hashed to md5. |
cellno_e164_sha1 | String | This is the user’s cell phone number in e164 format hashed to sha1. |
loginid_sha256_lowercase | String | This is the user’s login ID that is logged. We hash the login ID to sha256 after converting to lowercase. |
loginid_md5_lowercase | String | This is the user’s login ID that is logged. We hash the login ID to md5 after converting to lowercase. |
loginid_sha1_lowercase | String | This is the user’s login ID that is logged. We hash the login ID to sha1 after converting to lowercase. |
loginid_sha256_uppercase | String | This is the user’s login ID that is logged. We hash the login ID to sha256 after converting to uppercase. |
loginid_md5_uppercase | String | This is the user’s login ID that is logged. We hash the login ID to md5 after converting to uppercase. |
loginid_sha1\_uppercase | String | This is the user’s login ID that is logged. We hash the login ID to sha1 after converting to uppercase. |
Note:To know about the hashing guidelines for email and cell phone numbers, refer here.
Set Events With Callback Function
You can also set events with Callback function as shown below. Note that thedata parameter is an object that contains status and message.
Code
Note:For more information about the
Callback function status codes and errors, refer here.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 and then remove identities. Call the following method:unSetUserIdentities()
Send User Profile Information
If you have any other information you want to send about the user on the app, you can send the same using setUserProperties. This is sent to the API with the default user zi ID, along with any other identities set using setUserIdentities. Below is an example showing how to pass the user profile information:Code
Code
Track User Consent
The consent that you provide is used for the following two primary purposes:- User identification
- Tracking user data
Default Opt-in
In this scenario, you directly provide consent to Zeotap by setting theopt_out flag to true or false.
For all these three purposes, if the opt_out flag is set to true, then it indicates that you have not granted access to Zeotap. Here, package is not allowed to perform user identification or tracking user data. However, if the opt_out flag is set to false, then the package is allowed to perform all the above actions.
| key name | Type | Value | Description |
|---|---|---|---|
| opt_out | Boolean | false | This is an explicit consent signal that you set. When enabled, the package can perform user identification and event capturing. |
| opt_out | Boolean | true | This is an explicit consent signal that you set. When disabled, the package cant perform user identification and event capturing. |
GDPR TCF CMP
If you already have a TCF 2.0 Consent Management Platform (CMP) implemented on your app, then the package automatically checks for the same. To do this, both theuse_consent and check_for_cmp flags are set to true. The package also queries the TCF consent string to fetch the Publisher’s consent before recording the events.
The below table describes the keys/parameters that need to be configured while using the GDPR consent module in package options.
| key name | Type | Value | Description |
|---|---|---|---|
use_consent | Boolean | true | If this option is set to true, then the package waits to receive a consent signal and uses that consent to manage actions. |
check_for_cmp | Boolean | true | If this option is set to true, then we check for the presence of the TCF 2.0 variables in the UserDefaults. If the TCF 2.0 variables are 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. |
check_zeotap_vendor_consent | Boolean | true or false | If this option is set to true, then the package checks for Zeotap Vendor consent, while resolving GDPR consent to send the data. If set to false, then the package ignores the Zeotap Vendor consent. By default, check_zeotap_vendor_consent is set to false. |
purposes_for_tracking | [number] | default = [1, 3, 4] | This option is used to pass a list of purpose IDs, based on which you can manage the consent for tracking. To know more about the purposes for tracking and the associated IDs, refer to the “Appendix A: Purposes andFeatures Definitions” section of this topic. |
purposes_for_identifying | [number] | default = [1, 9] | This option is used to pass a list of purpose IDs, based on which you can manage the consent for identification. To know more about the purposes for identification and the associated IDs, refer to the “Appendix A: Purposes andFeatures Definitions” section of this topic. |
Custom Consent
You may not want to explicitly give consent or even use the TCF API. Instead, they may want to have a custom consent flow. The following three points summarize this scenario:- The
use_consentflag is set to true - The
check_for_cmpoption is set to false - The
setConsentmethod is used to resolve the user consent
| Name | Type | Description |
|---|---|---|
| track | boolean | If this option is set to true, then you can track any user data. |
| identify | boolean | If this option is set to true, then it allows to identify you and a user. |
- 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.
- identify – This consent signal is used for user matching and third-party enrichment(for example, zcookie and ID+ permissions).
setConsent method as mentioned below:
Code
Code
Track Brand Consent
Use thesetConsent method to store brand-specific consent, such as zeotapVendorConsent or xyzVendorConsent, and ensure it persists across all events.
Example
JavaScript
Note:For consent types other than custom consent, the
track and identify flags are ignored because the consent configuration differs.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:- Device Id/iOS id
- Telco carrier, Network type, OS Version
- DeviceManufacturer
- DeviceModel
- DeviceVersion
- ClientAppName and ClientAppVersion
Capture Advertising ID in iOS
The zeo-collect package automatically collects the Identifier for Advertisers (IDFA) from the user’s device, if the iOS version is 13 or lower. This is then passed in the event payload as advertising_id. However, in the case of iOS 14 or higher, the package does not collect the IDFA automatically due to Apple’s latest privacy guidelines. For more information about Apple’s User privacy and data use guidelines, refer here.Collect the Identifier for Advertisers (IDFA)
You can include the Identifier for Advertisers (IDFA) in the event payload by using Apple’s App Tracking Transparency (ATT) framework. ATT enables displaying a pop-up to the user, seeking their permission to access the IDFA. Upon receiving a response from the user, the package appends att_authorization_status and advertising_id to the payload. Note that the advertising_id is passed along with the event payload only after att_authorization_status is authorised.Note:For more information about the Apple’s App Tracking Transparency (ATT) framework, refer here.
Set Apple’s App Tracking Transparency (ATT) Status
You can set the Apple’s App Tracking Transparency (ATT) status either from the iOS module or the React Native package as mentioned below.Set ATT Status from iOS Module
You can pass the ATT authorisation status from the iOS module in the following two ways:Note:The options are invoked from the iOS module of your project within Swift/Objective-C files.
setAdvertisingIdByATTStatus- By passingatt_authorization_statusto this function, the package captures the IDFA from the device. Subsequently, transmits the identifier along with its status within the payload.
Code
setATTStatusAndAdvertisingId- This function accepts the ATT authorisation status and IDFA string based on the permission granted. However, If the permission is denied, then you can pass the ATT authorisation status alone to the package.
Code
Set ATT Status from React Native Module
You can pass the ATT authorisation status from the React Native module in the following two ways:setAdvertisingIdByATTStatus– By passingATTStatusto this function, the package retrieves the IDFA from the device and includes the identifier along with its status in the payload.
| Method | Parameter | Description |
|---|---|---|
setAdvertisingIdByATTStatus | @param {string} ATTStatussetAdvertisingIdByATTStatus(ATTStatus) | Use this function to set ATT status from react native module. The parameter in the function is of data type string and the following are the valid entries:
|
Code
setATTStatusAndAdvertisingId- This function requires the ATT authorisation status (in String format) and the IDFA string based on the permission. However, If the permission is denied, then you can pass the ATT authorisation status alone to the package.
| Method | Parameter | Description |
|---|---|---|
setATTStatusAndAdvertisingId | @param {string} ATTStatus@param {string} advertisingIdsetATTStatusAndAdvertisingId(ATTStatus, advertisingId) | Use this function to set ATT status and advertisingId from React Native module.The following are the valid entries for ATTStatus:
|
Code
