Breaking Changes in Swift SDK

Learn about the breaking changes introduced in the Swift SDK.

  •   5 minute read  

This document outlines the breaking changes introduced in the Swift SDK when migrating from the iOS (Legacy) SDK.

Overview

The Swift SDK is built from scratch while retaining the core functionalities of the iOS (Legacy) SDK.

Note the following before upgrading your SDK:

  • This SDK does not support automatic data migration from the previous iOS SDK.
  • Any data persisted by the iOS SDK is not carried over automatically.
  • The Swift SDK requires a higher minimum platform version (iOS 15.0+ vs iOS 12.0+).

SDK initialization

The way of initializing the Swift SDK has changed. See the following snippets for comparison:

import Rudder

let builder: RSConfigBuilder = RSConfigBuilder()
            .withDataPlaneUrl("<DATA_PLANE_URL>")

RSClient.getInstance("<WRITE_KEY>", config: builder.build())

import RudderStackAnalytics

let config = Configuration(
    writeKey: "<WRITE_KEY>",
    dataPlaneUrl: "<DATA_PLANE_URL>"
)
let analytics = Analytics(configuration: config)
info
The Swift SDK does not follow a singleton pattern. You will need to manage the Analytics instance yourself.

RudderOption changes

The way of creating a RudderOption instance has changed in the Swift SDK:

In the iOS (Legacy) SDK, an RSOption instance was created using method chaining:

let option = RSOption()
        .putIntegration("Amplitude", isEnabled: false)
        .putExternalId("brazeExternalId", withId: "some_external_id_1")
        .putCustomContext(["key": "value"], withKey: "customKey")
        
let traits = ["name": "John", "email": "john@example.com"]
        
RSClient.sharedInstance()?.identify("user123", traits: traits, options: option)

In the Swift SDK, a RudderOption instance is created using constructor arguments:

let externalId = ExternalId(type: "brazeExternalId", id: "some_external_id_1")
let option = RudderOption(
    integrations: ["Amplitude": false],
    customContext: ["customKey": ["key": "value"]],
    externalIds: [externalId]
)

let traits = ["name": "John", "email": "john@example.com"]

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

Other API changes

MethodiOS (Legacy)Swift
putIntegrationAccepts two arguments — type (String) and enabled (Boolean).Converted into constructor arguments and renamed to integrations of a single Dictionary type.
putCustomContextAccepts two arguments — type (String) and context (Dictionary).Converted into constructor arguments and renamed to customContext of a single Dictionary type.
putExternalIdAccepts two arguments — type (String) and id (String).Converted into constructor arguments and renamed to externalIds of type [ExternalId], where ExternalId is a class with a type (String) and id (String).
sharedInstanceSingleton pattern for accessing the client.No singleton pattern - you manage the Analytics instance.
getInstanceStatic method to initialize the client.Direct initialization with Analytics(configuration:).
reset()Deprecated method without parameters.Replaced with reset() that always clears anonymousId.
reset:(BOOL)clearAnonymousIdMethod with Boolean parameter to control anonymousId clearing.Use a custom plugin to retain anonymousId if needed.

SDK configuration changes

The following table maps the SDK configuration options available in the iOS (Legacy) SDK to the new Swift SDK:

iOS (Legacy)Swift
withDataPlaneUrldataPlaneUrl
withControlPlaneUrlcontrolPlaneUrl
withLogLevelHandled via LoggerAnalytics class
withDBCountThresholdHandled via CountFlushPolicy
withSleepTimeoutHandled via FrequencyFlushPolicy
withConfigRefreshIntervalHandled internally
withTrackLifecycleEventstrackApplicationLifecycleEvents
withRecordScreenViewsNot available. User can handle via custom plugins
withCollectDeviceIdcollectDeviceId
withGzipgzipEnabled
withAutomaticSessionTrackingHandled via SessionConfiguration.automaticSessionTracking
sessionInActivityTimeOutHandled via SessionConfiguration.sessionTimeoutInMillis
withFactoryNot available. (This feature will be handled in future releases)
flushQueueSizeCountFlushPolicy

Removed features

The following features are removed in the Swift SDK:

  • Database encryption - The dbEncryption configuration option is no longer available.
  • Background Mode - The enableBackgroundMode option is no longer available.
  • Direct context access - RSContext and getContext method are no longer available.
  • CocoaPods support - Only Swift Package Manager is supported.

Feature updates

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

Reset API

iOS (Legacy)Swift SDK
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

iOS (Legacy)Swift SDK
The following configuration options are available:

  • withSleepTimeout
  • withDBCountThreshold
  • flushQueueSize
The following flush policies are available:

  • FrequencyFlushPolicy
  • CountFlushPolicy
  • StartupFlushPolicy

Override anonymous ID

iOS (Legacy)Swift SDK
Use the putAnonymousId method.Use a custom plugin.

See this Sample plugin for more information.

Get user traits after identify call

iOS (Legacy)Swift SDK
Use the following snippet: RSContext *context = [[RSClient sharedInstance] context];

NSDictionary *traits = context.traits;		Use the following snippet: let traits = analytics.traits

Set external ID or custom ID

iOS (Legacy)Swift SDK
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 or use a custom plugin.

Set iOS device token

iOS (Legacy)Swift SDK
Use the putDeviceToken method.Use a custom plugin.

See this Sample plugin for more information.

Set custom context

iOS (Legacy)Swift SDK
You can pass custom context during the SDK initialization and via putCustomContext method.Support for global custom context during initialization is removed. Use a custom plugin to set custom context for all events including automatically-tracked events.

See this Sample plugin for more information.

Set advertising ID

iOS (Legacy)Swift SDK
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.

Filter events for specific destinations

iOS (Legacy)Swift SDK
You can enable or disable event delivery for specific destinations across all events while initializing the SDK or while sending events via RSOption.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

iOS (Legacy)Swift SDK
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.

Platform support

iOS (Legacy)Swift SDK
  • iOS 12.0+
  • tvOS 11.0+
  • watchOS 7.0+
  • iOS 15.0+
  • macOS 12.0+
  • tvOS 15.0+
  • watchOS 8.0+

Questions? Contact us by email or on Slack