iOS SDK Migration Guide
The new version of Amplitude's iOS SDK (Amplitude-Swift
) features a plugin architecture, built-in type definition and broader support for front-end frameworks. The new version isn't backwards compatible with Amplitude-iOS
.
To migrate to Amplitude-Swift
, update your dependencies and instrumentation.
Terminology¶
Amplitude-iOS
: Maintenance iOS SDKAmplitude-Swift
: New iOS SDK
Dependencies¶
CocoaPods¶
Add AmplitudeSwift
dependency to Podfile
.
- pod 'Amplitude', '~> 8.14'
+ pod 'AmplitudeSwift', '~> 1.0'
Swift Package Manager¶
Enter https://github.com/amplitude/Amplitude-Swift
into the search bar.
- `https://github.com/amplitude/Amplitude-iOS`
+ `https://github.com/amplitude/Amplitude-Swift`
Carthage¶
Add amplitude/Amplitude-Swift
to your Cartfile
.
- github "amplitude/Amplitude-iOS" ~> 8.14
+ github "amplitude/Amplitude-Swift" ~> 1.0
Instrumentation¶
This SDK offers an API to instrument events. To migrate to the new SDK, you need to update a few calls. The following sections detail which calls have changed.
Initialization¶
Like all other calls, instance()
has been removed. Configuration is handled differently between the maintenance iOS and new iOS SDK. The new iOS SDKs use the Configuration object to set the configuration. See Configuration.
- import Amplitude
+ import AmplitudeSwift
- Amplitude.instance().trackingSessionEvents = true
- Amplitude.instance().initializeApiKey("YOUR-API-KEY")
+ let amplitude = Amplitude(configuration: Configuration(
+ apiKey: "YOUR-API-KEY",
+ defaultTracking: DefaultTrackingOptions(
+ sessions: true
+ )
+ ))
- #import "Amplitude.h"
+ @import AmplitudeSwift;
- [Amplitude instance].trackingSessionEvents = true;
- [[Amplitude instance] initializeApiKey:@"YOUR-API-KEY"];
+ AMPConfiguration* configuration = [AMPConfiguration initWithApiKey:@"YOUR-API-KEY"];
+ configuration.defaultTracking.sessions = true;
+ Amplitude* amplitude = [Amplitude initWithConfiguration:configuration];
Configuration¶
The configurations for the new SDK are simpler and more consistent across runtimes.
Amplitude-iOS | Amplitude-Swift |
---|---|
amplitude.instanceWithName("YOUR-INSTANCE-NAME") |
config.instanceName |
amplitude.useDynamicConfig |
NOT SUPPORTED. |
amplitude.setServerUrl("YOUR-SERVER-URL") |
config.serverUrl |
amplitude.setServerZone("AMPServerZone.EU or AMPServerZone.US") |
config.serverZone |
amplitude.trackingOptions |
config.trackingOptions |
amplitude.trackingSessionEvents |
config.defaultTracking.sessions |
amplitude.minTimeBetweenSessionsMillis |
config.minTimeBetweenSessionsMillis |
amplitude.eventUploadMaxBatchSize |
config.flushQueueSize |
amplitude.eventUploadThreshold |
config.flushQueueSize |
amplitude.eventUploadPeriodSeconds |
config.flushIntervalMillis |
Set max retries count. NOT SUPPORTED. | config.flushMaxRetries |
amplitude.eventMaxCount |
NOT SUPPORTED. |
amplitude.optOut |
config.optOut |
amplitude.enableCoppaControl() or amplitude.disableCoppaControl() |
config.enableCoppaControl |
Customize storage provider. NOT SUPPORTED. | config.storageProvider |
Set up log level. NOT SUPPORTED. | config.logLevel |
Customize logger provider. NOT SUPPORTED. | config.loggerProvider |
deviceId and userId don't have a minimum length. |
Minimum length is 5. config.minIdLength overwrites the minimum length ofdeviceId and userId . |
Partner Id for partner integrations. NOT SUPPORTED. | config.partnerId |
The event callback. NOT SUPPORTED. See middleware. | config.callback |
amplitude.libraryName |
NOT SUPPORTED. |
amplitude.libraryVersion |
NOT SUPPORTED. |
amplitude.adSupportBlock |
NOT SUPPORTED. See Plugins. |
amplitude.useAdvertisingIdForDeviceId |
NOT SUPPORTED. See Plugins. |
amplitude.locationInfoBlock |
amplitude.locationInfoBlock |
amplitude.deferCheckInForeground |
NOT SUPPORTED. |
amplitude.setOffline(Yes) |
NOT SUPPORTED. |
amplitude.setContentTypeHeader("YOUR-CONTENT-TYPE-HEADER") |
NOT SUPPORTED. |
amplitude.setPlan(plan) |
config.plan |
plan.setBranch("YOUR-BRANCH") |
config.plan.branch |
plan.setSource("YOUR-SOURCE") |
config.plan.source |
plan.setVersion("YOUR-VERSION") |
config.plan.version |
plan.setVersionId("YOUR-VERSION-ID") |
config.plan.versionId |
amplitude.setTrackingOptions(options) |
config.trackingOptions |
amplitude.setSessionId(timestamp) |
NOT SUPPORTED. |
Tracking events¶
The maintenance iOS SDK offered a variety of logEvent
APIs with withEventProperties
, withApiProperties
, withUserProperties
, withGroup
, withGroupProperties
, withTimestamp
, outOfSession
, to override specific properties in the event payload. Amplitude has simplified all these variations into a unified track
API.
logEvent()
¶
The logEvent()
API maps to track()
.
let eventType = "Button Clicked"
let eventProperties: [String: Any] = ["key": "value"]
- Amplitude.instance().logEvent(
- eventType,
- withEventProperties: eventProperties
- )
+ let event = BaseEvent(
+ eventType: eventType,
+ eventProperties: eventProperties
+ )
+ amplitude.track(event)
NSString* eventType = @"Button Clicked";
NSDictionary* eventProperties = @{@"key": @"value"};
- [[Amplitude instance] logEvent:eventType withEventProperties:eventProperties];
+ AMPBaseEvent* event = [AMPBaseEvent initWithEventType:eventType
+ eventProperties:eventProperties];
+ [amplitude track:event];
logEvent withTimestamp
¶
The logEvent()
API maps to track()
.
let eventType = "Button Clicked"
let timestamp = Int64(NSDate().timeIntervalSince1970 * 1000)
- Amplitude.instance().logEvent(
- eventType,
- withTimestamp: timestamp
- )
+ let event = BaseEvent(
+ eventType: eventType,
+ timestamp: timestamp
+ )
+ amplitude.track(event)
NSString* eventType = @"Button Clicked";
NSNumber* timestamp = [NSNumber numberWithLongLong:[[NSDate date] timeIntervalSince1970] * 1000];
- [[Amplitude instance] logEvent:eventType withTimestamp:timestamp];
+ AMPBaseEvent* event = [AMPBaseEvent initWithEventType:eventType];
+ event.timestamp = [timestamp longLongValue];
+ [amplitude track:event];
logEvent withGroup
¶
The logEvent()
API maps to track()
.
let eventType = "Button Clicked"
let eventProperties: [String: Any] = ["key": "value"]
let groups: [String: Any] = ["orgId": 10]
- Amplitude.instance().logEvent(
- eventType,
- withEventProperties: eventProperties,
- withGroups: groups
- )
+ let event = BaseEvent(
+ eventType: eventType,
+ eventProperties: eventProperties,
+ groups: groups
+ )
+ amplitude.track(event)
NSString* eventType = @"Button Clicked";
NSDictionary* eventProperties = @{@"key": @"value"};
- NSDictionary* groups = @{@"orgId": @"10"};
- [[Amplitude instance] logEvent:eventType
- withEventProperties:eventProperties
- withGroups:groups];
+ AMPBaseEvent* event = [AMPBaseEvent initWithEventType:eventType
+ eventProperties:eventProperties];
+ [event.groups set:@"orgId" value:@"10"];
+ [amplitude track:event];
uploadEvents()
¶
The uploadEvents()
API maps to flush()
.
- Amplitude.instance().uploadEvents()
+ amplitude.flush()
- [[Amplitude instance] uploadEvents];
+ [amplitude flush];
Set user properties¶
The APIs for setting user properties are the same, except for the removal of instance()
. Here are code snippets to migrate APIs for user properties.
setUserId()
¶
Id length limit
The maintenance SDK uses an old SDK endpoint (api2.amplitude.com
) which enforces no length limit for deviceId
and userId
. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi
) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength
to a smaller value if you allowed identifiers with fewer than 5 characters.
Setting a user ID can be invoked on amplitude
without calling getInstance()
.
let userId = "TEST-USER-ID"
- Amplitude.instance().setUserId(userId)
+ amplitude.setUserId(userId: userId)
NSString* userId = @"TEST-USER-ID";
- [[Amplitude instance] setUserId:userId];
+ [amplitude setUserId:userId];
setDeviceId()
¶
Id length limit
The maintenance SDK uses an old SDK endpoint (api2.amplitude.com
) which enforces no length limit for deviceId
and userId
. The latest SDK uses Amplitude's HTTP V2 API (api2.amplitude.com/2/httpapi
) and requires identifiers to be at least 5 characters by default. When you migrate to the latest SDK, set config.minIdLength
to a smaller value if you allowed identifiers with fewer than 5 characters.
Set a device ID on amplitude
without calling instance()
.
let deviceId = "TEST-DEVICE-ID"
- Amplitude.instance().setDeviceId(deviceId)
+ amplitude.setDeviceId(deviceId: deviceId)
NSString* deviceId = @"TEST-DEVICE-ID";
- [[Amplitude instance] setDeviceId:deviceId];
+ [amplitude setDeviceId:deviceId];
clearUserProperties()
¶
The clearUserProperties
API has been removed, but you can now use the unified identify
API to remove user properties.
- Amplitude.instance().clearUserProperties()
+ let identify = Identify()
+ identify.clearAll()
+ amplitude.identify(identify: identify)
- [[Amplitude instance] clearUserProperties];
+ AMPIdentify* identify = [AMPIdentify new];
+ [identify clearAll];
+ [amplitude identify:identify];
setUserProperties()
¶
The setUserProperties
API has been removed, but you can now use the unified identify
API to add user properties.
- Amplitude.instance().setUserProperties([
- "membership": "paid",
- "payment": "bank",
- ])
+ amplitude.identify(userProperties: [
+ "membership": "paid",
+ "payment": "bank"
+ ])
- [[Amplitude instance] setUserProperties:@{
- @"membership": @"paid",
- @"payment": @"bank"
- }];
+ AMPIdentify* identify = [AMPIdentify new];
+ [identify set:@"membership" value:@"paid"];
+ [identify set:@"payment" value:@"bank"];
+ [amplitude identify:identify];
identify()
¶
You can now make an identify call on amplitude
without calling instance()
.
- let identify = AMPIdentify()
- identify.set("membership", value: "paid")
- Amplitude.instance().identify(identify)
+ let identify = Identify()
+ identify.set(property: "membership", value: "paid")
+ amplitude.identify(identify: identify)
AMPIdentify* identify = [AMPIdentify new];
[identify set:@"membership" value:@"paid"];
- [[Amplitude instance] identify:identify];
+ [amplitude identify:identify];
Set group properties¶
groupIdentify()
¶
You can now make an identify call on amplitude
without calling instance()
.
- let identify = AMPIdentify()
- identify.set("membership", value: "paid")
- Amplitude.instance().groupIdentify(
- withGroupType: "TEST-GROUP-TYPE",
- groupName: "TEST-GROUP-NAME",
- groupIdentify: identify
- )
+ let identify = Identify()
+ identify.set(property: "membership", value: "paid")
+ amplitude.groupIdentify(
+ groupType: "TEST-GROUP-TYPE",
+ groupName: "TEST-GROUP-NAME",
+ identify: identify
+ )
AMPIdentify* identify = [AMPIdentify new];
[identify set:@"membership" value:@"paid"];
- [[Amplitude instance] groupIdentifyWithGroupType:@"TEST-GROUP-TYPE"
- groupName:@"TEST-GROUP-NAME"
- groupIdentify:identify];
+ [amplitude groupIdentify:@"TEST-GROUP-TYPE"
+ groupName:@"TEST-GROUP-NAME"
+ identify:identify];
Tracking revenue¶
logRevenueV2()
¶
Track revenue using revenue()
API on amplitude
without calling instance()
.
- let revenue = AMPRevenue()
- revenue.setProductIdentifier("productIdentifier")
- revenue.setQuantity(3)
- revenue.setPrice(NSNumber(value: 3.99))
- Amplitude.instance().logRevenueV2(revenue)
+ let revenue = Revenue()
+ revenue.productId = "productIdentifier"
+ revenue.quantity = 3
+ revenue.price = 3.99
+ amplitude.revenue(revenue: revenue)
AMPRevenue* revenue = [AMPRevenue new];
- [revenue setProductIdentifier:@"productidentifier"];
- [revenue setQuantity:3];
- [revenue setPrice:@3.99];
- [[Amplitude instance] logRevenueV2:revenue];
+ revenue.productId = @"productidentifier";
+ revenue.quantity = 3;
+ revenue.price = 3.99;
+ [amplitude revenue:revenue];
Patterns¶
Plugins¶
The configs amplitude.adSupportBlock
or amplitude.useAdvertisingIdForDeviceId
were available in Amplitude-iOS
to allow you to use IDFV or IDFA as the deviceID. Although Amplitude-Swift
doesn't support these configurations, you can add plugins to the new iOS SDK to enrich event payloads.
import AdSupport
import AmplitudeSwift
import AppTrackingTransparency
import Foundation
import SwiftUI
/// Plugin to collect IDFA values. Users will be prompted if authorization status is undetermined.
/// Upon completion of user entry a track event is issued showing the choice user made.
///
/// Don't forget to add "NSUserTrackingUsageDescription" with a description to your Info.plist.
class IDFACollectionPlugin: Plugin {
let type = PluginType.enrichment
weak var amplitude: Amplitude? = nil
func execute(event: BaseEvent?) -> BaseEvent? {
let status = ATTrackingManager.trackingAuthorizationStatus
var idfa = fallbackValue
if status == .authorized {
idfa = ASIdentifierManager.shared().advertisingIdentifier.uuidString
}
let workingEvent = event
// The idfa on simulator is always 00000000-0000-0000-0000-000000000000
event?.idfa = idfa
// If you want to use idfa for the device_id
event?.deviceId = idfa
return workingEvent
}
}
extension IDFACollectionPlugin {
var fallbackValue: String? {
// fallback to the IDFV value.
// this is also sent in event.context.device.id,
// feel free to use a value that is more useful to you.
return UIDevice.current.identifierForVendor?.uuidString
}
}
...
// To install your custom plugin, use 'add()' with your custom plugin as parameter.
amplitude.add(plugin: IDFACollectionPlugin())
@import AmplitudeSwift;
#import <AppTrackingTransparency/AppTrackingTransparency.h>
#import <AdSupport/ASIdentifierManager.h>
[amplitude add:[AMPPlugin initWithType:AMPPluginTypeEnrichment execute:^AMPBaseEvent* _Nullable(AMPBaseEvent* _Nonnull event) {
ATTrackingManagerAuthorizationStatus status = ATTrackingManager.trackingAuthorizationStatus;
// fallback to the IDFV value.
// this is also sent in event.context.device.id,
// feel free to use a value that is more useful to you.
NSUUID* idfaUUID = [UIDevice currentDevice].identifierForVendor;
if (status == ATTrackingManagerAuthorizationStatusAuthorized) {
idfaUUID = [ASIdentifierManager sharedManager].advertisingIdentifier;
}
NSString* idfa = (idfaUUID != nil) ? idfaUUID.UUIDString : nil;
// The idfa on simulator is always 00000000-0000-0000-0000-000000000000
event.idfa = idfa;
// If you want to use idfa for the device_id
event.deviceId = idfa;
return event;
}]];
Callback¶
Amplitude-Swift
supports configuration-level and event-level callback functions which are called for success and error upload. Configuration-level callback applies for every success and error event upload. Event-level callback is specific for one Event. Notice that the event-level callbacks are stored in cache, those callbacks are lost if the app crashes.
Configuration-level callbacks:
let amplitude = Amplitude(
configuration: Configuration(
apiKey: "TEST-API-KEY",
callback: { (event: BaseEvent, code: Int, message: String) -> Void in
print("eventCallback: \(event), code: \(code), message: \(message)")
},
)
)
AMPConfiguration* configuration = [AMPConfiguration initWithApiKey:@"YOUR-API-KEY"];
configuration.callback = ^(AMPBaseEvent* _Nonnull event, NSInteger code, NSString* _Nonnull message) {
NSLog(@"eventCallback: %@, code: %@, message: %@", event.eventType, @(code), message);
};
Amplitude* amplitude = [Amplitude initWithConfiguration:configuration];
Event-level callbacks:
let event = BaseEvent(
callback: { (event: BaseEvent, code: Int, message: String) -> Void in
print("eventCallback: \(event), code: \(code), message: \(message)")
},
eventType: "TEST-EVENT-TYPE")
amplitude.track(event: event)
AMPBaseEvent* event = [AMPBaseEvent initWithEventType:@"TEST-EVENT-TYPE"];
event.callback = ^(AMPBaseEvent* _Nonnull event, NSInteger code, NSString* _Nonnull message) {
NSLog(@"eventCallback: %@, code: %@, message: %@", event.eventType, @(code), message);
};
[amplitude track:event];
or
let event2 = BaseEvent(eventType:"test")
amplitude.track(
event: event2,
callback: { (event: BaseEvent, code: Int, message: String) -> Void in
print("eventCallback: \(event), code: \(code), message: \(message)")
})
AMPBaseEvent* event2 = [AMPBaseEvent initWithEventType:@"test"];
[amplitude track:event2 callback:^(AMPBaseEvent* _Nonnull event, NSInteger code, NSString* _Nonnull message) {
NSLog(@"eventCallback: %@, code: %@, message: %@", event.eventType, @(code), message);
}];
Comparison¶
This section provides a comparison between different version of SDKs. This overview provides key insights for developers, identifying areas that have significant changes and need careful consideration.
Note
While there are multiple versions of our SDK available, please use the latest version of the SDKs rather than maintenance SDKs. Maintenance versions only provide support and will eventually be deprecated. The latest SDK adopts an aligned architecture, with no extra dependencies, and offers enhanced stability for optimal performance.
Feature |
Latest iOS SDK | Maintenance iOS SDK |
---|---|---|
Package | AmplitudeSwift | Amplitude |
Configuration | Configuration is implemented by the configuration object. Configurations need to be passed into Amplitude Object during initialization. More configurations. Latest iOS SDK support more configurations. Check here for more details. | Supports specific setter methods. More configurations |
Logger Provider | ConsoleLogger() by default. Fully customizable. | AMPLITUDE_LOG, config through macro. |
Storage Provider | PersistentStorage() by default. File storage and iOS user’s defaults database. Fully customizable (not supported in Objective-C). | SQLite Database. |
Customization | Plugins | Middleware |
Server Endpoint | HTTP V2 API | HTTP V1 API |
Batch API | Yes, with configuration. | Not supported. |
Data migration¶
Existing maintenance SDK data (events, user/device ID) are moved to the latest SDK by default. It can be disabled by setting migrateLegacyData
to false
in the Configuration.
amplitude = Amplitude(
Configuration(
...
migrateLegacyData: false,
)
)
AMPConfiguration* configuration = [AMPConfiguration initWithApiKey:@"YOUR-API-KEY"];
configuration.migrateLegacyData = false;
Amplitude* amplitude = [Amplitude initWithConfiguration:configuration];