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:

📘

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

  1. Add the following to your dependencies section in project/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
        }
  1. Add the following to your dependencies section in app/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'
  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

  1. 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();
}

If you do not have an Application class, add this to your AndroidManifest.xml file:

<application
        android:label="@string/app_name"
        android:icon="@drawable/ic_launcher"
        android:name="com.clevertap.android.sdk.Application">

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());
	}
}
  1. 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:

  1. Navigate to the Info.plist file in your project navigator.
574

Information Property List in Info.plist

  1. Create a key called CleverTapAccountID with the type string.
  2. Create a key called CleverTapToken with the type string.
  3. 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.
1449

CleverTap Project Credentials

Add iOS Region Code

To add the iOS region code for your account, refer to Add iOS Region Code.

Initialize CleverTap SDK

  1. 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>
  1. 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 using use_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.