Get Started

Before you can take advantage of our SDK, you need to install and initialize the SDK. This page also explains how the SDK prioritizes operations.

This page is part of an introductory series to help you get started with the essential features of our SDK. The highlighted step(s) below are covered on this page. Before you continue, make sure you've implemented previous features—i.e. you can't identify people before you initialize the SDK!

graph LR getting-started(Install SDK) -->B(Initialize SDK) B --> identify(identify people) identify -.-> track-events(Send events) identify -.-> push(Receive push) identify -.-> rich-push(Receive Rich Push) identify -.-> in-app(Receive in-app) click getting-started href "/docs/sdk/react-native/getting-started" click B href "/docs/sdk/react-native/getting-started/#initialize-the-sdk" click identify href "/docs/sdk/react-native/identify" click track-events href "/docs/sdk/react-native/track-events/" click register-token href "/docs/sdk/react-native/push" click push href "/docs/sdk/react-native/push" click rich-push href "/docs/sdk/react-native/rich-push" click in-app href "/docs/sdk/react-native/in-app" click test-support href "/docs/sdk/react-native/test-support" style getting-started fill:#B5FFEF,stroke:#007069 style B fill:#B5FFEF,stroke:#007069

How it works

Our SDKs provide a ready-made integration to identify people who use mobile devices and send them notifications. Before you start using the SDK, you should understand a bit about how the SDK works with

sequenceDiagram participant A as Mobile User participant B as SDK participant C as A--xB: User activity
user not identified A->>B: Logs in (identify method) rect rgb(229, 254, 249) Note over A,C: Now you can Send events and receive messages B-->>C: Person added/updated in CIO A->>B: User activity (track event) B->>C: Event triggers campaign C->>B: Campaign triggered push B->>A: Display push A->>B: Logs out (stopIdentify method) end A--xB: No longer sending events or receiving messages

You must identify a person before you can take advantage of most SDK features. We don’t currently support messages or events for anonymous devices/users, which means that we can’t track or respond to anything your audience does in your app until you identify them.

In, you identify people by id or email, which typically means that you need someone to log in to your app or service before you can identify them.

While someone is “identified”, you can send events representing their activity in your app to You can also send the identified person messages from

You send messages to a person through the campaign builder, broadcasts, etc. These messages are not stored on the device side. If you want send an event-triggered campaign to a mobile device, the mobile device user must be identified and have a connection such that it can send an event back to and receive a message payload.

Install and initialize the SDK

  1. Open your terminal and run npm install customerio-reactnative

  2. To support iOS: go to the iOS subfolder and run pod install. Make sure your deployment target is set to at least 13.0. Before you perform this step, you may want to update your podfile to support push notifications and rich push respectively, and then

  3. To support Android: Go to the Android subfolder and set up Firebase Cloud Messaging (FCM) and in-app messaging; both are mandatory to use the React Native SDK for Android.

    1. Add the following lines to the project-level android/build.gradle file:
      buildscript {
         repositories {
            // Add this line if it isn't already in your build file:
            google()  // Google's Maven repository
         dependencies {
            // Add this line:
            classpath ''  // Google Services plugin
      allprojects {
         repositories {
            // Add this line if it isn't already in your build file:
            google()  // Google's Maven repository
    2. Add the in-app dependency to the dependencyResolutionManagement block in your android/settings.gradle file—if it exists. Otherwise, add the dependency to your project-level android/build.gradle file.
      // in build.gradle
      allprojects {
         repositories {
            // add in-app messaging dependency
            maven { url '' }
      // in settings.gradle
      dependencyResolutionManagement {
         repositories {
            // add in-app messaging dependency
            maven { url '' }
    3. Add the following line to android/app/build.gradle:
      apply plugin: ''  // Google Services plugin
    4. Download google-services.json from your Firebase project and copy the file to android/app/google-services.json.
  4. Return to the main folder and run your application:

    • iOS: npx react-native run-ios
    • Android: npx react-native run-android
  5. Add an import statement to your project for the react native library. We haven’t included it below, but you can import CioLogLevel to set log outputs to something other than error; this may help you debug your application.

    import { CustomerIO, CustomerioConfig, CustomerIOEnv, Region } from customerio-reactnative;
  6. In useEffect, initialize the package with your CustomerioConfig options and CustomerIOEnv variables. You can find your Site ID and API Key credentials—or create new ones—under Data & Integrations > Integrations > API:

    useEffect(() => {
       const data = new CustomerioConfig()
       data.logLevel = CioLogLevel.debug
       const env = new CustomerIOEnv()
       env.siteId = Env.siteId
       env.apiKey = Env.apiKey
       env.organizationId = Env.organizationId
       //organizationId is used to send in-app messages.
       env.region = Region.US
       //Region is optional, defaults to Region.US. Use Region.EU for EU-based workspaces.
       CustomerIO.initialize(env, data) 
    }, [])

Configure the SDK

You can determine global behaviors for the SDK in the CustomerIO.config object. You must provide configuration options before you initialize the SDK; you cannot declare configuration changes after you initialize the SDK.

const data = new CustomerioConfig()
   data.logLevel = CioLogLevel.debug
   data.autoTrackDeviceAttributes = true
CustomerIO.initialize(env, data) 

When you initialize the SDK, you can pass configuration options. In most cases, you'll want to stick with the defaults, but you might do things like change the logLevel when testing updates to your app.

autoTrackDeviceAttributesbooleantrueAutomatically gathers information about devices, like operating system, device locale, model, app version, etc
autoTrackPushEventsbooleantrueThe SDK automatically generates delivered and opened metrics for push notifications sent from
backgroundQueueMinNumberOfTasksinteger10See the processing queue for more information. This sets the number of tasks that enter the processing queue before sending requests to In general, we recommend that you don't change this setting, because it can impact your audience's battery life.
backgroundQueueSecondsDelayinteger30See the processing queue for more information. The number of seconds after a task is added to the processing queue before the queue executes. In general, we recommend that you don't change this setting, because it can impact your audience's battery life.
logLevelstringerrorSets the level of logs you can view from the SDK. Set to debug to see more logging output.

The Processing Queue

The SDK automatically adds all calls to a queue system, and waits to perform these calls until certain criteria is met. This queue makes things easier, both for you and your users: it handles errors and retries for you (even when users lose connectivity), and it can save users’ battery life by batching requests.

The queue holds requests until any one of the following criteria is met:

  • There are 10 or more tasks in the queue.
  • 30 seconds have passed since the SDK performed its last task.
  • The app is closed and re-opened.

For example, when you identify a new person in your app using the SDK, you won’t see the created/updated person immediately. You’ll have to wait for the SDK to meet any of the criteria above before the SDK sends a request to the API. Then, if the request is successful, you’ll see your created/updated person in your workspace.

How the queue organizes tasks

The SDK typically runs tasks in the order that they were called—unless one of the tasks in the queue fails.

Tasks in the queue are grouped by “type” because some tasks need to run sequentially. For example, you can’t invoke a track call if an identify call hasn’t succeeded first. So, if a task fails, the SDK chooses the next task in the queue depending on whether or not the failed task is the first task in a group.

  • If the failed task is the first in a group: the SDK skips the remaining tasks in the group, and moves to the next task outside the group.
  • If the failed task is 1+n task in a group: the SDK skips the failed task and moves on to the next task in the group.**

The following chart shows how the SDK would process a queue where tasks A, B, and C belong to the same group.

flowchart TD a["Task inventory
[A, B, C], D"]-->b{Is task A
successful} b-.->|Yes|c[Continue to task B] b-.->|No|d[Skip to task D] c-.->|Whether task B
succeeds or fails|E[Continue to task C]
Copied to clipboard!
Latest release
Is this page helpful?