# Breaking Changes in iOS (Swift) SDK


This document outlines the breaking changes introduced in the iOS (Swift) SDK when migrating from the legacy [iOS SDK v2]({{< ref "sources/event-streams/sdks/rudderstack-ios-sdk/ios-v2.md" >}}).

## Package & import changes

The SDK has been renamed from `Rudder` to `RudderStackAnalytics`. Update your package dependencies and import statements throughout your codebase.

{{< tabs tabTotal="2" >}}
{{% tab tabName="Installation" %}}
```swift
// Old
.package(url: "git@github.com:rudderlabs/rudder-sdk-ios.git", from: "2.5.1-beta")
.product(name: "Rudder", package: "rudder-sdk-ios")

// New
.package(url: "https://github.com/rudderlabs/rudder-sdk-swift.git", from: "1.0.0")
.product(name: "RudderStackAnalytics", package: "rudder-sdk-swift")
```
{{% /tab %}}
{{% tab tabName="Import" %}}
```swift
// Old
import Rudder

// New
import RudderStackAnalytics
```
{{% /tab %}}
{{< /tabs >}}

## Initialization

The singleton pattern (`RSClient.sharedInstance()`) has been replaced with an instance-based approach.

{{< tabs tabTotal="2" >}}
{{% tab tabName="iOS SDK v2 — Legacy" %}}

```swift
let config = RSConfig(writeKey: "WRITE_KEY")
    .dataPlaneURL("<https://data-plane.com>")
RSClient.sharedInstance().configure(with: config)

// Usage anywhere
RSClient.sharedInstance().track("Event")
```
{{% /tab %}}
{{% tab tabName="iOS (Swift)" %}}

```swift
let configuration = Configuration(
    writeKey: "WRITE_KEY",
    dataPlaneUrl: "<https://data-plane.com>"
)
let analytics = Analytics(configuration: configuration)

// Store and use the instance
analytics.track(name: "Event")
```
{{% /tab %}}
{{< /tabs >}}

## Public classes renamed

All public classes have been renamed to remove the `RS` prefix in favor of clearer, more descriptive names. Find and replace all references in your codebase.

| Old | New |
| --- | --- |
| `RSClient` | `Analytics` |
| `RSConfig` | `Configuration` |
| `RSOption` | `RudderOption` |
| `RSMessage` | `Event` |
| `RSPlugin` | `Plugin` |
| `RSEventPlugin` | `EventPlugin` |
| `RSDestinationPlugin` | `IntegrationPlugin` |
| `RSLogLevel` | `LogLevel` |

## API method signatures

All tracking methods now use explicit named parameters for better code readability and Swift conventions. The first parameter is no longer anonymous, and `option` has been renamed to `options`.

| Method | iOS SDK v2 — Legacy | iOS (Swift) |
| --- | --- | --- |
| Track | `track(_:properties:option:)` | `track(name:properties:options:)` |
| Identify | `identify(_:traits:option:)` | `identify(userId:traits:options:)` |
| Screen | `screen(_:category:properties:option:)` | `screen(screenName:category:properties:options:)` |
| Group | `group(_:traits:option:)` | `group(groupId:traits:options:)` |
| Alias | `alias(_:option:)` | `alias(newId:previousId:options:)` |
| Reset | `reset()` | `reset(options:)` |

## Type changes

Several numeric types have changed to `UInt64` for consistency and to support larger values. Note that flush interval units changed from seconds to milliseconds for finer control.

| Field | iOS SDK v2 — Legacy | iOS (Swift) |
| --- | --- | --- |
| Session ID | `Int` | `UInt64` |
| Session timeout | `Int` <br/> <span style="color: #4D4DFF;font-size:12px;">Milliseconds</span> | `UInt64` <br/> <span style="color: #4D4DFF;font-size:12px;">Milliseconds</span> |
| Flush interval | `Int` <br/> <span style="color: #4D4DFF;font-size:12px;">Seconds</span> | `UInt64` <br/> <span style="color: #4D4DFF;font-size:12px;">Milliseconds</span> |

An example for session management is shown below:

```swift
// Old
RSClient.sharedInstance().startSession(1234567890)  // Int

// New
analytics.startSession(sessionId: 1234567890)  // UInt64
```

## Plugin execution stages

Plugin execution stages have been renamed to better describe their purpose in the event processing pipeline. The `.after` stage has been removed — use `.terminal` or `.utility` instead.

| iOS SDK v2 — Legacy | iOS (Swift) |
| --- | --- |
| `.before` | `.preProcess` |
| `.enrichment` | `.onProcess` |
| `.destination` | `.terminal` |
| `.after` | **Removed** |
| `.utility` | `.utility` |

## Configuration mappings

The builder pattern (`RSConfig().method().method()`) has been replaced with a standard Swift initializer. Session-related settings are now grouped in a separate `SessionConfiguration` object. 

Use the below table as a reference when updating your configuration code:

| iOS SDK v2 — Legacy (`RSConfig`) | iOS (Swift) SDK (`Configuration`) |
| --- | --- |
| `writeKey` | `writeKey` |
| `dataPlaneURL(_:)` | `dataPlaneUrl`  |
| `controlPlaneURL(_:)` | `controlPlaneUrl`  |
| `loglevel(_:)` | Handled via `LoggerAnalytics` class |
| `trackLifecycleEvents(_:)` | `trackApplicationLifecycleEvents` |
| `recordScreenViews(_:)` | Not available. For UIKit-based apps, you can implement automatic screen tracking using a [custom plugin]({{< ref "sources/event-streams/sdks/client-side-features/plugin-architecture/create-custom-plugin.md" >}}). <br /><br />See the [UIKitAutomaticScreenTrackingPlugin](https://github.com/rudderlabs/rudder-sdk-swift/blob/main/Examples/SwiftExample/SwiftExample/CustomPlugins/UIKitAutomaticScreenTrackingPlugin.swift) example for more information. |
| `flushQueueSize(_:)` | `CountFlushPolicy` |
| `sleepTimeOut(_:)` | Handled via `FrequencyFlushPolicy` |
| `dbCountThreshold(_:)` | Handled via `CountFlushPolicy` |
| `autoSessionTracking(_:)` | Handled via `SessionConfiguration.automaticSessionTracking` |
| `sessionTimeout(_:)` | Handled via `SessionConfiguration.sessionTimeoutInMillis` |

## Removed features

The following features are removed in the iOS (Swift) SDK:

- `MessageContext` and `context` call are no longer available.
- `CocoaPods` is not supported — only Swift Package Manager is supported.
- Automatic screen tracking (`recordScreenViews`) is no longer available. For UIKit-based apps, you can implement automatic screen tracking using a [custom plugin]({{< ref "sources/event-streams/sdks/client-side-features/plugin-architecture/create-custom-plugin.md" >}}). See the [UIKitAutomaticScreenTrackingPlugin](https://github.com/rudderlabs/rudder-sdk-swift/blob/main/Examples/SwiftExample/SwiftExample/CustomPlugins/UIKitAutomaticScreenTrackingPlugin.swift) example for more information.

## Migration from iOS v2 SDK

See the [Migration Guide]({{< ref "sources/event-streams/sdks/swift-sdk/migration-guide/ios-v2.md" >}}) for detailed instructions on migrating from the legacy iOS SDK v2 to the iOS (Swift) SDK.

<br />