Packages and Configuration Options

Updated

The SDK consists of a few packages. You’ll get the most value out of Customer.io when you use all our packages together, but this lets you omit packages for features you don’t intend to use.

SDK packages

To minimize our SDK’s impact on your app’s size, we’ve split the SDK into packages. You can limit your install to the packages that you need for your project. But, in most cases, you’ll want to install all the packages to get the most value out of Customer.io.

You must install the datapipelines package. It lets you identify people, which you must do before you can send them messages, etc. You’ll want to add the messaging-push-fcm and the messaging-in-app packages to send push notifications and in-app messages respectively.

Package ProductRequired?Description
datapipelines✅Identify people, track events, track anonymous activity
messaging-push-fcmReceive push notifications over Google Firebase Cloud Messaging (FCM)
messaging-in-appReceive in-app notifications

Configuration options

You’ll call configuration options before you initialize the SDK. 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—as shown in the example below.

If you’re in our EU region, you must set Region.EU.

val builder = CustomerIOConfigBuilder(
    applicationContext = this,
    cdpApiKey = "your_cdp_api_key"
).region(Region.US)
    .autoTrackDeviceAttributes(true)
    .autoTrackActivityScreens(false)
    .screenViewUse(ScreenView.All)
    .logLevel(CioLogLevel.DEBUG)
    .addCustomerIOModule(
        ModuleMessagingInApp(
            config = MessagingInAppModuleConfig.Builder(
                siteId = "your_site_id",
                region = Region.US
            ).setEventListener(InAppMessageEventListener()).build()
        )
    )
    .addCustomerIOModule(ModuleMessagingPushFCM())

CustomerIO.initialize(builder.build())
td style="text-align:left">ScreenView.All (Default): Screen events are sent to Customer.io. You can use these events to build segments, trigger campaigns, and target in-app messages.

ScreenView.InApp: Screen view events not sent to Customer.io. You’ll only use them to target in-app messages based on page rules.
OptionTypeDefaultDescription
cdpApiKeystringRequired: the key you'll use to initialize the SDK and send data to Customer.io
regionRegion.EU or Region.USRegion.USBecause we default to the US region, you must set this to Region.EU if your account is in the EU region.
apiHoststringThe domain you’ll proxy requests through. You’ll only need to set this (and cdnHost) if you’re proxying requests.
autoTrackDeviceAttributesbooleantrueAutomatically gathers information about devices, like operating system, device locale, model, app version, etc
autoTrackActivityScreensbooleanfalseIf true, the SDK automatically sends screen events for every screen your audience visits. If you use Jetpack Compose you should set this to false and track screens manually.
cdnHoststringThe domain you’ll fetch configuration settings from. You’ll only need to set this (and apiHost) if you’re proxying requests.
logLevelstringerrorSets the level of logs you can view from the SDK. Set to debug or info to see more logging output.
migrationSiteIdstringRequired if you're updating from 2.x: the credential for previous versions of the SDK. This key is used to send remaining tasks to Customer.io when your audience updates your app.
screenViewUseAll or InAppAll
trackApplicationLifecycleEventsbooleantrueSet to false if you don't want the app to send lifecycle events

Proxying requests

By default, requests go through our domain at cdp.customer.io. You can proxy requests through your own domain to provide a better privacy and security story, especially when submitting your app to app stores.

To proxy requests, you’ll need to set the apiHost and cdnHost properties in your SDKConfigBuilder. While these are separate settings, you should set them to the same URL.

While you need to initialize the SDK with a cdpApiKey, you can set this to any value you want. You only need to pass your actual key when you send requests from your server backend to Customer.io. If you want to secure requests to your proxy server, you can set the cdpApiKey to a value representing basic authentication credentials that you handle on your own. See proxying requests for more information.

val builder = CustomerIOConfigBuilder(
    applicationContext = this,
    cdpApiKey = "your_cdp_api_key"
)
    .region(Region.US)  // Optional but recommended
    .apiHost("your-proxy.example.com")
    .cdnHost("your-proxy.example.com")
    .addCustomerIOModule(ModuleMessagingPushFCM())

CustomerIO.initialize(builder.build())
Copied to clipboard!
  Contents
Version