iOS (Swift) SDK: Modern Analytics for Apple Platforms

The new iOS (Swift) SDK replaces the legacy iOS (Obj-C) SDK with a modern architecture designed for today’s Apple development practices. Built with async-await, it introduces a runtime-flexible plugin system, multi-instance support, and expands platform coverage to include macOS alongside iOS, tvOS, and watchOS.

RudderStack recommends using the iOS (Swift) SDK for all new Apple platform implementations. The legacy iOS (Obj-C) SDK continues to receive maintenance updates but no new features.

Why we built this

The legacy iOS SDK was built in Objective-C when it was the dominant language for Apple development. As Swift has matured and become the standard, developers expect type-safe APIs, structured concurrency, and modern language features that Objective-C cannot provide.

The legacy iOS (Obj-C) SDK locked integrations at configuration time, making runtime modifications impossible. Customers who needed custom event processing or filtering had to request SDK changes, creating bottlenecks and slowing their implementation timelines.

The iOS (Swift) SDK addresses these limitations with native Swift concurrency, a dynamic plugin system for runtime customization, and expanded platform support including macOS. It lets you use a single SDK across Apple platforms.

Key benefits

This section lists some key benefits of using the iOS (Swift) SDK.

Developer experience

• Modern Swift concurrency: Built with async-await and structured concurrency for non-blocking operations and better app responsiveness
• Enhanced identity access: Type-safe direct property access to anonymousId, userId, traits, and sessionId
• macOS support: Native support for macOS 12.0+ alongside iOS 15.0+, tvOS 15.0+, and watchOS 8.0+

Extensibility

• Plugin architecture: Dynamic plugin management lets you add, remove, and modify event processing without waiting for SDK updates
• Multi-instance support: Create multiple isolated analytics instances with independent state, storage, and configuration

Stability

• Shutdown API: Explicitly shut down and clean up SDK resources with event persistence across restarts

Maintainability

• Cleaner payloads: Removed redundant identity fields from context.traits for smaller, consistent event data

How to use the SDK

For installation, initialization, and API usage, see the iOS (Swift) SDK Quickstart. For configuration options, see SDK Configuration Options.

New and improved features

New features

• Plugin architecture: Add, remove, and customize plugins at runtime
• Multiple instances: Run separate SDK instances for different data sources
• Shutdown API: Clean up SDK resources during runtime with analytics.shutdown()

See New Features in iOS (Swift) SDK for more information.

Improved features

• Flexible reset API: Reset specific identity values (anonymousId, userId, traits, session) individually instead of all-or-nothing
• Enhanced custom context: Pass any JSON value type (strings, arrays, nested objects, booleans) to customContext, not just dictionaries
• Flexible integration options: Pass configuration objects to integrations instead of just boolean toggles
• ExternalId on all event types: Set externalId on track, screen, and group events—not just identify
• Direct destination instance access: Access destination plugin instances anytime with getDestinationInstance() instead of waiting for callbacks
• Custom logger: Configure centralized logging with pluggable implementations via LoggerAnalytics.setLogger()

See the Improved Features in iOS (Swift) SDK guide for more information.

Migrate from legacy iOS (Obj-C) SDK

The legacy iOS (Obj-C) SDK continues to work and receive maintenance updates, so you can migrate at your own pace.

The iOS (Swift) SDK introduces API and payload changes from the legacy iOS (Obj-C) SDK. For example, event payloads remove redundant identity fields such as context.traits.anonymousId, context.traits.userId, and context.traits.id.

If your downstream systems rely on these removed fields, update your transformations before migrating.

See the following guides for detailed API differences and migration steps:

• Breaking Changes in iOS (Swift) SDK
• Migration Guide: Migrate persisted user data (anonymousId, userId, traits, and so on)

Platform requirements

Resources

See the following resources for learning more about the iOS (Swift) SDK:

• iOS (Swift) SDK Overview
• New Features in iOS (Swift) SDK
• Plugin Architecture
• Improved Features
• Breaking Changes in iOS (Swift) SDK

The following guides will help you get started with the iOS (Swift) SDK:

• Quickstart Guide
• SDK Configuration Options
• Migration Guide