Breaking Changes in Kotlin SDK Alpha

Learn about the breaking changes introduced in the Kotlin SDK.

  •   5 minute read  

This guide walks you through the breaking changes introduced in the Kotlin SDK.

Overview

The Kotlin SDK is built from scratch while retaining the core functionalities of the previous Android SDK.

Note the following before upgrading your SDK:

  • This SDK does not support automatic data migration from the previous Android SDK.
  • Any data persisted by the Android SDK is not carried over automatically.

SDK initialization

The way of intializing the Kotlin SDK has changed. See the following snippets for comparison:

RudderClient rudderClient = RudderClient.getInstance(
    this,
    WRITE_KEY,
    RudderConfig.Builder()
        .withDataPlaneUrl(DATA_PLANE_URL)
        .withLogLevel(RudderLogger.RudderLogLevel.VERBOSE)
        .build()
)

val analytics: Analytics = Analytics(
    configuration = Configuration(
        writeKey = BuildConfig.WRITE_KEY,
        application = application,
        dataPlaneUrl = BuildConfig.DATA_PLANE_URL,
        logLevel = Logger.LogLevel.VERBOSE,
    )
)

Event API changes

  • The following APIs are removed in the Kotlin SDK:
  • The following fields are updated in the Kotlin SDK:
Android (Legacy)Kotlin
RudderTraitsTraits
RudderPropertyProperties
warning
RudderMessageBuilder and RudderMessage are no longer used in the Kotlin SDK.

RudderOption changes

The way for creating a RudderOption instance has changed in the Kotlin SDK:

In this SDK, a RudderOption instance was created using method chaining:

val option = RudderOption()
          .putIntegration(CustomFactory.FACTORY, false)
          .putIntegration("Amplitude", false)
          .putExternalId("brazeExternalId", "<id>")

val traits = RudderTraits()
          .put("key", "value")

// Identify event is used just for demonstration purposes.
rudderClient.identify("user 1", traits, option)

In Kotlin SDK, RudderOption is instantiated using the constructor arguments instead of method chaining:

val option = RudderOption(
    customContext = buildJsonObject {
        put("key", "value")
    },
    integrations = buildJsonObject {
        put("Amplitude", true)
        put("INTERCOM", buildJsonObject {
            put("lookup", "phone")
        })
    },
    externalIds = listOf(
        ExternalId(type = "brazeExternalId", id = "<id>"),
    )
)

val traits = buildJsonObject {
    put("key-1", "value-1")
}

// Identify event is used just for demonstration purposes.
RudderAnalyticsUtils.analytics.identify(
    userId = "User1",
    traits = traits,
    options = option
)

Other API changes

MethodAndroid (Legacy)Kotlin
putIntegrationAccepted two arguments - type (String) and enabled (Boolean).Converted into constructor arguments and renamed to integrations of a single JsonObject type.
putCustomContextAccepted two arguments - type (String) and context (Map).Converted into constructor arguments and renamed to customContext of a single JsonObject type.
putExternalIdAccepted two arguments - type (String) and id (String).Converted into constructor arguments and renamed to externalIds of type List<ExternalId>, where <ExternalId> is a data class with a type (String) and id (String).

SDK configuration changes

The following table maps the SDK configuration options available in the Android SDK to the new Kotlin SDK:

Android (Legacy)Kotlin
withLogLevellogLevel
withDataPlaneUrldataPlaneUrl
withTrackLifecycleEventstrackApplicationLifecycleEvents
withNewLifecycleEventstrackApplicationLifecycleEvents
withTrackDeepLinkstrackDeepLinks
withAutoSessionTrackingsessionConfiguration
withSessionTimeoutMillissessionConfiguration
withRecordScreenViewstrackActivities
withGzipgzipEnabled
withCollectDeviceIdcollectDeviceId
withFactoryHandled via plugins. For example, analytics.add(BrazeIntegration())
withControlPlaneUrlcontrolPlaneUrl
withFlushQueueSizeCountFlushPolicy
withSleepcountFrequencyFlushPolicy
withEventDispatchSleepIntervalFrequencyFlushPolicy

Removed features

The following features are removed in the Kotlin SDK:

Feature updates

This section covers the different feature updates introduced in the Kotlin SDK:

Reset API

Android (Legacy)Kotlin
reset(true) clears anonymousIdanalytics.reset() clears anonymousId
reset(false) retains anonymousIdUse a custom plugin to retain anonymousId.

See this Sample plugin for more information.
info
To preserve the anonymousId value on a reset API call or meet a custom requirement, you can use a custom plugin to manage anonymousId for each event. Custom plugins let you modify the event payload as needed.

Flush configuration

Android (Legacy)Kotlin
The following configuration options are available:

  • withSleepcount
  • withFlushQueueSize
  • withEventDispatchSleepInterval
The following flush policies are available:

  • FrequencyFlushPolicy
  • CountFlushPolicy
  • StartupFlushPolicy

Gzip event requests

Android (Legacy)Kotlin
Enabled by defaultDisabled by default

Override anonymous ID

Android (Legacy)Kotlin
Use the putAnonymousId method.Use a custom plugin.

See this Sample plugin for more information.

Get user traits after identify call

Android (Legacy)Kotlin
Use the following snippet: val traits =

rudderClient!!.getRudderContext().getTraits()		Use the following snippet: val traits = analytics.traits

Set external ID / custom ID

Android (Legacy)Kotlin
Use the identify call to set externalId.You can set externalId for all events including the application lifecycle events by leveraging a custom plugin.

See this Sample plugin for more information.
The SDK persisted the externalId.You must persist the externalId manually.

Set the Android device token

Android (Legacy)Kotlin
Use the putDeviceToken method.Use a custom plugin.

See this Sample plugin for more information.

Set custom context

Android (Legacy)Kotlin
You can pass custom context during the SDK initialization.Support for this feature is removed. Use a custom plugin to set custom context for all events including automatically-tracked events (for example, lifecycle events).

See this Sample plugin for more information.

Set advertising ID

Android (Legacy)Kotlin
Use the putAdvertisingId method to set the advertisement ID.Use a custom plugin to automatically collect and set the advertisement ID.

See this Sample plugin for more information.

Enable/disable events for specific destinations

Android (Legacy)Kotlin
You can enable or disable event delivery for specific destination across all events while initializing the SDK or while sending events.Use a custom plugin to enable or disable event delivery for specific destinations across all event calls, including automatically tracked events (like lifecycle events) using the SDK.

See this Sample plugin for more information.

Session tracking and lifecycle events dependency

Android (Legacy)Kotlin
Session tracking is tightly coupled with automatic tracking of lifecycle events. That means you cannot use session tracking if automatic lifecycle tracking is disabled.Session tracking is decoupled with automatic tracking of lifecycle events. That means you can use the session tracking and automatic lifecycle event tracking mechanisms independently.

Questions? Contact us by email or on Slack