This Quick Start Guide will walk you step-by-step through how to download and integrate the Amplitude iOS SDK into your application. For a reference on events and sessions, read here.
If you’re ready to get started, read on!
Step 1: Register for an Account
Start by registering for an account at https://amplitude.com. You will be assigned an API key which you’ll see as soon as you log in under Settings.
You’ll definitely want to record this key somewhere or set it as an environmental variable so you don’t have to constantly be referring back to this page.
Step 2: Download the Source
The next step is to download the source code, then extract the zip file it comes in. Extract the Amplitude folder into your app’s root directory, or use the dependency managers CocoaPods or Carthage, which will do this automatically.
For Cocoapods, add the following line to your Podfile:
pod 'Amplitude-iOS', '~> 3.8.5'.
If you are using CocoaPods, then steps 3 and 4 below will automatically be done for you, so skip to 5.
For Carthage, add the following line to your Cartfile:
github "amplitude/Amplitude-iOS".
Then, to import Amplitude into your app, add the following line of code to your headers:
#import <Amplitude/Amplitude.h>
Step 3: Copy Amplitude into Xcode
Copy the Amplitude sub-folder into the source of your project in Xcode. Check “Copy items into destination group’s folder (if needed).”
This loads the Amplitude code right into the control system of your project allowing it to access all relevant files.
Step 4: Build SQLite Flag
Amplitude’s iOS SDK requires the SQLite library, which is included in iOS but requires an additional build flag to enable. The SQLite library implements an SQL database engine that helps read the SDK code.
In your project’s Build Settings and your Target’s Build Settings, under Linking -> Other Linker Flags, add the flag -lsqlite3.0.
Step 5: Add Amplitude to Analytics Files
In every file that uses analytics, import Amplitude.h at the top. These include files that contain event logic, user definitions or any data that you’d like to track and analyze.
This code will include the Amplitude framework into the file and allow Amplitude access to those analytics.
#import "Amplitude.h"
We’ll pull examples from a 2048 demo application with Google Tag Manger (GTM) integrated to demonstrate how these steps are followed.
In this [AmplitudeGTMHandlers.m](https://github.com/amplitude/GTM-iOS-Demo/blob/master/m2048/AmplitudeGTMHandler.m) file we see:
Step 6: Initialize SDK
For every file in which you intend to grab data to analyze in Amplitude, you need to initialize the SDK. In the application:didFinishLaunchingWithOptions: method of your YourAppNameAppDelegate.m file, you initialize the SDK:
[[Amplitude instance] initializeApiKey:@"YOUR_API_KEY_HERE"];
You can see an example in [M2AppDelegate.m](https://github.com/amplitude/GTM-iOS-Demo/blob/master/m2048/M2AppDelegate.m):
Great work! At this point you’ve integrated the SDK into your app and are ready to start tracking analytics. Read on below to dive deeper into how events are tracked and logged, along with other potential integration options you have.
Track Events
Events are defined as any user action taken within your app. Amplitude is an event-based analytics platform so it’s important to choose and track events strategically.
To track an event anywhere in the app, call:
[[Amplitude instance] logEvent:@"EVENT_IDENTIFIER_HERE"];
“logEvent” works as a Function Call meaning when you want to log an event, you push a “logEvent” event to the data layer with the variables for “eventType” and “eventProperties.” This activates the logEvent trigger, which activates the logEvent tag. The function logEvent is then called in the Handler file, here it’s the AmplitudeGTMHandler.m file. This calls the SDK’s logEvent.
We see this implemented in this [M2GameManager.m](https://github.com/amplitude/GTM-iOS-Demo/blob/master/m2048/State/M2GameManager.m#L208-L209) file:
Log Events
Events are saved locally. Uploads are batched to occur every 30 events and every 30 seconds, as well as on app close. You can track Realtime Activity to see how your recent active users are interacting with your app.
After calling logEvent in your app, you will immediately see data appear on the Amplitude Website. As soon as a user logs an event, you can go into Activity Details to see what they’ve done.
Push Notifications
A session is a period of time that a user has your app in the foreground. Sessions are used to separate groups of events. It is possible to log events that don’t occur during a session, for example push notifications, so they don’t go untracked.
Out of session events have a session_id of -1 and are not considered part of the current session, meaning they do not extend the current session. You can log events as out of session by setting input parameter “outOfSession” to true when calling logEvent.
[[Amplitude instance] logEvent:@"EVENT_IDENTIFIER_HERE" withEventProperties:nil outOfSession:true];
Extensions
App extensions allow you to implement custom functionality and content into your app and make it available to users while they’re interacting with other apps, or they’re not exclusively in your app. The Amplitude iOS-SDK can be modified to integrate with these extensions as well.
For those interested in including extensions, you can read more about it in the DemoNotes project code.
