Get Started
UpdatedThere's a new version available!
These pages cover version 3 of our SDK, but a newer version is available. In general, we suggest that you update to the latest version to take advantage of new features and fixes.
- Are you new to our SDKs? Check out the latest docs.
- Otherwise, learn about updating to the latest version
Before you can take advantage of our SDK, you need to install the module(s) you want to use, initialize the SDK, and understand the order of 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 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 Customer.io.
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 (clearIdentify 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 Customer.io, 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 Customer.io. You can also send the identified person messages from Customer.io.
You send messages to a person through the Customer.io campaign builder, broadcasts, etc. These messages are not stored on the device side. If you want to 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 Customer.io and receive a message payload.
SDK packages
To minimize our impact on your app’s size, we offer multiple, separate SDKs. You should only install the SDKs that you need for your project.
You must install the Tracking SDK. It lets you identify people, which you must do before you can send them messages, track their events, etc.
Package | Required? | Description |
---|---|---|
tracking | ✅ | identify people in Customer.io |
messaging-push-fcm | Receive and interpret push notifications |
Prerequisites
To support the Customer.io SDK, you must:
Use Android Gradle plugin version 7.4 or later.
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).
Install the SDK
Before you add Customer.io dependencies, update your repositories in the
settings.gradle
file to includemavenCentral()
.dependencyResolutionManagement { repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS) repositories { google() mavenCentral() // only needed for in-app messaging in SDK versions below 3.6.1 // maven { url 'https://maven.gist.build' } } }
Or, if you’re using an earlier project setup, make sure that you have added
mavenCentral()
as a repository in your root-levelbuild.gradle
file:allprojects { repositories { google() mavenCentral() // only needed for in-app messaging in SDK versions below 3.6.1 // maven { url 'https://maven.gist.build' } } }
Install the dependencies that are relevant to your implementation. Replace
version-here
with the the latest version (available in our github repository).implementation 'io.customer.android:tracking:3.11.1' implementation 'io.customer.android:messaging-push-fcm:3.11.1'
Initialize the SDK
Before you can use the Customer.io SDK, you need to initialize it. CustomerIO
is a singleton: you’ll create it once and re-use it across your application. You’ll need Track API credentials to initialize the SDK—your Site IDEquivalent to the user name you’ll use to interface with the Journeys Track API; also used with our JavaScript snippets. You can find your Site ID under Settings > Workspace Settings > API Credentials and API KeyEquivalent to the password you’ll use with a Site ID to interface with the Journeys Track API. You can generate new keys under Settings > Workspace Settings > API Credentials, which you can find in Customer.io under Settings > Workspace Settings > API Credentials.
You should initialize CustomerIO
in the Application
class, so that you can access that instance from any part of your application using the instance()
method.
class App : Application() {
override fun onCreate() {
super.onCreate()
val customerIO = CustomerIO.Builder(
siteId = "your-site-id",
apiKey = "your-api-key",
appContext = this
).build()
}
}
The Builder
for CustomerIO
exposes configuration options for features like region
, and timeout
.
val builder = CustomerIO.Builder(
siteId = "YOUR-SITE-ID",
apiKey = "YOUR-API-KEY",
appContext = this
)
builder.setRegion(Region.EU)
// set the request timeout for all the API requests sent from SDK
builder.setRequestTimeout(8000L)
builder.build()
Check out our sample apps!
Configuration options
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.
Option | Type | Default | Description |
---|---|---|---|
autoTrackDeviceAttributes | boolean | true | Automatically gathers information about devices, like operating system, device locale, model, app version, etc |
autoTrackScreenViews | boolean | false | If true, the SDK automatically sends screen events for every screen your audience visits. |
backgroundQueueMinNumberOfTasks | integer | 10 | See the processing queue for more information. This sets the number of tasks that enter the processing queue before sending requests to Customer.io. In general, we recommend that you don't change this setting, because it can impact your audience's battery life. |
backgroundQueueSecondsDelay | integer | 30 | See 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. |
logLevel | string | error | Sets the level of logs you can view from the SDK. Set to debug to see more logging output. |
CustomerIO.Builder(
siteId = "your-site-id",
apiKey = "your-api-key",
appContext = this
)
.autoTrackScreenViews(true)
.build()
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 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 Customer.io 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.
[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]
Using the SDK as a Data Pipelines source
The SDK uses our Journeys Track API, but our SDK can also double as a source of data in our Data Pipelines feature without any additional development work.
If you want to forward data from your mobile app to other applications in your stack using our Data Pipelines feature, you can enable the Track API as a source. This automatically forwards calls from your app to Data Pipelines without having to implement new calls or functions. We’ll translate calls from the SDK to the Data Pipelines format, so you can take advantage of your mobile data in destinations automatically.
When you enable the Track API as a data source, you’ll see individual sources for each set of Track API credentials. The Name of your credentials becomes the name of your data source.
![all API credentials are listed as individual sources](/docs/images/cdp-journeys-sources.png)
![all API credentials are listed as individual sources](/docs/images/cdp-journeys-sources.png)