# Upgrade from 3x to 4x

This page details breaking changes from the previous major version of the SDK, so you understand the development effort required to update your app and take advantage of the latest features.

## What changed?[](#what-changed)

This update provides native support for our new integrations framework. While this represents a significant change “under the hood,” we’ve tried to make it as seamless as possible for you; much of your implementation remains the same.

This move also adds two additional features:

*   **Support for anonymous tracking**: you can send events and other activity for anonymous users, and we’ll reconcile that activity with a person when you identify them.
*   **Built-in lifecycle events**: the SDK now automatically captures events like “Application Installed” and “Application Updated” for you.
*   **New device-level data**: the SDK captures the device `name` and other device-level context for you.

When you’re done, you’ll be able to use your app data’s in both Customer.io *and* other downstream destinations—like your analytics platform, data warehouse, or CRM. All that *and* you’ll be prepared to accept new features and improvements that we roll out in the future!

## Upgrade process[](#upgrade-process)

You’ll update initialization calls for the SDK itself and the push and/or in-app messaging modules.

**As a part of this process, your credentials change**. You’ll need to set up a new integration in Customer.io and get the *CDP API Key* you’ll use to initialize the SDK. But you’ll *also* need to keep your previous `siteId` as a `migrationSiteId` when you initialize the SDK. The `migrationSiteId` is a key helps the SDK send remaining traffic when people update your app.

When you’re done, you’ll also need to change a few base properties to fit the new APIs. In general, `identifier` becomes `userId`, `body` becomes `traits`, and `data` becomes `properties`.

### 1\. Get your new *CDP API Key*[](#1-get-your-new-cdp-api-key)

The new version of the SDK requires you to set up a new integration in Customer.io. As a part of this process, you’ll get your *CDP API Key*.

1.  Go to [*Data & Integrations* > *Integrations*](https://fly.customer.io/workspaces/last/journeys/integrations/all/overview) and click **Add Integration**.
2.  Select **Android**.
    
    [![set up your android source](https://docs.customer.io/images/cdp-android-source.png)](#ca6b19a9972ef425e33c8ce9c19c2744-lightbox)
    
3.  Enter a *Name* for your integration, like “My Android App”.
4.  We’ll present you with a code sample containing a `cdpApiKey` that you’ll use to initialize the SDK. Copy this key and keep it handy.
5.  Click **Complete Setup** to finish setting up your integration.
    
    [![Set your name, get your CDP API Key, and click Complete Setup](https://docs.customer.io/images/cdp-android-source-setup.png)](#61f1ba08da415a2bac90e7b32907faf7-lightbox)
    

Now the *Integrations* page shows that your Android integration is connected to your workspace. You can also [connect your Android integration to other services](/integrations/data-out/add-destination/) if you want to send your mobile data to other places outside of Customer.io—like your analytics provider, data warehouse, or CRM.

### 2\. Import datapipelines instead of tracking[](#2-import-datapipelines-instead-of-tracking)

We’ve replaced the `tracking` package with `datapipelines`. You’ll need to update your import statements to reflect this change.

```groovy
// replace `tracking` with:
implementation 'io.customer.android:datapipelines:4.17.0'
```

### 3\. Update your initialization[](#3-update-your-initialization)

You’ll initialize the new version of the SDK and its packages with `SDKConfigBuilder` objects instead of a `CustomerIOConfig`. A few of the configuration options changed. In particular,

*   `CustomerIOBuilder` replaces `CustomerIO.Builder`.
*   `cdpApiKey` replaces `apiKey`: this is a new key that you got from [Step 1](#1-get-your-new-cdp-api-key)
*   `migrationSiteId` replaces `siteId`: this is the same key you used in the previous version of the SDK. **You need to include this property** to send remaining traffic when people update your app.
*   `AutoTrackActivityScreens` replaces `autoTrackScreenViews`: functionality is unchanged.
*   The `messagingInApp` module now includes a site ID and region—these tell the SDK which workspace your in-app messages come from.

```kotlin
CustomerIOBuilder(
   applicationContext = this,
   // new credentials
   cdpApiKey = "your_cdp_api_key"
   migrationSiteId = "your_site_id"
).apply {
  // If you're in the EU, set Region.EU
   region(Region.US)
   addCustomerIOModule(
      ModuleMessagingInApp(
        // the in-app module now has its own configuration
         config = MessagingInAppModuleConfig.Builder(
            siteId = "your_site_id",
            region = Region.US
         ).setEventListener(InAppMessageEventListener()).build()
      )
   )
   addCustomerIOModule(ModuleMessagingPushFCM())
   build()
}
```

### 4\. Update your `identify`, `track`, and `screen` calls[](#4-update-your-identify-track-and-screen-calls)

Our APIs changed slightly in this release. We’ve done our best to make the new APIs as similar as possible to the old ones. The names of a few properties that you’ll pass in your calls have changed, but their functionality has not.

*   `identify`: `identifier` becomes `userId` and `body` becomes `traits`
*   `track`: `data` becomes `properties`
*   `screen`: `name` becomes `title`, and `data` becomes `properties`

We’ve highlighted changes in the sample below.

```kotlin
//identify: identifier becomes userId, body becomes traits
CustomerIO.instance()
  .identify(
    userId = "USER_ID",
    traits = mapOf("first_name" to "firstName")
  )

// track: data becomes properties
CustomerIO.instance().track(
  name = "purchase",
  properties = mapOf("product" to "socks", "price" to "4.99")
)

// screen: name becomes title, data becomes properties
CustomerIO.instance().screen(
  title = "purchase",
  properties = mapOf("product" to "socks", "price" to "4.99"),
  category: String = "" // optional
)
```

## Configuration Changes[](#configuration-changes)

As a part of this release, we’ve changed a few configuration options. The `MessagingInApp` and `MessagingPush` modules also now take their own configuration options.

### `datapipelines` configuration options[](#datapipelines-configuration-options)

For the base SDK, you’ll use `SDKConfigBuilder` to set your configuration options. The following table shows the changes to the configuration options.

Field

Type

Default

Description

`cdpApiKey`

string

Replaces `apiKey`; required to initialize the SDK and send data to Customer.io.

`migrationSiteId`

string

Replaces `siteId`; required if you’re updating from 2.x. This is the key representing your previous version of the SDK.

`AutoTrackActivityScreens`

boolean

`false`

Replaces `autoTrackScreenViews`; functionality is unchanged. We simply renamed the option to reflect support for UIKit and *not* SwiftUI.

`trackApplicationLifeCycleEvents`

boolean

`true`

When true, the SDK automatically tracks application lifecycle events (like *Application Installed*).

### `MessagingInApp` configuration options[](#messaginginapp-configuration-options)

When you initialize the `MessagingInApp` package, **you must pass both of these configuration options**.

Option

Type

Default

Description

`siteId`

string

The [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 *Workspace Settings* > *API Credentials*](https://fly.customer.io/env/last/settings/api_credentials) from a set of Track API credentials; this determines the workspace that your app listens for in-app messages from.

`Region`

`.US` or `.EU`

`.US`

The region your Customer.io account resides in—US or EU.