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!

How it works

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

You must identify a profile before you can take advantage of most SDK features. You can send anonymous in-app messages in our latest updates, but you can’t send push notifications or capture event activity for anonymous devices/users. That means that you can’t track or respond to anything your audience does in your app until you identify them.

In Customer.io, you identify profiles 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 Customer.io. You can also send the identified profile messages from Customer.io.

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

Prerequisites

Before you get started with our React Native SDKs, you’ll need your Customer.io workspace Site ID and API Key. You’ll provide these credentials when you initialize the SDK.

Because our React Native package relies on our native iOS and Android modules, you’ll need to set up both your React Native development environment and make sure that you’re set up to support both iOS and Android in your environment.

To support the Customer.io SDK, you must:

• Use Gradle 8.0 or later.
• Use Android Gradle plugin version 8.0 or later (8.2+ recommended).
• Use Kotlin 1.9.20 or later (2.0+ required if using Kotlin Multiplatform or K2-specific features).
• Set iOS 13 or later as your minimum deployment target in XCode.
• Have an Android device or emulator with Google Play Services enabled and a minimum OS version between Android 5.0 (API level 21) and Android 13.0 (API level 33).
• Have an iOS 13+ device to test your implementation. You cannot test push notifications in a simulator.
• Add React Navigation to your app to support deep links and screen tracking.

Before you begin: set up your development environment

Before you get started, you’ll need to do the following things:

1. Set up your React Native environment ↗
2. Add React navigation ↗ to your project to support deep links and screen tracking
3. Set up your iOS environment:
   1. Setup XCode (using deployment target to 13.0 or later).
   2. Make sure that you have XCode command line tools installed xcode-select --install.
   3. Get your Apple Push Certificate and enable push notifications for iOS in your Customer.io account.
   4. Have an iOS 13 to test with. You cannot test push notifications in an emulator.
4. Set up your Android environment:
   1. Download and install Android Studio ↗
   2. Add your Google Firebase Cloud Messaging (FCM) key to Customer.io and enable push notifications for Android
   3. Make sure you use an appropriate version of the Android Gradle plugin.
   4. Have an Android device or emulator with Google Play Services enabled and a minimum OS version.

Install the React Native SDK

This process involves setup for both iOS and Android. For Android, the directions below will guide you through the setup process for both Firebase Cloud Messaging (FCM) and our in-app messaging module; both are required to use the React Native SDK.

1. Open your terminal and go to your project folder—cd <Root/path/to/your/app>.

2. Install the customerio-reactnative package using NPM or Yarn:

   • npm install customerio-reactnative
   • yarn add customerio-reactnative

3. If you’re using a React Native version earlier than 0.60, link the library manually with npx react-native link customerio-reactnative. Otherwise, go to the next step.

4. In your terminal, run pod install --repo-update --project-directory=ios. This adds the required iOS dependencies to your project. When the process is complete , you’ll see a message like this:

   Pod installation complete! There are X dependencies from the Podfile and Y total pods installed.

5. Make sure that your minimum deployment target is set to 13.0. You’ll have to do this in two places:

   1. Go to the ios subfolder and open your Podfile. Find the platform:ios line, and make sure that the version is set to 13.0 or later if it isn’t already.

   2. Open your project’s iOS directory in XCode, select the project under Targets, and set the Minimum Deployments target to 13.0 or later.

      

6. Go to the Android subfolder and include google-services-plugin ↗ by adding 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 'com.google.gms:google-services:<version-here>'  // Google Services plugin
      }
   }
   
   allprojects {
      repositories {
         // Add this line if it isn't already in your build file:
         google()  // Google's Maven repository
      }
   }

7. Add the following line to android/app/build.gradle:

   apply plugin: 'com.google.gms.google-services'  // Google Services plugin

8. Download google-services.json from your Firebase project and copy the file to android/app/google-services.json.

Now you’re ready to initialize the SDK and use it in your app.

Initialize the SDK

After you install the SDK, you’ll need to initialize it in your app. To do this, you’ll add initialization code in your App.js file—or wherever you want to initialize the customerio-reactnative package. You’ll need Track API credentials to initialize the SDK—your Site ID and API Key, which you can find in Customer.io under Settings > Workspace Settings > API Credentials.

This makes the SDK available to use in your app. Note that you’ll still need to identify your app’s users before you can send them messages.

import React, {useEffect} from 'react';
import { CustomerIO, CustomerIOEnv, Region } from 'customerio-reactnative';

const App = () => {

useEffect(() => {
   const env = new CustomerIOEnv()
   env.siteId = "YourSiteId"
   env.apiKey = "YourAPIKey"
   
   // Region is optional, defaults to Region.US.
   // Use Region.EU for EU-based workspaces.
   env.region = Region.US

   CustomerIO.initialize(env)
}, [])

When you’re done, you may want to return to your main folder and run your application to make sure that everything’s set up correctly:

• iOS: npx react-native run-ios
• Android: npx react-native run-android

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.

Import CustomerioConfig and then set configuration options to configure things like your logging level and whether or not you want to automatically track device attributes, etc.

import { CustomerIO, CustomerioConfig } from 'customerio-reactnative';

const data = new CustomerioConfig()
data.logLevel = CioLogLevel.debug
data.autoTrackDeviceAttributes = true
    
// In-app messages are optional and disabled by default
// To enable in-app messages, set enableInApp to true
data.enableInApp = true

// `env` is the environment constant you used
// to initialize the SDK in the previous section
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 or enable autoTrackScreenViews to automatically capture screen view events for your audience.

Securing your credentials

To simplify things, code samples in our documentation sometimes show API keys directly in your code. But you don’t have to hard-code your keys in your app. You can use environment variables, management tools that handle secrets, or other methods to keep your keys secure if you’re concerned about security.

To be clear, the keys that you’ll use to initialize the SDK don’t provide read access to data in Customer.io; they only write data to Customer.io. A bad actor who found your credentials can’t use your keys to read data from our servers.

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 20 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 profile in your app using the SDK, you won’t see the created/updated profile immediately. You’ll have to wait for the SDK to meet any of the criteria above before the SDK sends a request to the Customer.io API. Then, if the request is successful, you’ll see your created/updated profile 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.

Using the SDK as a data source

The SDK uses our Legacy Track API API, but it can also double as a source of data for other integrations without additional development work.

To do this, we translate calls from the SDK to our newer Data Pipelines API format before we send them to your destinations.

In general, we recommend that you upgrade your app to use a newer version of the SDK. Our newer versions rely on the Data Pipelines API, so you can take advantage of your mobile data without without us translating it for you. It can make it easier to trace data from your app to your destinations and troubleshoot issues as they arise. Our newer SDKs also support more features, like anonymous tracking.