Loading…

Quick Start Guide

Updated

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.

Setup Process Overview

For native Android apps, our Android SDK sets you up to send push notifications and track user activity. You’ll need to add Customer.io SDK to your project, configure it with your API key, and set up push notification handling. Then, you’ll use the SDK to identify users, track their activity, and respond to incoming notifications.

  1. Install the SDK.
  2. Identify and Track
  3. Push Notifications
  4. In-App

1. Install the SDK

  1. If you haven’t already gotten a CDP API key, you’ll need to add a new Android integration to your Customer.io workspace. This “integration” represents your app in Customer.io and provides the CDP API key that you’ll use to initialize the SDK. See Get your CDP API key for details.

  2. Ensure that your build.gradle or settings.gradle includes the following repositories to resolve dependencies:

    android {
  repositories {
    google()
    mavenCentral()
  }
  ...
}

  3. Add the following dependencies to your build.gradle file to install Customer.io Android SDK:

    dependencies {
  implementation "io.customer.android:datapipelines:4.6.0"
  // Required for push notifications only
  implementation "io.customer.android:messaging-push-fcm:4.6.0"
  // Required for in-app messages only
  implementation "io.customer.android:messaging-in-app:4.6.0"
}

  4. We recommend initializing Customer.io SDK in your app’s Application class in the onCreate method. This ensures the SDK is accessible throughout your app using CustomerIO.instance() method. Use CustomerIOBuilder to add and configure the modules you want to enable:

import io.customer.messaginginapp.MessagingInAppModuleConfig
import io.customer.messaginginapp.ModuleMessagingInApp
import io.customer.messagingpush.ModuleMessagingPushFCM
import io.customer.sdk.CustomerIOBuilder
import io.customer.sdk.data.model.Region

CustomerIOBuilder(application, <CDP_API_KEY>).apply {
  // If you're in the EU, set Region.EU. Default is Region.US and optional.
  region(Region.US)

  // Optional: Enable in-app messaging by adding siteId and Region
  addCustomerIOModule(
      ModuleMessagingInApp(
        // If you're in the EU, set Region.EU
        MessagingInAppModuleConfig.Builder(<SITE_ID>, Region.US).build()
      )
  )

  // Optional: Enable support for push notifications
  addCustomerIOModule(ModuleMessagingPushFCM())

  // Completes setup and initializes the SDK
  build()
}

import io.customer.messaginginapp.MessagingInAppModuleConfig;
import io.customer.messaginginapp.ModuleMessagingInApp;
import io.customer.messagingpush.ModuleMessagingPushFCM;
import io.customer.sdk.CustomerIOBuilder;
import io.customer.sdk.data.model.Region;

CustomerIOBuilder builder = new CustomerIOBuilder(application, <CDP_API_KEY>);
builder.region(Region.US.INSTANCE);
// Optional: Enable in-app messaging by adding siteId and Region
builder.addCustomerIOModule(
  // If you're in the EU, set Region.EU
  new ModuleMessagingInApp(new MessagingInAppModuleConfig.Builder(<SITE_ID>, Region.US.INSTANCE).build()));
// Optional: Enable support for push notifications
builder.addCustomerIOModule(new ModuleMessagingPushFCM());
// Completes setup and initializes the SDK
builder.build();

2. Identify and Track

  1. Identify a user in your app using the CustomerIO.instance().identify method. You must identify a user before you can send push notifications and personalized in-app messages.
import io.customer.sdk.CustomerIO

fun identifyUserExample() {
  CustomerIO.instance().identify(
    userId = "android-test-user@example.com",
    traits = buildMap { 
      put("firstName", "John")
      put("lastName", "Doe")
      put("email", "android-test-user@example.com")
      put("subscriptionStatus", "active")
    },
  )
  Log.d("[CustomerIO]", "User identified successfully")
}

import io.customer.sdk.CustomerIO;

void identifyUserExample() {
    String userId = "android-test-user@example.com";
    Map<String, Object> traits = new HashMap<>();
    traits.put("firstName", "John");
    traits.put("lastName", "Doe");
    traits.put("email", "android-test-user@example.com");
    traits.put("subscriptionStatus", "active");
    CustomerIO.instance().identify(userId, traits);
    Log.d("[CustomerIO]", "User identified successfully");
}
  1. Track a custom event using the CustomerIO.instance().track method. Events help you trigger personalized campaigns and track user activity.
import io.customer.sdk.CustomerIO

fun trackCustomEventExample() {
  CustomerIO.instance().track(
    name = "purchased_item",
    properties = buildMap { 
      put("product", "Premium Subscription")
      put("price", 99.99)
      put("currency", "USD")
    }
  )
  Log.d("[CustomerIO]", "Custom event tracked successfully")
}

import io.customer.sdk.CustomerIO;

void trackCustomEventExample() {
    String name = "purchased_item";
    Map<String, Object> properties = new HashMap<>();
    properties.put("product", "Premium Subscription");
    properties.put("price", 99.99);
    properties.put("currency", "USD");
    CustomerIO.instance().track(name, properties);
    Log.d("[CustomerIO]", "Custom event tracked successfully");
}
  1. Track screen views to automatically trigger in-app messages associated with specific screens.
import io.customer.sdk.CustomerIO

fun trackScreenViewExample() {
  CustomerIO.instance().screen(
    title = "ProductDetails",
    properties = buildMap {
      put("product_id", "12345")
      put("product_name", "Sample Product")
      put("category", "Electronics")
    }
  )
  Log.d("[CustomerIO]", "Screen view tracked successfully")
}

import io.customer.sdk.CustomerIO;

void trackScreenViewExample() {
    String title = "ProductDetails";
    Map<String, Object> properties = new HashMap<>();
    properties.put("product_id", "12345");
    properties.put("product_name", "Sample Product");
    properties.put("category", "Electronics");
    CustomerIO.instance().screen(title, properties);
    Log.d("[CustomerIO]", "Screen view tracked successfully");
}

3. Push Notifications

  1. Set up your push notification credentials by uploading your Firebase Cloud Messaging (FCM) service account key (.json file) in Customer.io dashboard
  2. Add the push messaging dependency to your project:
    implementation "io.customer.android:messaging-push-fcm:4.6.0"
  3. Make sure your app includes required Firebase configurations (like the google-services plugin and the google-services.json file) as described in the FCM documentation.
  4. Initialize and include the push module in CustomerIOBuilder when setting up the SDK:
    import io.customer.messagingpush.ModuleMessagingPushFCM

addCustomerIOModule(ModuleMessagingPushFCM())

    import io.customer.messagingpush.ModuleMessagingPushFCM;

builder.addCustomerIOModule(new ModuleMessagingPushFCM());
  5. Request push notification permissions from the user following Google’s recommendations.

For more details and customization options, see Push Notifications.

4. In-App

  1. To enable in-app messaging, add your site ID and Region. You’ll find your site ID under Data & Integrations > Integrations > Customer.io API: Track in the Connections tab.
  2. Add the in-app messaging dependency to your project:
    implementation "io.customer.android:messaging-in-app:4.6.0"
  3. Initialize and include the in-app module in CustomerIOBuilder when setting up the SDK:
    import io.customer.messaginginapp.MessagingInAppModuleConfig
import io.customer.messaginginapp.ModuleMessagingInApp
import io.customer.messaginginapp.type.InAppEventListener
import io.customer.messaginginapp.type.InAppMessage
import io.customer.sdk.data.model.Region

addCustomerIOModule(
  ModuleMessagingInApp(
    MessagingInAppModuleConfig.Builder(
      siteId = <SITE_ID>,
      // If you're in the EU, set Region.EU
      region = Region.US
    )
    // Optional: Set in-app message event listener
    .setEventListener(object : InAppEventListener {
      ...
    })
    .build()
  )
)

    import io.customer.messaginginapp.MessagingInAppModuleConfig;
import io.customer.messaginginapp.ModuleMessagingInApp;
import io.customer.messaginginapp.type.InAppEventListener;
import io.customer.messaginginapp.type.InAppMessage;
import io.customer.sdk.data.model.Region;

builder.addCustomerIOModule(
  // If you're in the EU, set Region.EU
  new ModuleMessagingInApp(new MessagingInAppModuleConfig.Builder(<SITE_ID>, Region.US.INSTANCE)
    // Optional: Set in-app message event listener
    .setEventListener(new InAppEventListener() {
      ...
    })
    .build()));

For more details and customization options, see In-App Messaging.

Copied to clipboard!
  Contents
Version
Is this page helpful?