React Native Quick Start Guide
Learn how to quickly integrate your React Native app.
Overview
The following section shows how to install, set up, and test your React Native application.
Install
To add the CleverTap React Native SDK to your project
npm install --save clevertap-react-native
Android Integration
Add CleverTap Credentials
To associate your Android app with your CleverTap account, you must add your CleverTap credentials to the application's AndroidManifest.xml
file. Follow the steps to add CleverTap credentials:
Add your CleverTap Account ID and Token to your AndroidManifest.xml within the tags.
<meta-data
android:name="CLEVERTAP_ACCOUNT_ID"
android:value="Your CleverTap Account ID"/>
<meta-data
android:name="CLEVERTAP_TOKEN"
android:value="Your CleverTap Account Token"/>
<!-- IMPORTANT: To force use Google AD ID to uniquely identify users, use the following meta tag. GDPR mandates that if you are using this tag, there is prominent disclousure to your end customer in their application. Read more about GDPR here - https://clevertap.com/blog/in-preparation-of-gdpr-compliance/ -->
<meta-data
android:name="CLEVERTAP_USE_GOOGLE_AD_ID"
android:value="1"/>
Credentials and Access
The CleverTap Account ID and CleverTap Token are available as Project ID and Project Token respectively on the CleverTap dashboard. Member and Creator roles in the project don't have access to view the Passcode and Project Token of the account on the dashboard.
Add Android Region Code
Refer to the following table to identify the region for your account:
CleverTap Dashboard URL | Region |
---|---|
https://eu1.dashboard.clevertap.com/login.html#/ | Europe (default region) |
https://in1.dashboard.clevertap.com/login.html#/ | India |
https://us1.dashboard.clevertap.com/login.html#/ | US |
https://sg1.dashboard.clevertap.com/login.html#/ | Singapore |
https://aps3.dashboard.clevertap.com/login.html#/ | Indonesia |
https://mec1.dashboard.clevertap.com/login.html | Middle East (UAE) |
Region Code for CleverTap Essentials
By default, the region code applicable for CleverTap Essentials plan is EU.
To enable the CleverTap region, add the following snippet in your AndroidManifest.xml
file between the <application></application>
tags:
<meta-data
android:name="CLEVERTAP_REGION"
android:value="in1"/>
<meta-data
android:name="CLEVERTAP_REGION"
android:value="sg1"/>
<meta-data
android:name="CLEVERTAP_REGION"
android:value="us1"/>
<meta-data
android:name="CLEVERTAP_REGION"
android:value="aps3"/>
<meta-data
android:name="CLEVERTAP_REGION"
android:value="mec1"/>
No action needed.
For more information on adding region codes for OS, channels, and APIs, refer to Region Codes.
Enable Tracking by Adding Permissions
Add the snippet below in the AndroidManifest.xml
file so the CleverTap SDK can access the internet.
<!-- Required to allow the app to send events and user profile information -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- Recommended so that CleverTap knows when to attempt a network call -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
Add Dependencies
- Add the following to your
dependencies
section inproject/build.gradle
:
dependencies {
classpath 'com.android.tools.build:gradle:7.2.1'
classpath 'com.google.gms:google-services:4.3.3' //<--- Mandatory for using Firebase Messaging, skip if not using FCM
}
- Add the following to your
dependencies
section inapp/build.gradle
:
implementation 'com.clevertap.android:clevertap-android-sdk:5.0.0'
implementation 'com.google.firebase:firebase-messaging:23.0.6'
implementation 'androidx.core:core:1.4.0'
implementation 'androidx.fragment:fragment:1.3.6'
//MANDATORY for App Inbox
implementation 'androidx.appcompat:appcompat:1.3.1'
implementation 'androidx.recyclerview:recyclerview:1.2.1'
implementation 'androidx.viewpager:viewpager:1.0.0'
implementation 'com.google.android.material:material:1.4.0'
implementation 'com.github.bumptech.glide:glide:4.12.0'
//For CleverTap Android SDK v3.6.4 and above add the following -
implementation 'com.android.installreferrer:installreferrer:2.2'
//Optional ExoPlayer Libraries for Audio/Video Inbox Messages. Audio/Video messages will be dropped without these dependencies
implementation 'com.google.android.exoplayer:exoplayer:2.17.1'
implementation 'com.google.android.exoplayer:exoplayer-hls:2.17.1'
implementation 'com.google.android.exoplayer:exoplayer-ui:2.17.1'
- At the end of the
app/build.gradle
file, add the following:
apply plugin: 'com.google.gms.google-services' //skip if not using FCM
Setup Android's Application Class
In your app's Android Application class
, add the following code:
// CleverTap imports
import com.clevertap.android.sdk.ActivityLifecycleCallback;
import com.clevertap.react.CleverTapPackage;
import com.clevertap.android.sdk.CleverTapAPI;
// add CleverTapPackage to react-native package list
@Override
protected List<ReactPackage> getPackages() {
List<ReactPackage> packages = new PackageList(this).getPackages();
// Packages that cannot be autolinked yet can be added manually here, for
// example:
packages.add(new CleverTapPackage());// only needed when not auto-linking
return packages;
}
// add onCreate() override
@Override
public void onCreate() {
// Register the CleverTap ActivityLifecycleCallback; before calling super
ActivityLifecycleCallback.register(this);
super.onCreate();
}
Optionally Override onCreate in MainActivity.java to notify CleverTap of a launch deep link (android/app/src/[...]/MainActivity.java
)
import com.clevertap.react.CleverTapModule;
import android.os.Bundle;
public class MainActivity extends ReactActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
CleverTapModule.setInitialUri(getIntent().getData());
}
}
- Add the following permissions. The CleverTap SDK needs them:
<!-- Required to allow the app to send events and user profile information -->
<uses-permission android:name="android.permission.INTERNET"/>
<!-- Recommended so that CleverTap knows when to attempt a network call -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
iOS integration
iOS with podspec
- Add
pod 'clevertap-react-native', :path => '../node_modules/clevertap-react-native'
as a dependency in your ios/Podfile.
Add the following to your Podfile:
target 'YOUR_TARGET_NAME' do
use_frameworks!
pod 'clevertap-react-native', :path => '../node_modules/clevertap-react-native'
end
- Run
pod install
from your ios directory.
iOS without podspec
- Add
pod 'CleverTap-iOS-SDK'
as a dependency in your ios/Podfile. cd ios; pod install --repo-update
Note
After pod install, open your project using [MyProject].xcworkspace instead of the original .xcodeproj.
Add CleverTap Credentials
To link your iOS app with your CleverTap account, add your CleverTap credentials to your application's Info.plist
file.
Perform the following steps:
- Navigate to the
Info.plist
file in your project navigator.
- Create a key called CleverTapAccountID with the type string.
- Create a key called CleverTapToken with the type string.
- Insert the account ID and account token values from your CleverTap account. These values are available on the Settings page. To navigate to the Settings page, log into your CleverTap account, click on the gear icon on the bottom left navigation, and select Settings dashboard.
Add iOS Region Code
To add the iOS region code for your account, refer to Add iOS Region Code.
Initialize CleverTap SDK
- Initialize CleverTap SDK by adding the following code snippet to import the CleverTap header in your AppDelegate file:
#import <CleverTap-iOS-SDK/CleverTap.h>
#import <Clevertap-react-native/CleverTapReactManager.h>
import <CleverTapSDK/CleverTap.h>
import <CleverTapReact/CleverTapReactManager.h>
- In your
didFinishLaunchingWithOptions:
method, notify the CleverTap React Native SDK of application launch:
[CleverTap autoIntegrate]; // integrate CleverTap SDK using the autoIntegrate option
[[CleverTapReactManager sharedInstance] applicationDidLaunchWithOptions:launchOptions];
CleverTap.autoIntegrate() // integrate CleverTap SDK using the autoIntegrate option
CleverTapReactManager.sharedInstance()?.applicationDidLaunch(options: launchOptions)
Note
Need to use
@import CleverTapSDK;
instead of#import <CleverTap-iOS-SDK/CleverTap.h>
and@import CleverTapReact;
instead of#import <clevertap-react-native/CleverTapReactManager.h>
in the AppDelegate class in case if usinguse_modular_headers!
in the podfile.
Example Usage
Grab a reference
Create a CleverTap reference to use Javascript methods:
const CleverTap = require('clevertap-react-native');
Track User Profiles
Create a User profile when the user logs in (On User Login):
CleverTap.onUserLogin({'Name': 'React-Test', 'Identity': '11102008', 'Email': '[email protected]', 'custom1': 43});
Update the User Profile
The Onuserlogin
method identifies individual users on a device when the User logs in for the first time. However, you may need to add additional user properties to the user profile such as gender, date of birth, and so on. You can update these properties with the profilePush()
method. For more information, refer to our User Documentation.
Track User Events
Record an event without event data:
CleverTap.recordEvent('testEvent');
Record an event with event data:
CleverTap.recordEvent(
'Product Viewed', {'Product Name': 'Dairy Milk',
'Category': 'Chocolate',
'Amount': 20.00
});
TroubleShooting
Android
If you face the following crash at runtime -
java.lang.UnsatisfiedLinkError: couldn't find DSO to load: libhermes.so
Add the following in your app/build.gradle
-
project.ext.react = [
entryFile: "index.js",
enableHermes: false //add this
]
def jscFlavor = 'org.webkit:android-jsc:+'
def enableHermes = project.ext.react.get("enableHermes", false);
def jscFlavor = 'org.webkit:android-jsc:+'
def enableHermes = project.ext.react.get("enableHermes", false);
dependencies {
if (enableHermes) {
// For RN 0.60.x
def hermesPath = "../../node_modules/hermesvm/android/"
debugImplementation files(hermesPath + "hermes-debug.aar")
releaseImplementation files(hermesPath + "hermes-release.aar")
} else {
implementation jscFlavor
}
}
In android/build.gradle
add this -
maven {
url "$rootDir/../node_modules/jsc-android/dist"
}
iOS
If you're on React-Native v0.60 or your project configuration doesn't allow you to add use_frameworks!
in the podfile, you can add use_modular_headers!
to enable the stricter search paths and module map generation for all of your pods. Alternatively, you can add:modular_headers => true
to a single pod declaration to enable for only that pod.
GDPR Compliance
CleverTap provides APIs to support GDPR compliance. For more information, refer to Advance Features.
Updated about 2 months ago