Analytics for Swift Migration Guide
Analytics Swift supports these destinations with more to come.
Getting Started
If you’re using a different mobile library such as Analytics-iOS, follow these steps to migrate to the Analytics-Swift library.
This guide assumes you already have a Source in your Segment workspace. If you are creating a new one you can reference the Source Overview Guide
Segment no longer supports installing Analytics-Swift through Cocoapods.
Add the SDK as a Dependency
- Open your project in Xcode.
- If using Xcode 12, go to File > Swift Packages > Add Package Dependency…. If using Xcode 13, go to File > Add Packages…
- Enter the git path
git@github.com:segmentio/analytics-swift.gitfor the Package Repository and click Next. - Select the version rules for your application and click Next.
- Make sure the Segment Library checkbox is selected.
- Click Finish.
You have now added Analytics-Swift to your project. Segment and Sovran show as Swift package dependencies.
Modify your initialized instance.
let configuration = Configuration(writeKey: "YOUR_WRITE_KEY")
configuration.trackApplicationLifecycleEvents = true
configuration.flushAt = 3
configuration.flushInterval = 10
Analytics.setup(with: configuration)
SEGConfiguration *config = [[SEGConfiguration alloc] initWithWriteKey:@"<writekey>"];
config.trackApplicationLifecycleEvents = YES;
_analytics = [[SEGAnalytics alloc] initWithConfiguration: config];
Convert Middlewares to Plugins
Middlewares are a powerful mechanism that can augment events collected by the Analytics iOS (Classic) SDK. A middleware is a simple function that is invoked by the Segment SDK and can be used to monitor, modify, augment or reject events. Analytics Swift replaces the concept of middlewares with Enrichment Plugins to give you even more control over your event data. Refer to the Plugin Architecture Overview for more information.
Source middleware
Before example
let customizeAllTrackCalls = BlockMiddleware { (context, next) in
if context.eventType == .track {
next(context.modify { ctx in
guard let track = ctx.payload as? TrackPayload else {
return
}
let newEvent = "[New] \(track.event)"
var newProps = track.properties ?? [:]
newProps["customAttribute"] = "Hello"
ctx.payload = TrackPayload(
event: newEvent,
properties: newProps,
context: track.context,
integrations: track.integrations
)
})
} else {
next(context)
}
}
analytics.sourceMiddleware = [customizeAllTrackCalls]
After example
class customizeAllTrackCalls: EventPlugin {
let type: PluginType = .enrichment
let analytics: Analytics
public func track(event: TrackEvent) -> TrackEvent? {
var workingEvent = event
workingEvent.event = "[New] \(event.event)"
workingEvent.properties["customAttribute"] = "Hello"
return workingEvent
}
}
analytics.add(plugin: customizeAllTrackCalls())
Destination middleware
If you don’t need to transform all of your Segment calls, and only want to transform the calls going to specific, device-mode destinations, use Destination plugins.
Before example
// define middleware we'll use for amplitude
let customizeAmplitudeTrackCalls = BlockMiddleware { (context, next) in
if context.eventType == .track {
next(context.modify { ctx in
guard let track = ctx.payload as? TrackPayload else {
return
}
let newEvent = "[Amplitude] \(track.event)"
var newProps = track.properties ?? [:]
newProps["customAttribute"] = "Hello"
ctx.payload = TrackPayload(
event: newEvent,
properties: newProps,
context: track.context,
integrations: track.integrations
)
})
} else {
next(context)
}
}
// configure destination middleware for amplitude
let amplitude = SEGAmplitudeIntegrationFactory.instance()
config.use(amplitude)
config.destinationMiddleware = [DestinationMiddleware(key: amplitude.key(), middleware:[customizeAmplitudeTrackCalls])]
After example
class customizeAllTrackCalls: EventPlugin {
let type: PluginType = .enrichment
let analytics: Analytics
public func track(event: TrackEvent) -> TrackEvent? {
var workingEvent = event
workingEvent.event = "[New] \(event.event)"
workingEvent.properties["customAttribute"] = "Hello"
return workingEvent
}
}
// create an instance of the Amplitude plugin
let amplitudeDestination = AmplitudeDestination()
// add our enrichment plugin to amplitude
amplitudeDestination.add(plugin: customizeAmplitudeTrackCalls())
// add amplitude to analytics instance.
analytics.add(plugin: amplitudeDestination)
Update your config options
Segment changed these config options:
| Before | After |
|---|---|
defaultProjectSettings |
Name changed to defaultSettings |
Segment added these options:
| Name | Details |
|---|---|
autoAddSegmentDestination |
The analytics client automatically adds the Segment Destination. Set this to false if you want to customize the initialization of the Segment Destination, such as, add destination middleware. |
Segment deprecated these options:
| Deprecated Option | Details |
|---|---|
enableAdvertisingTracking |
Deprecated |
launchOptions |
Deprecated in favor of the enrichment plugin that adds the default data to the event payloads. |
maxQueueSize |
Deprecated |
recordScreenViews |
Deprecated in favor of a plugin that provides the same functionality. Use the UIKitScreenTracking plugin. |
shouldUseBluetooth |
Deprecated |
shouldUseLocationServices |
Deprecated |
trackAttributionData |
This feature no longer exists. |
trackInAppPurchases |
Deprecated |
trackPushNotifications |
Deprecated |
Add destination plugins
You should remove all of your Analytics iOS (Classic) device-mode destinations as they are not compatible with Analytics Swift
Segment previously used Factories to initialize destinations. With Analytics Swift, Segment treats destinations similar to plugins and simplifies the process in adding them. Refer to the Plugin Architecture Overview for more information.
Before example
analyticsConfig.use(FooIntegrationFactory.instance()
let analytics = Analytics.setup(with: analyticsConfig)
After example
let destination = /* initialize your desired destination */
analytics.add(plugin: destination)
Modify your tracking methods
Identify
Before example
analytics.identify(userId: "a user's id", traits: ["firstName": "John", "lastName": "Doe"])
After example
// The newer APIs promote the use of strongly typed structures to keep codebases legible
struct UserTraits(
let firstName: String,
let lastName: String
)
analytics.identify("a user's id", UserTraits(firstName = "John", lastName = "Doe"))
Track
Before example
analytics.track("Item Purchased", properties: ["item": "Sword of Heracles", "revenue": 2.95])
After example
// The newer APIs promote the use of strongly typed structures to keep codebases legible
struct ItemPurchasedProperties(
let item: String
let revenue: Double
)
analytics.track(
name: "Item Purchased",
properties: ItemPurchasedProperties(
item = "Sword of Heracles",
price = 2.95
)
)
Group
Before example
analytics.identify(userId: "a user's id", traits: ["firstName": "John", "lastName": "Doe"])
After example
// The newer APIs promote the use of strongly typed structures to keep codebases legible
struct GroupTraits(
let name: String
let description: String
)
analytics.group(groupId: "group123", traits: GroupTraits(name = "Initech", description = "Accounting Software"))
Screen
Before example
analytics.screen("Photo Feed", properties: ["Feed Type": "private"])
After example
// The newer APIs promote the use of strongly typed structures to keep codebases legible
struct FeedScreenProperties(
let feedType: Int
)
analytics.screen(title: "Photo Feed", properties: FeedScreenProperties(feedType = "private"))
Alias
Before example
analytics.alias("new id");
After example
analytics.alias(newId: "new id")
This page was last modified: 11 May 2023
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!