iOS SDK

This is the official documentation for the Amplitude Analytics iOS SDK.

Install the SDK

Install the iOS SDK with CocoaPods, Carthage, or Swift Package Manager.

pod '@{{packageName}}', '~> @{{version}}'

Initialize the SDK

Initialize the SDK before you instrument. The API key for your Amplitude project is required.

Initialize the SDK in the application:didFinishLaunchingWithOptions: method of your YourAppAppDelegate.m file.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Enable sending automatic session events
    [Amplitude instance].defaultTracking.sessions = YES;
    // Initialize SDK
    [[Amplitude instance] initializeApiKey:@"API_KEY"];
    // Set userId
    [[Amplitude instance] setUserId:@"userId"];
    // Log an event
    [[Amplitude instance] logEvent:@"app_start"];

    return YES;
}

Configure the SDK

EU data residency

Starting with version 8.5.0, you can configure the server zone after initializing the client to send data to Amplitude's EU servers. The SDK sends data based on the server zone if you set it. The server zone configuration also supports dynamic configuration.

For earlier versions, configure the serverURL property after initializing the client.

// For versions starting from 8.5.0
// No need to call setServerUrl for sending data to Amplitude's EU servers

[[Amplitude instance] setServerZone:AMPServerZone.EU];

// For earlier versions
[[Amplitude instance] setServerUrl: @"https://api.eu.amplitude.com"];

Send events

Events represent how users interact with your application. For example, "Button Clicked" can be an action you want to note.

[[Amplitude instance] logEvent:@"Button Clicked"];

Send events with properties

Events can also contain properties, which give more context about the event. For example, "hover time" can be a relevant event property for "button click".

NSMutableDictionary *eventProperties = [NSMutableDictionary dictionary];
[eventProperties setValue:@"100ms" forKey:@"Hover Time"];
[[Amplitude instance] logEvent:@"Button Clicked" withEventProperties:eventProperties];

User properties

User properties help you understand your users at the time they performed an action in your app. For example, you can learn about their device details, their preferences, or language.

Amplitude-iOS's AMPIdentity class manages these features. Identify sets the user properties of a particular user without sending any event. The SDK supports these operations on individual user properties: set, setOnce, unset, add, append, prepend, preInsert, postInsert, and remove. Declare the operations through the Identify interface. You can chain multiple operations in a single Identify object.

Pass the AMPIdentify object to the Amplitude client to send it to the server. Starting from release v8.15.0, the SDK batches identify events with set operations and sends them with fewer events. This change doesn't affect the result of the set operations. Manage the flush interval for batched Identify events with setIdentifyUploadPeriodSeconds.

Set a user property

set sets the value of a user property. You can also chain together multiple identify calls.

AMPIdentify *identify = [[[AMPIdentify identify] set:@"gender" value:@"female"] set:@"age"
    value:[NSNumber numberWithInt:20]];
[[Amplitude instance] identify:identify];

Set a user property once

setOnce sets the value of a user property only once. The SDK ignores subsequent calls using setOnce.

AMPIdentify *identify1 = [[AMPIdentify identify] setOnce:@"sign_up_date" value:@"2015-08-24"];
[[Amplitude instance] identify:identify1];

AMPIdentify *identify2 = [[AMPIdentify identify] setOnce:@"sign_up_date" value:@"2015-09-14"];
[[Amplitude instance] identify:identify2]; // Is ignored

Increment a user property

add increments a user property by some numerical value. If the user property doesn't have a value set yet, the SDK initializes it to 0 before incrementing.

AMPIdentify *identify = [[[AMPIdentify identify] add:@"karma" value:[NSNumber numberWithFloat:0.123]]
    add:@"friends" value:[NSNumber numberWithInt:1]];
[[Amplitude instance] identify:identify];

Remove values from a user property

remove removes a value or values from a user property. If the item doesn't exist in the user property, the SDK removes nothing.

NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] remove:@"ab-tests" value:@"new-user-test"]
    remove:@"some_list" value:array];
[[Amplitude instance] identify:identify];

Set multiple user properties

Use setUserProperties as a shorthand to set multiple user properties at once. This method is a wrapper around Identify.set and identify.

NSMutableDictionary *userProperties = [NSMutableDictionary dictionary];
[userProperties setValue:@"VALUE" forKey:@"KEY"];
[userProperties setValue:@"OTHER_VALUE" forKey:@"OTHER_KEY"];
[[Amplitude instance] setUserProperties:userProperties];

Use arrays in user properties

Directly set arrays or use append to generate an array.

NSMutableArray *colors = [NSMutableArray array];
[colors addObject:@"rose"];
[colors addObject:@"gold"];
NSMutableArray *numbers = [NSMutableArray array];
[numbers addObject:[NSNumber numberWithInt:4]];
[numbers addObject:[NSNumber numberWithInt:5]];
AMPIdentify *identify = [[[[AMPIdentify identify] set:@"colors" value:colors] append:@"ab-tests"
    value:@"campaign_a"] append:@"existing_list" value:numbers];
[[Amplitude instance] identify:identify];

Append or prepend user property data

• append appends a value or values to a user property array.
• prepend prepends a value or values to a user property.

If the user property doesn't have a value set yet, the SDK initializes it to an empty list before adding the new values. If the user property has an existing value and it isn't a list, the SDK converts it into a list and adds the new value.

append and prepend don't check for duplicates. For duplicate checking, refer to preInsert and postInsert.

NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] append:@"ab-tests" value:@"new-user-test"]
    append:@"some_list" value:array];
[[Amplitude instance] identify:identify];

Preinsert and postinsert

• preInsert inserts a value or values to the front of a user property array if the value doesn't exist in the array yet.
• postInsert inserts a value or values to the end of a user property array if the value doesn't exist in the array yet.

If the user property doesn't exist, the SDK initializes it to an empty list before pre-inserting the new values. If the user property has an existing value, the SDK inserts nothing.

NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] preInsert:@"ab-tests" value:@"new-user-test"]
    preInsert:@"some_list" value:array];
[[Amplitude instance] identify:identify];

Remove user properties

clearUserProperties removes all the current user's user properties.

[[Amplitude instance] clearUserProperties];

Remove a value or values from a user property

remove removes an existing value or values from a user property. If the item doesn't exist in the user property, the SDK removes nothing.

NSMutableArray *array = [NSMutableArray array];
[array addObject:@"some_string"];
[array addObject:[NSNumber numberWithInt:56]];
AMPIdentify *identify = [[[AMPIdentify identify] remove:@"ab-tests" value:@"new-user-test"]
    remove:@"some_list" value:array];
[[Amplitude instance] identify:identify];

Track default events

Starting from release v8.17.0, the SDK can track more default events. Configure the SDK to track the following events automatically:

• Sessions.
• App lifecycles.
• Screen views.
• Deep links.
• defaultTracking.sessions
  • Type: Optional. boolean.
  • Default Value: NO.
  • Description:
    • Enables session tracking. This configuration replaces trackingSessionEvents. If the value is YES, Amplitude tracks session start and session end events.
    • Refer to Tracking sessions for more information.
• defaultTracking.appLifecycles
  • Type: Optional. boolean.
  • Default Value: NO.
  • Description:
    • Enables application lifecycle events tracking. If the value is YES, Amplitude tracks application installed, application updated, application opened, and application backgrounded events.
    • Tracked event properties include: [Amplitude] Version, [Amplitude] Build, [Amplitude] Previous Version, [Amplitude] Previous Build, and [Amplitude] From Background.
    • Refer to Tracking application lifecycles for more information.
• defaultTracking.screenViews
  • Type: Optional. boolean.
  • Default Value: NO.
  • Description:
    • Enables screen views tracking. If the value is YES, Amplitude tracks screen viewed events.
    • Tracked event properties include: [Amplitude] Screen Name.
    • Refer to Tracking screen views for more information.
• defaultTracking.deepLinks
  • Type: Optional. boolean.
  • Default Value: NO.
  • Description:
    • Enables deep link tracking. If the value is YES, Amplitude tracks deep link opened events. You still need to call continueUserActivity or openURL manually to track this event.
    • Tracked event properties include: [Amplitude] Link URL and [Amplitude] Link Referrer.
    • Refer to Tracking deep links for more information.

Use the following code sample to enable default event tracking.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithAllEnabled];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

Disable default event tracking with the following code sample.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithNoneEnabled];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

Default event tracking accepts options that define which events to track.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithSessions:YES
                                                                        appLifecycles:NO
                                                                            deepLinks:NO
                                                                        screenViews:NO];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

Track sessions

To start tracking session events, set defaultTracking.sessions to true. Refer to the following code sample.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithSessions:YES
                                                                        appLifecycles:NO
                                                                            deepLinks:NO
                                                                        screenViews:NO];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

For more information about session tracking, refer to User sessions.

Track application lifecycle

To start tracking application lifecycle events, set defaultTracking.appLifecycles to true. Refer to the following code sample.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithSessions:NO
                                                                      appLifecycles:YES
                                                                          deepLinks:NO
                                                                        screenViews:NO];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

After enabling this setting, Amplitude tracks the following events:

• [Amplitude] Application Installed: fires when a user opens the application for the first time after installation. The SDK observes the UIApplicationDidFinishLaunchingNotification notification.
• [Amplitude] Application Updated: fires when a user opens the application after updating it. The SDK observes the UIApplicationDidFinishLaunchingNotification notification.
• [Amplitude] Application Opened: fires when a user launches or foregrounds the application after the first open. The SDK observes the UIApplicationDidFinishLaunchingNotification or UIApplicationWillEnterForegroundNotification notification.
• [Amplitude] Application Backgrounded: fires when a user backgrounds the application. The SDK observes the UIApplicationDidEnterBackgroundNotification notification.

Track screen views

To start tracking screen view events, set defaultTracking.screenViews to true. Refer to the following code sample.

[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithSessions:NO
                                                                        appLifecycles:NO
                                                                            deepLinks:NO
                                                                        screenViews:YES];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

After enabling this setting, Amplitude tracks the [Amplitude] Screen Viewed event with the screen name property. The SDK reads the property value from the controller class metadata using viewDidAppear method swizzling.

Track deep links

To start tracking deep link events, set defaultTracking.deepLinks to true. Refer to the following code sample.

// Enable tracking deep links.
[Amplitude instance].defaultTracking = [AMPDefaultTrackingOptions initWithSessions:NO
                                                                        appLifecycles:NO
                                                                            deepLinks:YES
                                                                        screenViews:NO];
[[Amplitude instance] initializeApiKey:@"API_KEY"];

// Call helper method to track, e.g., in `onOpenURL` callback.
[[Amplitude instance] openURL:url];
[[Amplitude instance] continueUserActivity:activity];

After enabling this setting, Amplitude tracks the [Amplitude] Deep Link Opened event with the URL and referrer information. You still need to call continueUserActivity or openURL manually to track deep links.

Set user groups

Amplitude supports assigning users to groups and performing queries, such as Count by Distinct, on those groups. If at least one member of the group has performed the specific event, then the count includes the group.

For example, you want to group your users based on what organization they're in by using an 'orgId'. Joe is in 'orgId' '10', and Sue is in 'orgId' '15'. Sue and Joe both perform a certain event. You can query their organizations in the Event Segmentation Chart.

When setting groups, define a groupType and groupName. In the previous example, 'orgId' is the groupType, and '10' and '15' are the values for groupName. Another example of a groupType is 'sport', with groupName values like 'tennis' and 'baseball'.

Setting a group also sets the groupType:groupName as a user property. It overwrites any existing groupName value set for that user's groupType and the corresponding user property value. groupType is a string, and groupName can be either a string or an array of strings to indicate that a user is in multiple groups.

[[Amplitude instance] setGroup:@"orgId" groupName:[NSNumber numberWithInt:15]];
[[Amplitude instance] setGroup:@"sport" groupName:[NSArray arrayWithObjects: @"tennis", @"soccer", nil]];

You can also use logEventWithGroups to set event-level groups. The group designation only applies for the specific event you log, and doesn't persist on the user unless you explicitly set it with setGroup:

NSDictionary *eventProperties = [NSDictionary dictionaryWithObjectsAndKeys: @"value", @"key", nil];
NSDictionary *groups = [NSDictionary dictionaryWithObjectsAndKeys:[NSNumber numberWithInt:10],
    @"orgId", @"soccer", @"sport", nil];
[[Amplitude instance] logEvent:@"initialize_game" withEventProperties:eventProperties withGroups:groups];

Group identify

Use the Group Identify API to set or update the properties of particular groups. These updates only affect events going forward.

The groupIdentifyWithGroupType method accepts a group type string parameter, a group name object parameter, and an Identify object that applies to the group.

NSString *groupType = @"plan";
NSObject *groupName = @"enterprise";
AMPIdentify *identify = [[AMPIdentify identify] set:@"key" value:@"value"];
[[Amplitude instance] groupIdentifyWithGroupType:groupType groupName:groupName groupIdentify:identify];

You can add an optional outOfSession boolean input as a fourth argument to groupIdentifyWithGroupType.

Track revenue

Instances of AMPRevenue store revenue transactions and define special revenue properties (such as revenueType) used in Amplitude's Event Segmentation and Revenue LTV charts. Pass each instance to Amplitude.logRevenueV2. This lets Amplitude automatically display data relevant to revenue.

To track revenue from a user, call logRevenueV2 each time a user generates revenue. Here is an example:

AMPRevenue *revenue = [[[AMPRevenue revenue] setProductIdentifier:@"productIdentifier"] setQuantity:3];
[revenue setPrice:[NSNumber numberWithDouble:3.99]];
[[Amplitude instance] logRevenueV2:revenue];

Calling logRevenueV2 generates up to 2 different event types in the platform:

• [Amplitude] Revenue: Amplitude logs this event for all revenue events, regardless of whether verification is on.
• [Amplitude] Revenue (Verified/Unverified): These revenue events contain the actual $revenue property.

You can't change the default names that Amplitude gives these client-side revenue events in the raw data, but you can change the display name. Learn more about tracking revenue in the Help Center.

Each revenue event has fields available, and each field has a corresponding set method (such as price and setPrice). Refer to the API docs for AMPRevenue for a full list of fields.

Like logEvent, you can attach event properties for each call to logRevenueV2. However, these event properties only appear in the Event Segmentation chart, not in the Revenue charts.

Advanced topics

User sessions

A session is a period of time that a user has the app in the foreground. Events logged within the same session share the same session_id. The SDK handles sessions automatically, so you don't have to manually call an API like startSession() or endSession().

To adjust the time window for which sessions extend, change the variable minTimeBetweenSessionsMillis.

Amplitude groups events together by session. A session represents a single period of user activity with a start and end time. Different SDKs track sessions differently, depending on the requirements of the platform. Configure the minimum duration of a session within the SDK.

[Amplitude instance].defaultTracking.sessions = YES;
[Amplitude instance].minTimeBetweenSessionsMillis = 10 * 60 * 1000; // 10 minutes
[[Amplitude instance] initializeApiKey:@"API_KEY"];

You can also log events as out-of-session. Out-of-session events have a session_id of -1 and don't count as part of the current session, meaning they don't extend the current session. This can be useful when you log events triggered by push notifications, for example. Log events as out-of-session by setting the input parameter outOfSession to true when calling logEvent.

[[Amplitude instance] logEvent:@"EVENT_TYPE" withEventProperties:nil outOfSession:YES];

You can also log identify events as out-of-session. This is useful when you update user properties in the background and don't want to start a new session. Set the input parameter outOfSession to true when calling identify.

AMPIdentify *identify = [[AMPIdentify identify] set:@"key" value:@"value"];
[[Amplitude instance] identify:identify outOfSession:YES];

You can use the helper method getSessionId to get the value of the current sessionId.

long sessionId = [[Amplitude instance] getSessionId];

Set a custom user ID

If your app has its own login system that you want to track users with, call setUserId at any time.

[[Amplitude] instance] setUserId:@"USER_ID"];

You can also add the User ID as an argument to the init call.

[[Amplitude] instance] initializeApiKey:@"API_KEY" userId:@"USER_ID"];

Don't assign users a user ID that could change, because each unique user ID is a unique user in Amplitude. For more information, refer to Track unique users.

Debug logging

By default, the SDK logs only critical errors to the console. To enable debug logging in iOS, change AMPLITUDE_DEBUG from 0 to 1 at the top of the Objective-C file you want to examine. The SDK prints error messages by default. To disable error logging, change AMPLITUDE_LOG_ERRORS from 1 to 0 in Amplitude.m.

Logged out and anonymous users

Amplitude merges user data, so any events associated with a known userId or deviceId link to the existing user.

If a user logs out, Amplitude can merge that user's logged-out events to the user's record. You can change this behavior and log those events to an anonymous user instead.

To log events to an anonymous user:

1. Set the userId to null.
2. Generate a new deviceId.

Events coming from the current user or device appear as a new user in Amplitude. Note: if you do this, you can't see that the two users were using the same device.

[[Amplitude instance] setUserId:nil]; // not string nil
[[Amplitude instance] regenerateDeviceId];

Disable tracking

By default, the iOS SDK tracks several user properties such as carrier, city, country, ip_address, language, and platform. Use the AMPTrackingOptions interface to customize and disable individual fields.

Each operation on the AMPTrackingOptions object returns the same instance, letting you chain multiple operations together.

To use the AMPTrackingOptions interface, first include the header:

#import "AMPTrackingOptions.h"

Before initializing the SDK with your apiKey, create an AMPTrackingOptions instance with your configuration and set it on the SDK instance.

AMPTrackingOptions *options = [[[[AMPTrackingOptions options] disableCity] disableIPAddress] disablePlatform];
[[Amplitude instance] setTrackingOptions:options];

You can individually control tracking for each field, and each field has a corresponding method (for example, disableCountry, disableLanguage).

Carrier

Amplitude determines the user's mobile carrier using CTTelephonyNetworkInfo, which returns the registered operator of the sim.

COPPA control

You can enable or disable COPPA (Children's Online Privacy Protection Act) restrictions on IDFA, IDFV, city, IP address, and location tracking all at once. Apps that ask for information from children under 13 years of age must comply with COPPA.

[[Amplitude instance] enableCoppaControl];

Advertiser ID

Advertiser ID (also called IDFA) is a unique identifier that the iOS and Google Play stores provide. Because IDFA is unique to every person and not just their devices, IDFA is useful for mobile attribution.

Mobile attribution is the attribution of an installation of a mobile app to its original source (such as ad campaign, app store search).

Mobile apps need permission to ask for IDFA, and apps targeted at children can't track at all. Consider using IDFV, device ID, or an email login system when IDFA isn't available.

amplitude.adSupportBlock = ^{
    return [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
};

Remember to add AdSupport.framework to your project.

Set IDFA as device ID

Amplitude uses the IDFV as the device ID by default, but you can change this behavior. After you set up the logic to fetch IDFA, call the useAdvertisingIdForDeviceId API to set the IDFA as your deviceId.

Device ID lifecycle

The SDK initializes the device ID in the following order. The SDK sets the device ID to the first valid value it encounters:

1. Device id fetched from the SQLite database.
2. IDFA if useAdvertisingIdForDeviceId is true and you didn't call disableIDFA().
3. IDFV if you didn't call disableIDFV().
4. A randomly generated UUID.

One user with multiple devices

A single user may have multiple devices, each having a different device ID. To ensure coherence, set the user ID consistently across all these devices. Even though the device IDs differ, Amplitude can still merge them into a single Amplitude ID, thus identifying them as a unique user.

Transfer to a new device

Multiple devices can have the same device ID when a user switches to a new device. When transitioning to a new device, users often transfer their applications along with other relevant data. The specific transferred content can vary depending on the application. It generally includes databases and file directories associated with the app. The exact items included depend on the app's design and the developers' choices. If databases or file directories were backed up from one device to another, the device ID stored within them can still be present. As a result, when the SDK retrieves the device ID during initialization, different devices might end up using the same device ID.

Get device ID

You can use the helper method getDeviceId() to get the value of the current deviceId.

NSString *deviceId = [[Amplitude instance] getDeviceId];

Custom device ID

You can assign a new device ID using setDeviceId(). When setting a custom device ID, make sure the value is sufficiently unique. Amplitude recommends using a UUID.

[[Amplitude instance] setDeviceId:@"DEVICE_ID"];

Location tracking

Amplitude converts the IP of a user event into a location (GeoIP lookup) by default. An app's own tracking solution or user data can override this information.

Carrier information

Amplitude-iOS can help report carrier information.

To enable the SDK to report this information from devices, add CoreTelephony.framework as a dependency.

Dynamic configuration

The iOS SDK lets you configure your apps to use dynamic configuration. This feature finds the best server URL automatically based on app users' location.

To use it, enable the useDynamicConfig flag.

• If you have your own proxy server and use apiEndPoint API, leave dynamic configuration off.
• If you have users in China Mainland, Amplitude recommends using dynamic configuration.
• By default, this feature returns the server URL of Amplitude's US servers. If you need to send data to Amplitude's EU servers, use setServerZone to set it to the EU zone.

[Amplitude instance].useDynamicConfig = YES;

SSL pinning

SSL Pinning is a client-side technique that helps prevent man-in-the-middle attacks by validating server certificates again after SSL handshaking. Only use SSL pinning if you have a specific reason to do so. Contact Support before you ship any products with SSL pinning enabled.

If you installed the SDK using CocoaPods, enable the preprocessor macro through your Podfile by adding this post install hook:

post_install do |installer_representation|
   installer_representation.pods_project.targets.each do |target|
      target.build_configurations.each do |config|
         config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)', 'AMPLITUDE_SSL_PINNING=1']
      end
   end
end

If you installed the SDK directly from the source or Swift Package Manager, enable SSL pinning by adding the following preprocessor macro. Refer to this StackOverflow post to learn how to add a preprocessor macro.

AMPLITUDE_SSL_PINNING=1

Opt users out of tracking

Users can opt out of tracking entirely, which means Amplitude doesn't track any of their events or browsing history. setOptOut provides a way to fulfill a user's requests for privacy.

[[Amplitude instance] setOptOut:YES]; // disables instrumentation
[[Amplitude instance] setOptOut:NO]; // enables instrumentation

tvOS and watchOS

This SDK works with tvOS and watchOS apps. To begin, follow the same setup instructions for iOS apps.

[[Amplitude instance] setEventUploadThreshold:30];

iOS extensions

The SDK allows for tracking in iOS extensions. To set up tracking in iOS extensions, follow the same setup instructions but initialize the SDK in your extension's viewDidLoad method instead of application:didFinishLaunchingWithOptions:.

A few things to highlight:

• The system calls the viewDidLoad method every time your extension opens. This means the SDK's initializeApiKey method runs every time. This is safe because the SDK ignores calls after the first one. You can protect the initialization with something like a dispatch_once block.
• Amplitude's sessions are defined for an app use case. Depending on your expected extension use case, you might not want to enable defaultTracking.sessions, or you might want to extend minTimeBetweenSessionsMillis to be longer than five minutes. Experiment with these two settings to get the session definition you want.
• If you don't expect users to keep your extension open long, decrease eventUploadPeriodSeconds to something shorter than 30 seconds to upload events at shorter intervals. You can also manually call [[Amplitude instance] uploadEvents]; to force an upload.

App Clips

The SDK also allows for tracking in App Clips. To set up tracking in App Clips, install Amplitude-iOS under your App Clip target. Make sure the amplitude-iOS SDK is installed on your main app first.

CocoaPods

After creating an App Clip target, open your project Podfile and append the following code.

target 'appClipTarget' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'Amplitude', :git => 'https://github.com/Amplitude/Amplitude-iOS.git'
end

Save the Podfile and run pod install.

Swift Package Manager

1. Open your App Clip target in Xcode and select the + button under the Framework, Libraries, and Embedded Content section.
2. Select Amplitude under Amplitude Package and select Add.

Push notification events

Don't send push notification events client-side through the iOS SDK. Because a user must open the app to initialize the Amplitude SDK before the SDK can send the event, the SDK doesn't send events to the Amplitude servers until the next time the user opens the app. This can cause data delays.

You can use mobile marketing automation partners or the HTTP API V2 to send push notification events to Amplitude.

Offline mode

The Amplitude SDK supports offline usage through the setOffline(isOffline) method. Offline mode is off by default.

When offline mode is on, the SDK saves events to local storage but doesn't send them to the Amplitude servers.

When offline mode is off, the SDK sends any pending events to Amplitude's servers immediately.

To limit the permissions required by the SDK, the SDK doesn't automatically detect network connectivity. Instead, manually call setOffline() to enable or disable offline mode.

[[Amplitude instance] setOffline:YES]; // enables offline mode
[[Amplitude instance] setOffline:NO]; // disables offline mode

Middleware

Middleware lets you extend Amplitude by running a sequence of custom code on every event. This pattern is flexible and supports event enrichment, transformation, filtering, routing to third-party destinations, and more.

Each middleware is a simple interface with a run method:

- (void)run:(AMPMiddlewarePayload *_Nonnull)payload next:(AMPMiddlewareNext _Nonnull)next;

The payload contains the event the SDK sends and an optional extra that lets you pass custom data to your own middleware implementations.

To invoke the next middleware in the queue, use the next function. Call next(payload) to continue the middleware chain. If a middleware doesn't call next, event processing stops after the current middleware completes.

Add middleware to Amplitude through client.addEventMiddleware. You can add as many middleware as you like. Each middleware runs in the order you added it.

You can find examples for Objective-C and Swift.

Security

iOS automatically protects application data by storing each app's data in its own secure directory. Other applications generally can't access this directory. However, if a device is jailbroken, apps gain root access to all directories on the device.

To prevent other apps from accessing your app's Amplitude data on a jailbroken device, Amplitude recommends setting a unique instance name for your SDK. This creates a unique database that is isolated from other apps.

Amplitude* amplitude = [Amplitude instanceWithName:@"my-unique-instance-name"];

Apple privacy manifest

Starting December 8, 2020, Apple requires a privacy manifest file for all new apps and app updates. Apple expects to make this mandatory in Spring 2024. Because Amplitude is a third-party to your app, properly disclose to your users how you use Amplitude with their data.

NSPrivacyTracking

By default, Amplitude doesn't use data for tracking. Add this field and set it to true if your app does.

NSPrivacyCollectedDataTypes

By default, the SDK tracks deviceId only. Use setUserId() to track userId as well. To do so, add the "User ID" Data type. For more information about data types, refer to Apple's article Describing data use in privacy manifests.

NSPrivacyTrackingDomains

If you set NSPrivacyTracking to true, provide at least one internet domain in NSPrivacyTrackingDomains based on your configuration.

NSPrivacyAccessedAPITypes

The SDK doesn't use any API by default. Learn more here.

Create your app's privacy report

Follow the steps on how to create your app's privacy.