This article describes how to use Tealium native mobile libraries (iOS, Android) in your React Native application.
In this article:
Table of Contents Placeholder
How it Works
Tealium for React Native allows you to use the Tealium native mobile libraries (iOS, Android) in your React Native application.
You can integrate Tealium mobile libraries into your React Native application using one of the following two methods:
Automatic Use the NPM package (recommended)
Manual For those with specific requirements. You can find the code on GitHub.
Prerequisites
Access to your native build environments Including the respective libraries for Android and iOS means working with platform-specific (native) code.
React Native and Tools You must have React Native and tools installed, along with native dependencies, such as Android Studio, Xcode, and other tools for developing mobile apps using React Native.
Related Tealium Documentation As you will be working with the Tealium native mobile libraries, this guide references links to other relevant Tealium documentation, such as the Tealium for Android and Tealium for iOS guides.
Core Library The Core library is required. If you want to track lifecycle events, the lifecycle module is also needed. These libraries are both available from the Tealium GitHub repository for iOS. There are two versions of each module: one for publishing to the App Store and one that includes the ability to run the application on a simulator (which cannot be published to the App Store). When working on your own application with intent to publish to the App Store, make sure that you use the frameworks in the devices only folder.
Installation via NPM
To install, you must first download React Native and the native dependencies, as follows:
From the root of your React Native project, run the following command to download the tealium-react-native package and install it to your project:
npm install tealium-react-native
Next, run the following command to link the native dependencies within the module to your main React Native app so that it can build against the module:
react-native link
Android
After downloading React Native and the native dependencies, your Android application should build and work without issues.
At Tealium, we prefer to build using the Integrated Development Environment (IDE) as we have found it to be more reliable. If it works best for your worklfow, you can start applications from the Command Line Interface (CLI) if it works better for your workflow.
iOS
The following additional steps are required for your iOS application:
Obtain a copy of the following two Tealium native libraries for iOS.
TealiumIOS.framework
TealiumIOSLifecycle.framework
Drag the frameworks into the Libraries folder in your Xcode project.
From there, drag them into the Embedded Binaries section under the General tab of your target. See Adding Tealium to Your iOS App for information about how to add the frameworks to your Xcode project.
Under Libraries , go to the TealiumModule.xcodeproj folder.
Go to the Products folder.
Locate the libTealiumModule.a file.
Under the Build Phases tab of your target, locate the Link Binary With Libraries section.
Drag the libTealiumModule.a file to the Link Binary With Libraries section. Your iOS application should now build and run.
For additional information about linking libraries, see the React Native documentation.
Manual Installation and Setup
This section contains two separate sections on how to install and set up manually for Android and for iOS.
Android
Use the following steps for a manual installation for Android:
To integrate Tealium into your Android application, you first need to add the Tealium maven repository, as follows:
allprojects { repositories { jcenter() maven { url "http://maven.tealiumiq.com/android/releases/" } } }
Add the Tealium core library dependency to your project module build.gradle file. If you will be tracking lifecycle events, add the optional Tealium lifecycle dependency in this step.
dependencies { compile 'com.tealium:library:5.5.2' compile 'com.tealium:lifecycle:1.1' // <--- Add if tracking lifecycle events }
Copy the bridging logic, as follows:
From the Android folder, add TealiumModule.java and TealiumPackage.java into your project files.
Include TealiumPackage into the getPackages() method of your MainApplication.java file, as shown in the following example:
@Override Protected List getPackages() { return Arrays.asList( new MainReactPackage(), new TealiumPackage() // <--- Add TealiumPackage ); }
iOS
Adding Tealium for iOS to a React Native project uses the same steps for a non-React Native application (with the exception of the bridging files). For complete details, see Adding Tealium to Your iOS App.
The Core library is required. The lifecycle module is needed if you want to track lifecycle events, both of which are available from the Tealium GitHub repository for iOS. There are two versions of each module: one for publishing to the App Store and one that includes the ability to run the app on a simulator, which cannot be published to the App Store
The sample application uses the TealiumIOS.framework and TealiumIOSLifecycle.framework modules for a simulator and developer experimentation and are not meant for publishing on the App Store. When working on your own application with the intent to publish to the App Store, use the frameworks in devices only folder.
CocoaPods
CocoaPods is the recommended installation method for complex production applications with many dependencies. The Tealium pod is named "TealiumIOS". For complete details, see the Tealium for iOS guide. Due to the fact that the command create-react-native-app does not create a Podfile, the sample application is built using manual installation.
Copy Bridging Logic
In the GitHub repository, the following two files provide the bridging between the Tealium native iOS SDK and the JavaScript in your React Native app:
TealiumModule.m
TealiumModule.h
Copy these two files into your main project for your application. Your iOS application should then build and work if your project correctly included the React Native dependencies and the Tealium iOS library.
Use from JavaScript
Importing the Module
If you installed via NPM
import Tealium from 'tealium-react-native';
If you installed manually
In the npm-package folder of the GitHub repository, find the file index.js , rename it to TealiumModule.js and copy it into your React Native JavaScript Project.
Next, add this line to your code to import the Tealium JavaScript module:
import Tealium from './TealiumModule';
Initialization
Once your app has been built you are ready to start coding. The Tealium instance must be invoked with the following parameters before you can begin tracking:
account – the name of your account
profile – the name of your profile
environment – (optional) one of "dev", "qa", or "prod"
iOS data source – (optional) the data source key from UDH
Android data source – (optional) the data source key from UDH
Example code to initialize Tealium:
Tealium.initialize('ACCOUNT', 'PROFILE', 'ENVIRONMENT', 'IOS_DATA_SOURCE_KEY', 'ANDROID_DATA_SOURCE_KEY' );
Initialization with Consent Management
If you want to use Consent Management, you can use this initializer instead. For more information on how Consent Management works, please refer to the Android and iOS documentation:
account – the name of your account
profile – the name of your profile
environment – (optional) one of "dev", "qa", or "prod"
iOS data source – (optional) the data source key from UDH
Android data source – (optional) the data source key from UDH
Example code to initialize Tealium:
Tealium.initializeWithConsentManager('ACCOUNT', 'PROFILE', 'ENVIRONMENT', 'IOS_DATA_SOURCE_KEY', 'ANDROID_DATA_SOURCE_KEY' );
Initialization with Custom Configuration Options
If you want to use more advanced features of the SDK like overriding Tag Management and Collect URLs, or need to support multiple instances of Tealium, you can use this initialization method:
account – the name of your account
profile – the name of your profile
environment – (optional) one of "dev", "qa", or "prod"
iOS data source – (optional) the data source key from UDH
Android data source – (optional) the data source key from UDH
instance name – any String to represent your Tealium instance
enable life cycle – life cycle tracking is optional. Pass true to enable, otherwise false <
publish settings URL – String representing the publish settings URL if overriding, otherwise null
tag management URL – String representing the tag management URL if overriding, otherwise null
enable collect endpoint – true is the default in native Android and iOS libraries that sends data to the Collect endpoint. false sends the data to the older vdata endpoint.
enable consent management – true to enable, otherwise false
Example code to initialize Tealium:
Tealium.initializeCustom('ACCOUNT', 'PROFILE', 'ENVIRONMENT', 'IOS_DATA_SOURCE_KEY', 'ANDROID_DATA_SOURCE_KEY', 'instance-1', true, null, null, true, true );
Tracking
Once the Tealium instance has been defined you can begin tracking with the method Tealium.trackView() , which takes the following parameters:
Screen Name – a name to identify the screen
Data – Object with event data as key/value pairs
Example code to track a view:
Tealium.trackView("screenName", {"someKey": "someValue"});
If multiple instances of Tealium are running, use Tealium.trackViewForInstanceName() which takes the following parameters:
Instance Name – name of the Tealium instance to track from
Screen Name – a name to identify the screen
Data (optional) – Object with event data as key/value pairs
Example code to track a view:
Tealium.trackViewForInstanceName("instance-1", "screenName", {"someKey": "someValue"});
Track non-view events with the method Tealium.trackEvent() using the following parameters:
Event Name (required) – a name to identify the event
Data (optional) – Object with event data as key/value pairs
Example code to track an event:
Tealium.trackEvent("eventName", {"someKey": "someValue"});
If multiple instances of Tealium are running, Track non-view events with the method Tealium.trackEventForInstanceName() using the following parameters:
Instance Name (required) – name of the Tealium instance to track from
Event Name (required) – a name to identify the event
Data (optional) – Object with event data as key/value pairs
Example code to track an event:
Tealium.trackEventForInstanceName("instance-1", "eventName", {"someKey": "someValue"});
Function Definitions
Tealium.initialize()
Tealium.initialize(account, profile, environment, iosDatasource, androidDatasource); Initialize Tealium before calling any other method.
Tealium.initialize('my-account', 'main', 'prod', 'abc123', 'def456');
Parameters
Type
Description
account
String
Tealium account name
profile
String
Tealium profile name (default: "main")
environment
String
Tealium environment: "qa" or "prod"
iOS data source (optional)
String
A data source key from UDH eg. "abc123"
Android data source (optional)
String
A data source key from UDH eg. "def456"
Tealium.initializeWithConsentManager()
Tealium.initializeWithConsentManagement(account, profile, environment, iosDatasource, androidDatasource); Initialize Tealium with Consent Management before calling any other method.
Tealium.initializeWithConsentManager('my-account', 'main', 'prod', 'abc123', 'def456');
Parameters
Type
Description
account
String
Tealium account name
profile
String
Tealium profile name (default: "main")
environment
String
Tealium environment: "qa" or "prod"
iOS data source (optional)
String
A data source key from UDH eg. "abc123"
Android data source (optional)
String
A data source key from UDH eg. "def456"
Tealium.initializeCustom()
Tealium.initializeCustom(account, profile, environment, iosDatasource, androidDatasource, instanceName, isLifecycleEnabled, overridePublishSettingsURL, overrideTagManagementURL, collectURL, enableConsentManager); Initialize Tealium with Consent Management before calling any other method.
Tealium.initializeCustom('my-account', 'main', 'prod', 'abc123', 'def456', 'instance-1', true, null, null, true, true);
Parameters
Type
Description
account
String
Tealium account name
profile
String
Tealium profile name (default: "main")
environment
String
Tealium environment: "qa" or "prod"
iOS data source (optional)
String
A data source key from UDH eg. "abc123"
Android data source (optional)
String
A data source key from UDH eg. "def456"
instance name
String
name of Tealium instance (e.g. can be any String)
enable life cycle
Boolean
To enable life cycle tracking (default: true)
override publish settings URL
String
String representing the publish settings URL if overriding, otherwise null (default: null)
override tag management URL
String
String representing the tag management URL if overriding, otherwise null (default: null)
enable collect endpoint
Boolean
true sends data to the Collect endpoint (default: true)
enable consent manager
Boolean
true enables Consent Management
Tealium.trackEvent()
Tealium.trackEvent(eventName, data);
Track an event, where the title is a string and the data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings.
Parameters
Type
Description
eventName
String
Name of event (becomes the event_name attribute in UDH)
data
Object
JSON object of key value pairs
Tealium.trackEvent("user_login", {"customer_id": "abcdef123456"});
Tealium.trackEventForInstanceName()
Tealium.trackEvent(instanceName, eventName, data);
Track an event, where the title is a string and the data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings. This method should be used if you have multiple instances of Tealium in your app.
Parameters
Type
Description
instanceName
String
Name of the Tealium instance
eventName
String
Name of event (becomes the event_name attribute in UDH)
data
Object
JSON object of key value pairs
Tealium.trackEventForInstanceName("instance-1", "user_login", {"customer_id": "abcdef123456"});
Tealium.trackView()
code>Tealium.trackView(screenName, data);
Track a view, where the title is a string and the data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings.
Parameters
Type
Description
screenName
String
Name of event (becomes the screen_title attribute in UDH)
data
Object
JSON object of key value pairs
Tealium.trackView("user_login", {"customer_id": "abcdef123456"});
Tealium.trackViewForInstanceName()
Tealium.trackViewForInstanceName(instanceName, screenName, data);
Track a view, where the title is a string and the data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings.This method should be used if you have multiple instances of Tealium in your app.
Parameters
Type
Description
instanceName
String
Name of the Tealium instance
screenName
String
Name of event (becomes the screen_title attribute in UDH)
data
Object
JSON object of key value pairs
Tealium.trackViewForInstanceName("instance-1", "user_login", {"customer_id": "abcdef123456"});
Tealium.setVolatileData()
Tealium.setVolatileData(data);
Set volatile data to be sent with each subsequent event or view until the app is terminated, where data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings.
Tealium.setVolatileDataForInstanceName()
Tealium.setVolatileData(instanceName, data);
Set volatile data to be sent with each subsequent event or view until the app is terminated, where data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings. This method should be used if you have multiple instances of Tealium in your app.
Tealium.getVolatileData()
Tealium.getVolatileData(key, value);
Gets the value for the key passed in.
Tealium.getVolatileDataForInstanceName()
Tealium.getVolatileData(instanceName, key, value);
Gets the value for the key passed in for the instance name. This method should be used if you have multiple instances of Tealium in your app.
Tealium.setPersistentData()
Tealium.setPersistentData(data);
Set persistent data to be sent with each subsequent event or view, even between app restarts, where data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings.
Tealium.setPersistentDataForInstanceName()
Tealium.setPersistentData(instanceName, data);
Set persistent data to be sent with each subsequent event or view, even between app restarts, where data is a JSON object of key-value pairs where keys are strings and the values are either a string or array of strings. This method should be used if you have multiple instances of Tealium in your app.
Tealium.removeVolatileData()
Tealium.removeVolatileData(keys);
Remove volatile data that has been previously set using Tealium.setVolatileData() by taking an array of key names.
Tealium.removeVolatileDataForInstanceName()
Tealium.removeVolatileData(instanceName, keys);
Tealium.setVolatileData() by taking an array of key names. This method should be used if you have multiple instances of Tealium in your app.
Tealium.removePersistentData()
Tealium.removePersistentData(keys);
Remove persistent data that has been previously set using Tealium.setPersistentData() by taking an array of key names.
Tealium.removePersistentDataForInstanceName()
Tealium.removePersistentData(instanceName, keys);
Remove persistent data that has been previously set using Tealium.setPersistentData() by taking an array of key names. This method should be used if you have multiple instances of Tealium in your app.
Tealium.getVisitorID()
Tealium.getVisitorID(visitorID);
Gets the visitorID of a user. Pass in a callback to use the visitorID.
Tealium.getVisitorIDForInstanceName()
Tealium.getVisitorID(instanceName, visitorID);
Gets the visitorID of a user. Pass in a callback to use the visitorID. This method should be used if you have multiple instances of Tealium in your app.
Tealium.getUserConsentStatus()
Tealium.getUserConsentStatus(userConsentStatus);
Gets the consent status of a user. Pass in a callback to use the userConsentStatus.
Tealium.getUserConsentStatusForInstanceName()
Tealium.getUserConsentStatusForInstanceName(instanceName, userConsentStatus);
Gets the consent status of a user. Pass in a callback to use the userConsentStatus. This method should be used if you have multiple instances of Tealium in your app.
Tealium.setUserConsentStatus()
Tealium.setUserConsentStatus(userConsentStatus);
Sets the consent status of a user.
Value
Description
0
Unknown
1
Consented
2
Not Consented
3
Disabled (Objective-C only)
Tealium.setUserConsentStatusForInstanceName()
Tealium.setUserConsentStatusForInstanceName(instanceName, userConsentStatus);
Sets the consent status of a user. This method should be used if you have multiple instances of Tealium in your app.
Value
Description
0
Unknown
1
Consented
2
Not Consented
3
Disabled (Objective-C only)
Tealium.getUserConsentCategories()
Tealium.getUserConsentCategories(userConsentCategories);
Gets the consent categories of a user. Pass in a callback to use the userConsentCategories.
Tealium.getUserConsentCatgoriesForInstanceName()
Tealium.getUserConsentCategoriesForInstanceName(instanceName, userConsentCategories);
Gets the consent categories of a user. Pass in a callback to use the userConsentCategories. This method should be used if you have multiple instances of Tealium in your app.
Tealium.setUserConsentCategories()
Tealium.setUserConsentCategories(userConsentCategories);
Sets the consent categories of a user. Pass in an array of Strings to set the categories.
Tealium.setUserConsentCatgoriesForInstanceName()
Tealium.setUserConsentCategoriesForInstanceName(instanceName, userConsentCategories);
Sets the consent ;categories of a user. Pass in an array of Strings to set the categories. This method should be used if you have multiple instances of Tealium in your app.
Tealium.resetUserConsentPreferences()
Tealium.resetUserConsentPreferences();
Resets the user consent status and categories of a user.
Tealium.resetUserConsentPreferencesForInstanceName()
Tealium.resetUserConsentPreferencesForInstanceName(instanceName);
Resets the user consent status and categories of a user. This method should be used if you have multiple instances of Tealium in your app.
Tealium.setConsentLoggingEnabled()
Tealium.setConsentLoggingEnabled(enabled);
Sets consent logging for a user.
Tealium.setConsentLoggingEnabledForInstanceName()
Tealium.setConsentLoggingEnabled(instanceName, enabled);
Sets consent logging for a user. This method should be used if you have multiple instances of Tealium in your app.
Tealium.isConsentLoggingEnabled()
Tealium.isConsentLoggingEnabled(enabled);
Checks if consent logging is enabled for a user. Pass in a callback to use the value of consent logging.
Tealium.isConsentLoggingEnabledForInstanceName()
Tealium.isConsentLoggingEnabled(instanceName, enabled);
Checks if consent logging is enabled for a user. Pass in a callback to use the value of consent logging. This method should be used if you have multiple instances of Tealium in your app.
... View more