iOS SDK Reference

Updated

Important Note:
This article has been moved to our Developer Center, and will no longer be updated on this site. Here is the newest version of our iOS SDK Reference.

 This article describes all the available SDK methods for Amplitude's iOS SDK. The variables and values in red are what you will need to replace with your own. Please see the iOS SDK Installation documentation for instructions on how to install the SDK.

For additional information regarding the Amplitude iOS SDK, please feel free to check out our Developers Centre here.

Table of Contents

  

Class: AMPIdentify

Inherits from: NSObject

Declared in: AMPIdentify.h and AMPIdentify.m

 

Overview

AMPIdentify objects are a wrapper for user property operations, which are passed to the identify method and sent to Amplitude's servers. Note: If a user property is used in multiple operations on the same Identify object, only the first operation will be saved and the rest will be ignored. Each method adds a user property operation to the Identify object and returns the same Identify object, allowing you to chain multiple method calls together.

Here is an example of how to use AMPIdentify to send user property operations:

AMPIdentify *identify = [[AMPIdentify identify] add:@"karma" value:[NSNumber numberWithInt:1]];
[[identify set:@"colors" value:@[@"rose", @"gold"]] append:@"ab-tests" value:@"campaign_a"];
[[Amplitude instance] identify:identify];

See the iOS SDK Installation documentation for more information about user properties and user property operations. 

 

Creating an AMPIdentify Object

To create a new AMPIdentify object:

+ (instancetype) identify;

Return value: A new AMPIdentify object.

Declared in: AMPIdentify.h 

 

User Property Operations

See the iOS SDK Installation documentation for more information about user properties and user property operations. 

 

1. - (AMPIdentify *) add:(NSString *) property value:(NSObject *) value;

Increment a user property by a given value (can also be negative to decrement). If the user property does not have a value set yet, it will be initialized to zero before being incremented. 

Parameters:

property

 The user property key.

value

The amount by which to increment the user property.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

 

2. - (AMPIdentify *) append:(NSString *) property value:(NSObject *) value;

Append a value or values to a user property. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are appended. If the user property has an existing value and it is not a list, the existing value will be converted into a list with the new values appended.

Parameters:

property

 The user property key.

value

The value or values to append.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

 

3. - (AMPIdentify *) prepend:(NSString *) property value:(NSObject *) value;

Prepend a value or values to a user property. Prepend means inserting the value or values at the front of a list. If the user property does not have a value set yet, it will be initialized to an empty list before the new values are prepended. If the user property has an existing value and it is not a list, the existing value will be converted into a list with the new values prepended.

Parameters:

property

 The user property key.

value

The value or values to prepend.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

 

4. - (AMPIdentify *) set:(NSString *) property value:(NSObject*) value;

Sets the value of a given user property. If the value already exists, it will be overwritten with the new value.

Parameters:

property

 The user property key.

value

The value or values to set.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

 

5. - (AMPIdentify *) setOnce:(NSString *) property value:(NSObject *) value;

Sets the value of a given user property only once. Subsequent setOnce operations on that user property will be ignored. However, that user property can still be modified through any of the other operations. This is useful for capturing properties such as 'initial_signup_date' and 'initial_referrer'.

Parameters:

property

 The user property key.

value

The value or values to set once.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

 

6. - (AMPIdentify *) unset:(NSString *) property;

Unset and remove a user property. This user property will no longer show up in that user's profile.

Parameters:

property

 The user property key to unset.

Return value: The same AMPIdentify object, allowing you to chain multiple method calls together.

Declared in: AMPIdentify.h

Back to top

 

Class: AMPRevenue

Inherits from: NSObject

Declared in: AMPIdentify.h and AMPIdentify.m

 

Overview

AMPRevenue objects are a wrapper for revenue data, which gets passed to the logRevenueV2 method to send to Amplitude's servers. Note: The revenue amount for each revenue event is calculated as price * quantity. Each method updates a revenue property in the Revenue object and returns the same Revenue object, allowing you to chain multiple method calls together. 

Here is an example of how to use AMPRevenue to send revenue data:

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

See the iOS SDK installation documentation for more information about logging Revenue. 

 

Required Revenue Fields

1. @property (nonatomic, strong, readonly) NSNumber *price;

The price of the product(s) in the transaction.

Declared in: AMPRevenue.h

 

2. @property (nonatomic, readonly) NSInteger quantity;

The price of the product(s) in the transaction. This defaults to 1.

Declared in: AMPRevenue.h

 

3. @property (nonatomic, strong, readonly) NSData *receipt; (required for revenue verification)

The receipt data for the transaction. This is required if you want to verify the revenue event. See the iOS SDK installation documentation for more information about revenue verification.

Declared in: AMPRevenue.h

 

Optional Revenue Fields

1. @property (nonatomic, strong, readonly) NSString *productId;

The product identifier for the transaction.

Declared in: AMPRevenue.h

 

2. @property(nonatomic, strong, readonly) NSString *revenueType;

The revenue type for the transaction.

Declared in: AMPRevenue.h

 

3. @property (nonatomic, strong, readonly) NSDictionary *properties;

Event properties for the revenue event. See the iOS SDK installation documentation for more information about setting event properties.

Declared in: AMPRevenue.h

 

Creating an AMPRevenue Object

To create a new AMPRevenue object:

+ (instancetype)revenue

Return value: A new AMPRevenue object.

Declared in: AMPRevenue.h

 

Set Methods for Revenue Fields

1. - (AMPRevenue *) setProductIdentifier:(NSString *) productIdentifier;

Sets a value for the product identifier.

Parameters:

productIdentifier

 The value for the product identifier. Empty strings will be ignored.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together.

Declared in: AMPRevenue.h

 

2. - (AMPRevenue *) setQuantity:(NSInteger) quantity;

Sets a value for the quantity. Note: Revenue is calculated as price * quantity.

Parameters:

quantity

 The integer value to set for the quantity. This defaults to 1 if not specified.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together. 

Declared in: AMPRevenue.h

 

3. - (AMPRevenue *) setPrice:(NSNumber *) price;

Sets a value for the price. Note: Revenue is calculated as price * quantity.

Parameters:

price

 The value to set for the price.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together. 

Declared in: AMPRevenue.h

 

4. - (AMPRevenue *) setRevenueType:(NSString *) revenueType;

Sets a value for the revenue type (e.g. purchase, cost, tax, refund, etc.).

Parameters:

revenueType

 The string value to set for the revenue type.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together. 

Declared in: AMPRevenue.h

 

5. - (AMPRevenue *) setReceipt:(NSData *) receipt;

Add the receipt data for the transaction. This is required if you want to verify the revenue event. See the iOS SDK installation documentation for more information on verifying revenue events. See here for information on how to verify receipts from the app store.

Parameters:

receipt

 The receipt data from the app store.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together.

Declared in: AMPRevenue.h

 

5. - (AMPRevenue *) setEventProperties:(NSDictionary *) eventProperties;

Set event properties for the revenue event. See the iOS SDK installation for more information on how to set event properties.

Parameters:

eventProperties

 An NSDictionary of event properties to set for the revene event.

Return value: This returns the same AMPRevenue object, allowing you to chain multiple method calls together.

Declared in: AMPRevenue.h

Back to top

 

Class: Amplitude

Inherits from: NSObject

Declared in: AMPIdentify.h and AMPIdentify.m

 

Overview

Amplitude iOS SDK. Use the Amplitude SDK to track events in your application. For details on how to install the SDK, please read the iOS SDK Installation documentation. 

 

Instance Properties

1. @property (nonatomic, strong, readonly) NSString *apiKey;

API key for your Amplitude project.

Declared in: Amplitude.h

 

2. @property (nonatomic, strong, readonly) NSString *userId;

Identifier for the current user.

Declared in: Amplitude.h

 

3. @property (nonatomic, strong, readonly) NSString *deviceId;

Identifier for the current device.

Declared in: Amplitude.h

 

4. @property (nonatomic, strong, readonly) NSString *deviceId;

Name of the SDK instance (e.g. no name for the default instance or a custom name for a named instance).

Declared in: Amplitude.h

 

5. @property (nonatomic, assign) BOOL optOut;

Whether or not to opt the current user out of tracking. If true, then this blocks the logging of any events and properties and blocks the sending of events to Amplitude servers.

Declared in: Amplitude.h

 

Configurable SDK Thresholds and Parameters

1. @property (nonatomic, assign) int eventUploadThreshold;

The maximum number of events that can be stored locally before forcing an upload. The default is 30 events.

Declared in: Amplitude.h

 

2. @property (nonatomic, assign) int eventUploadMaxBatchSize;

The maximum number of events that can be uploaded in a single request. The default is 100 events.

Declared in: Amplitude.h

 

3. @property (nonatomic, assign) int eventMaxCount;

The maximum number of events that can be stored locally. The default is 1000 events.

Declared in: Amplitude.h

 

4. @property (nonatomic, assign) int eventUploadPeriodSeconds;

The amount of time after an event is logged where events will be batched before being uploaded to the server. The default is 30 seconds.

Declared in: Amplitude.h

 

5. @property (nonatomic, assign) long minTimeBetweenSessionsMillis;

When a user closes and reopens the app within the milliseconds specified by this parameter, the reopen is considered part of the same session and the session continues. Otherwise, a new session is created. The default is 5 minutes.

Declared in: Amplitude.h

 

6. @property (nonatomic, assign) BOOL trackingSessionEvents;

Whether or not to automatically log start and end session events that correspond to the start and end of a user's session.

Declared in: Amplitude.h

 

Fetching the Amplitude SDK Instance

This fetches the default SDK instance and is recommended if you are only logging events to a single project in Amplitude.  

+ (Amplitude *) instance;

Return value: The default Amplitude SDK instance. 

Declared in: Amplitude.h

 

This fetches a named SDK instance. Use this if you are logging events to multiple Amplitude projects. See the iOS SDK Installation documentation for more information. 

+ (Amplitude *) instanceWithName:(NSString *) instanceName;

Parameters:

instanceName

 The name of the SDK instance to fetch. 

Return value: The Amplitude SDK instance corresponding to the instance name. 

Declared in: Amplitude.h

 

Initialize the Amplitude SDK

Initializes the Amplitude instance with your API Key. We recommend you first initialize your class within your didFinishLaunchingWithOptions method inside your app delegate. Note: This is required before you can log any events.

 - (void) initializeApiKey:(NSString *) apiKey;

Parameters:

apiKey

 Your Amplitude API Key, which can be found in your project's Settings page. 

Declared in: Amplitude.h

 

Initializes the Amplitude instance with your API Key and sets a user identifier for the current user. We recommend you first initialize your class within your didFinishLaunchingWithOptions method inside your app delegate. Note: This is required before you can log any events.

- (void) initializeApiKey:(NSString *) apiKey userId:(NSString *) userId;

Parameters:

apiKey

 Your Amplitude API Key, which can be found in your project's Settings page. 

userId

 If your app has its own login system that you want to track users with, then you can set the userId. 

Declared in: Amplitude.h

 

Tracking Events

1. - (void) logEvent:(NSString *) eventType;

Tracks an event. Events are saved locally. Uploads are batched to occur every 30 events or every 30 seconds (which ever comes first) as well as on app close. See the iOS SDK Installation documentation for more information.

Parameters:

eventType

 The name of the event you wish to track.

Declared in: Amplitude.h

 

2. - (void logEvent:(NSString *) eventType withEventProperties:(NSDictionary *) eventProperties;

Tracks an event. Events are saved locally. Uploads are batched to occur every 30 events or every 30 seconds (which ever comes first) as well as on app close. See the iOS SDK Installation documentation for more information.

Parameters:

eventType

 The name of the event you wish to track.

eventProperties

 You can attach additional data to any event by passing a NSDictionary object with property:value pairs.

Declared in: Amplitude.h

 

3. - (void) logEvent:(NSString *) eventType withEventProperties:(NSDictionary *) eventProperties outOfSession:(BOOL) outOfSession;

Tracks an event. Events are saved locally. Uploads are batched to occur every 30 events or every 30 seconds (which ever comes first) as well as on app close. See the iOS SDK Installation documentation for more information about sessions.

Parameters:

eventType

 The name of the event you wish to track.

eventProperties

 You can attach additional data to any event by passing a NSDictionary object with property:value pairs.

outOfSession

 If YES, then the SDK will track the event as out-of-session. This is useful for events like push notifications.

Declared in: Amplitude.h

 

 

4. - (void) logEvent:(NSString *) eventType withEventProperties:(NSDictionary *) eventProperties withGroups:(NSDictionary *) groups withLongLongTimestamp:(long long) timestamp outOfSession:(BOOL) outOfSession;

Tracks an event. Events are saved locally. Uploads are batched to occur every 30 events or every 30 seconds (which ever comes first) as well as on app close. See the iOS SDK Installation documentation for more information.

Parameters:

eventType

 The name of the event you wish to track.

eventProperties

 You can attach additional data to any event by passing a NSDictionary object with property:value pairs.

groups

 You can specify event-level groups for this user by passing a NSDictionary object with groupType:groupName pairs. Note: The keys need to be strings, and the values can either be strings or an array of strings.

outOfSession

 If YES, then the SDK will track the event as out-of-session. This is useful for events like push notifications.

longLongtimestamp

 You can specify a custom timestamp by passing the milliseconds since epoch in UTC time as a long long.

Declared in: Amplitude.h

 

5. - (void) logEvent:(NSString *) eventType withEventProperties:(NSDictionary *) eventProperties withGroups:(NSDictionary *) groups withTimestamp:(NSNumber *) timestamp outOfSession:(BOOL) outOfSession;

Tracks an event. Events are saved locally. Uploads are batched to occur every 30 events or every 30 seconds (which ever comes first) as well as on app close. See the iOS SDK Installation documentation for more information.

Parameters:

eventType

 The name of the event you wish to track.

eventProperties

 You can attach additional data to any event by passing a NSDictionary object with property:value pairs.

groups

 You can specify event-level groups for this user by passing a NSDictionary object with groupType:groupName pairs. Note: The keys need to be strings, and the values can either be strings or an array of strings.

outOfSession

 If YES, then the SDK will track the event as out-of-session. This is useful for events like push notifications.

timestamp

 You can specify a custom timestamp by passing an NSNumber representing the milliseconds since epoch in UTC time. We recommend using [NS Number numberWithLongLong:milliseconds] to create the value. If nil is passed in, then the event will be timestamped with the current time. 

Declared in: Amplitude.h

 

Tracking Revenue 

1. -(void) logRevenueV2:(AMPRevenue *) revenue;

Tracks revenue - API v2. This uses the AMPRevenue object to store transaction properties such as quantity, price, and revenue type. This is the recommend method for tracking revenue in Amplitude. See the iOS SDK Installation documentation for more information.

For validating revenue, make sure the receipt data is set on the AMPRevenue object. To track revenue from a user, create an AMPRevenue object each time the user generates revenue, and set the revenue properties ('productIdentifier', 'price', and 'quantity'). logRevenueV2 takes in an AMPRevenue object. This allows us to automatically display data relevant to revenue on the Amplitude platform.

Parameters:

AMPRevenue

 The revenue object that contains all the revenue information.

Declared in: Amplitude.h

 

Setting User Properties

1. - (void) identify:(AMPIdentify *) identify;

Update user properties using operations provided via the Identify API. To update user properties, first create an AMPIdentify object. See the iOS SDK Installation documentation for more information on user properties. For example, if you wanted to set a user's gender and then increment their karma count by 1, you would do: 

AMPIdentify *identify = [[[AMPIdentify identify] set:@"gender" value:@"male"] add:@"karma" value:[NSNumber numberWithInt:1]];

Then, you would pass this AMPIdentify object to the identify function to send to the server:

[[Amplitude instance] identify:identify];

Parameters:

identify

 An AMPIdentify object with the intended user property operations. 

Declared in: Amplitude.h

 

2. - (void) identify:(AMPIdentify *) identify outOfSession:(BOOL) outOfSession;

Update user properties using operations provided via the Identify API. If outOfSession is YES then the identify event is logged with a session ID of -1 and does not trigger any session-handling logic. To update user properties, first create an AMPIdentify object. See the iOS SDK Installation documentation for more information on user properties. For example, if you wanted to set a user's gender and then increment their karma count by 1, you would do: 

AMPIdentify *identify = [[[AMPIdentify identify] set:@“gender” value:@“male”] add:@“karma” value:[NSNumber numberWithInt:1]];

Then, you would pass this AMPIdentify object to the identify function to send to the server:

[[Amplitude instance] identify:identify outOfSession:YES];

Parameters:

identify

 An AMPIdentify object with the intended user property operations. 

outOfSession

 Whether or not to log an identify event out-of-session.

Declared in: Amplitude.h

 

3. - (void) setUserProperties:(NSDictionary *) userProperties;

Adds properties that are tracked on the user level. See the iOS SDK Installation documentation for more information on setting multiple user properties. Note: Property keys must be NSString objects and values must be serializable.

Parameters:

userProperties

 An NSDictionary containing any additional data to be tracked.

Declared in: Amplitude.h

 

4. - (void) clearUserProperties;

Clears all user properties that are tracked for a user. See the iOS SDK Installation documentation for more information on clearing user properties. Note: The result is irreversible!

Declared in: Amplitude.h

 

5. - (void) setGroup:(NSString *) groupType groupName:(NSObject *) groupName;

Adds a user to a group or groups. You will need to specify a groupType and groupName(s). For example, you can group people by their organization. In that case, the groupType would be 'orgId' and the groupName would be the actual IDs. groupName can be a string or an array of strings to indicate a user in multiple groups. You can also call setGroup multiple times with different groupTypes to track multiple types of groups (up to 5 per app). Note: This will also set 'groupType:groupName' as a user property. See the iOS SDK Installation documentation for more information on setting groups.

Parameters:

groupType

 Specify a group type (e.g. 'orgId'). 

groupName

 The value for the group name. This can be a string or an array of strings (e.g. for the groupType 'orgId', the groupName would be an actual ID number like '15'). 

Declared in: Amplitude.h

 

Setting User and Device Identifiers

Sets the userId. See the iOS SDK Installation documentation for more information on setting custom User IDs.

- (void) setUserId:(NSString *) userId;

Parameters:

userId

 If your app has its own login system that you want to track users with, you can set the userId. 

Declared in: Amplitude.h

 

Sets the deviceId. Note: This is not recommended unless you know what you are doing. See the iOS SDK Installation documentation for more information on setting custom Device IDs.

- (void) setDeviceId:(NSString *) deviceId;

Parameters:

deviceId

 If your app has its own system for tracking devices, you can set the deviceId. 

Declared in: Amplitude.h

 

Configuring the SDK Instance

1. - (void) setOptOut:(BOOL) enabled;

Enables tracking opt out. If a user wants to opt out of all tracking, use this method to enable opt out for them. Once opt out is enabled, no events will be saved locally or sent to the server. Calling this method again with enabled set to NO will turn tracking back on for the user.

Parameters:

enabled

 Whether or not opt out should be enabled or disabled. 

Declared in: Amplitude.h

 

2. - (void) setOffline:(BOOL) offline;

Disables sending logged events to Amplitude's servers. If you want to stop logged events from being sent to Amplitude's servers, use this method to set the client to offline. Once offline is enabled, logged events will not be sent to our servers until offline is disabled. Calling this method again with offline set to NO will allow events to be sent to server and the client will attempt to send events that have been queued while offline.

Parameters:

offline

 Whether or not logged events should be sent to Amplitude's servers.

Declared in: Amplitude.h

 

3. - (void) enableLocationListening;

Enables location tracking. If a user has granted your app location permissions, the SDK will also grab the location of the user. Amplitude will never prompt the user for location permission, so this must be done by your app. Note: The user's location is only fetched once per session. Use updateLocation to force the SDK to fetch the user's latest location.

Declared in: Amplitude.h

 

4. - (void) disableLocationListening;

Disables location tracking. If you want location tracking disabled on startup of the app, call disableLocationListening before you call initializeApiKey. 

Declared in: Amplitude.h

 

5. - (void) updateLocation;

Forces the SDK to update with the user's last known location if possible. If you want to manually force the SDK to update with the user's last known location, call updateLocation.

Declared in: Amplitude.h

 

6. - (void) useAdvertisingIdForDeviceId;

Uses advertisingIdentifier instead of identifierForVendor as the Device ID. Apple prohibits the use of advertisingIdentifier if your app does not have advertising. This is useful for tying together data from advertising campaigns to analytics data. Note: This must be called before initializeApiKey is called.

Declared in: Amplitude.h

 

Other Methods

1. - (void) printEventsCount;

Prints the number of events in the queue. This is a debugging method that can be used to find out how many events are being stored locally on the device.

Declared in: Amplitude.h

 

2. - (NSString *) getDeviceId;

Fetches the deviceId, an unique identifier shared between multiple users using the same app on the same device.

Return value: Returns the deviceId. 

Declared in: Amplitude.h

 

3. - (void) regenerateDeviceId;

Regenerates a new random deviceId for the current user. Note: This is not recommended unless you know what you are doing. This can be used in conjunction with setUserId:nil to anonymize users after they log out. With a nil userId and a completely new deviceId, the current user would appear as a brand new user in the dashboard. See the iOS SDK Installation documentation for more information on how to log out users.

Declared in: Amplitude.h

 

4. - (long long) getSessionId;

Fetches the current sessionId, an identifier used by Amplitude to group together events tracked during the same session. See the iOS SDK Installation documentation for more information on sessions.

Return value: Returns the current Session ID. 

Declared in: Amplitude.h

 

5. - (void) uploadEvents;

Manually forces the instance to immediately upload all unsent events. Events are saved locally. Uploads are batched to occur every 30 events and every 30 seconds, as well as on app close. Use this method to force the class to immediately upload all queued events.

Declared in: Amplitude.h

 

6. - (void) initializeApiKey:(NSString *) apiKey userId:(NSString *) userId setUserId:(BOOL) setUserId

Use this to explicitly initialize the client with a userId (can be nil). If setUserId is NO, then the SDK will attempt to load userId from the saved eventsData.

Declared in: Amplitude.m

 

7. - (BOOL) runOnBackgroundQueue:(void (^)(void)) block

Run a block in the background. If already in the background, then run immediately.

Declared in: Amplitude.m

 

8. - (BOOL) startOrContinueSession:(NSNumber *) timestamp

Creates a new session if the app is in the background and the current session is expired or if there is no current Session ID. Otherwise, extends the session.

Return value: YES if a new session was created. 

Declared in: Amplitude.m

 

9. - (void) setSessionId:(long long) timestamp

Sets the session ID in memory and persists it to disk.

Return value: YES if a new session was created. 

Declared in: Amplitude.m

 

10. - (void) refreshSessionTime:(NSNumber *) timestamp

Update the session timer if there is a running session.

Declared in: Amplitude.m

 

11. - (BOOL) upgradePrefs

Move all preference data from the legacy name to the new, static name if needed. Data used to be in the NSCachesDirectory, which would sometimes be cleared unexpectedly, resulting in data loss. We move the data from NSCachesDirectory to the current location in NSLibraryDirectory.

Declared in: Amplitude.m

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request
Return to top

Related articles