iOS integration guide
Update October 26th 2017: We have updated this guide after the release of version 2.0.2 of our iOS plugin.
We assume in this guide you already have an account for our dashboard. Don't have an account yet? Schedule a demo and we'll invite you to your account.
From the description in the App Store it must be clear for the end user why location services are required. This is something Apple often checks during the review of your app. It is possible to change the description to ensure that it is clear for the end user why location services are required. You can find more information about this in the integration guide.
This guide shows how to integrate iOS version of the Plot plugin. You can find all versions at our download page.
- Integration with Cocoapods, using Swift
- Integration with Cocoapods, using Objective C
- Integration without Cocoapods, using Swift
- Integration without Cocoapods, using Objective C
Integration with Cocoapods, using Swift¶
To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.
Step 1: Update your podfile¶
If you are using CocoaPods, just add the following line to your Podfile to integrate the library into your IOS application.
Add the following to your podfile:
use_frameworks!
pod 'PlotPlugin'
or if you want to use a specific version:
use_frameworks!
pod 'PlotPlugin', '3.5.4'
Step 2: Run pod install¶
Run
pod install --repo-update
to let Cocoapods download our library and setup the new project structure.
Step 3: Add usage description¶
Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing why your app uses the location of the device. For example: "Your location is used to instantly inform you when you are near a location that is interesting to you."
| Required key | Description shown in XCode |
|---|---|
| NSLocationAlwaysUsageDescription | Privacy - Location Always Usage Description |
| NSLocationWhenInUseUsageDescription | Privacy - Location When In Use Usage Description |
| NSLocationAlwaysAndWhenInUseUsageDescription* | Privacy - Location Always and When In Use Usage Description |
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.
This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.
Step 4: Add configuration file¶
You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.
Add this file as plotconfig.json in the root folder.
{
"publicToken": "REPLACE_ME",
"enableOnFirstRun": true
}
Step 5: Add PlotDelegate¶
Add PlotDelegate to the implemented protocols of your AppDelegate.
@UIApplicationMain
class AppDelegate: UIResponder,
UIApplicationDelegate,
PlotDelegate
Step 6: Implement AppDelegate¶
Warning
In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.
In your AppDelegate call
PlotDebug.initialize(with: self)
Inside the function
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
The initialize method must be called before the end of that method.
Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default. If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.
import PlotProjects
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(with: self)
//This method must be called before the end of application(,didFinishLaunchingWithOptions)
return true
}
Now the Plot Projects library is ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.
An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.
Recommended: Set User ID¶
By default the Plot Plugin uses a unique identifier per installation to connect the data generated by each device. We highly recommended setting your own user_id in the Plot Plugin in addition to ease the integration with your own tools.
To set your own User ID, set a segmentation property key user_id and value <Your User ID>. Following the previous step, add the following line to the AppDelegate:
import PlotProjects
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(launchOptions: launchOptions, delegate: self)
PlotBase.setStringSegmentationProperty("<Your User ID>", forKey: "user_id")
return true
}
Read about why to use a custom User ID and more in User ID - How to get started.
Optional: Set Advertising Identifier (IDFA)¶
To send the IDFA to the Plot Plugin, add in the target settings the AdSupport.framework library in "Link Binary with libraries" under "Build phases". Then add the following lines to the AppDelegate:
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(launchOptions: launchOptions, delegate: self)
let advertisingIdentifier = ASIdentifierManager.shared().advertisingIdentifier
let advertisingTrackingEnabled = ASIdentifierManager.shared().isAdvertisingTrackingEnabled
PlotBase.setAdvertisingIdentifier(advertisingIdentifier, advertisingTrackingEnabled: advertisingTrackingEnabled)
return true
}
Read more about using the IDFA at Advertising identifier - How to get started.
Step 7: Test and Troubleshoot¶
If the integration was successful, look at the testing section of the documentation for more details. In case you had issues integrating our SDK, look into our troubleshooting section for help.
Integration with Cocoapods, using Objective C¶
To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.
Step 1: Update your podfile¶
If you are using CocoaPods, just add the following line to your Podfile to integrate the library into your IOS application.
Add the following to your podfile:
use_frameworks!
pod 'PlotPlugin'
Step 2: Run pod install¶
Run
pod install --repo-update
to let Cocoapods download our library and setup the new project structure.
Step 3: Add usage description¶
Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing why your app uses the location of the device. For example: "Your location is used to instantly inform you when you are near a location that is interesting to you."
| Required key | Description shown in XCod |
|---|---|
| NSLocationAlwaysUsageDescription | Privacy - Location Always Usage Description |
| NSLocationWhenInUseUsageDescription | Privacy - Location When In Use Usage Description |
| NSLocationAlwaysAndWhenInUseUsageDescription* | Privacy - Location Always and When In Use Usage Description |
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.
This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.
Step 4: Add configuration file¶
You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.
Add this file as plotconfig.json in the root folder.
{
"publicToken": "REPLACE_ME",
"enableOnFirstRun": true
}
Step 5: Add PlotDelegate¶
Add PlotDelegate to the implemented protocols of your AppDelegate in the header (.h) file.
#import <PlotProjects/Plot.h>
@interface AppDelegate : UIResponder
<UIApplicationDelegate, PlotDelegate>
Step 6: Implement AppDelegate¶
Warning
In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.
In the implementation file (.m) of your AppDelegate call [Plot initializeWithDelegate:self]; in application:didFinishLaunchingWithOptions:. The initialize method must be called before the end of that method.
Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default.
If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false.
When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
return YES;
}
Now the Plot Projects library is ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.
An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.
Recommended: Set User ID¶
By default the Plot Plugin uses a unique identifier per installation to connect the data generated by each device. We highly recommended setting your own user_id in the Plot Plugin in addition to ease the integration with your own tools.
To set your own User ID, set a segmentation property key user_id and value <Your User ID>. Following the previous step, add the following line to the AppDelegate:
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
[Plot setStringSegmentationProperty:@"<Your User ID>" forKey:@"user_id"];
return YES;
}
Read about why to use a custom User ID and more in User ID - How to get started.
Optional: Set Advertising Identifier (IDFA)¶
To send the IDFA to the Plot Plugin, add in the target settings the AdSupport.framework library in "Link Binary with libraries" under "Build phases". Then add the following lines to the AppDelegate:
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
[Plot setAdvertisingIdentifier:[[ASIdentifierManager sharedManager] advertisingIdentifier] advertisingTrackingEnabled:[[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]];
return YES;
}
Read more about using the IDFA at Advertising identifier - How to get started.
Step 7: Test and Troubleshoot¶
If the integration was successful, look at the testing section of the documentation for more details. In case you had issues integrating our SDK, look into our troubleshooting section for help.
Integration without Cocoapods, using Swift¶
To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.
Step 1: Get The Library¶
Once you log in to our dashboard, download the library under the "Developer Tools" page.
Step 2: Add PlotProjects.framework and other dependencies to your project¶
Extract the zip file and copy the PlotProjects.framework file to your project.
In the target settings add the following libraries in "Link Binary with libraries" under "Build phases"
- PlotProjects.framework
- libsqlite3.tbd
- CoreLocation.framework
- MessageUI.framework
- UserNotifications.framework
- AppTrackingTransparency.framework *
- AdSupport.framework *
* required for iOS 14
You also need to add PlotProjects.framework to Embedded Binaries as well
Step 3: Add usage description¶
Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing why your app uses the location of the device. For example: "Your location is used to instantly inform you when you are near a location that is interesting to you."
| Required key | Description shown in XCode |
|---|---|
| NSLocationAlwaysUsageDescription | Privacy - Location Always Usage Description |
| NSLocationWhenInUseUsageDescription | Privacy - Location When In Use Usage Description |
| NSLocationAlwaysAndWhenInUseUsageDescription* | Privacy - Location Always and When In Use Usage Description |
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.
This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.
Step 4: Add configuration file¶
You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.
Add this file as plotconfig.json in the root folder.
{
"publicToken": "REPLACE_ME",
"enableOnFirstRun": true
}
Step 5: Add PlotDelegate¶
Add PlotDelegate to the implemented protocols of your AppDelegate.
@UIApplicationMain
class AppDelegate: UIResponder,
UIApplicationDelegate,
PlotDelegate
Step 6: Implement AppDelegate¶
Warning
In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.
In your AppDelegate call
PlotDebug.initialize(launchOptions: launchOptions, delegate: self) in func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool
The initialize method must be called before the end of that method.
Plot is enabled by default on the first run. If you don't want Plot enabled by default, you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default.
If you don't want the permission dialogs to appear straight away when it initializes,
then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false. When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.
import PlotProjects
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(launchOptions: launchOptions, delegate: self)
//This method must be called before the end of application(,didFinishLaunchingWithOptions)
return true
}
Now the Plot Projects library is ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.
An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.
Recommended: Set User ID¶
By default the Plot Plugin uses a unique identifier per installation to connect the data generated by each device. We highly recommended setting your own user_id in the Plot Plugin in addition to ease the integration with your own tools.
To set your own User ID, set a segmentation property key user_id and value <Your User ID>. Following the previous step, add the following line to the AppDelegate:
import PlotProjects
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(launchOptions: launchOptions, delegate: self)
PlotBase.setStringSegmentationProperty("<Your User ID>", forKey: "user_id")
return true
}
Read about why to use a custom User ID and more in User ID - How to get started.
Optional: Set Advertising Identifier (IDFA)¶
To send the IDFA to the Plot Plugin, add in the target settings the AdSupport.framework library in "Link Binary with libraries" under "Build phases". Then add the following lines to the AppDelegate:
func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
//Register your notification center delegate before initializing Plot:
//let center = UNUserNotificationCenter.current()
//center.delegate = ...
//PlotDebug enables extra debug logging
//which makes it easier to understand
//what is going on
//Replace PlotDebug with PlotRelease
//to disable debug logging
PlotDebug.initialize(launchOptions: launchOptions, delegate: self)
let advertisingIdentifier = ASIdentifierManager.shared().advertisingIdentifier
let advertisingTrackingEnabled = ASIdentifierManager.shared().isAdvertisingTrackingEnabled
PlotBase.setAdvertisingIdentifier(advertisingIdentifier, advertisingTrackingEnabled: advertisingTrackingEnabled)
return true
}
Read more about using the IDFA at Advertising identifier - How to get started.
Step 7: Test and Troubleshoot¶
If the integration was successful, look at the testing section of the documentation for more details. In case you had issues integrating our SDK, look into our troubleshooting section for help.
Integration without Cocoapods, using Objective C¶
To use the library in an iOS application, a few steps must be performed. The first steps differ based on whether or not you're using Cocoapods. The Cocoapods integration is the easiest, but if you want to add the library yourself to the project that is fine too.
Step 1: Get The Library¶
Once you log in to our dashboard, download the library under the "Developer Tools" page.
Step 2: Add PlotProjects.framework and other dependencies to your project¶
Extract the zip file and copy the PlotProjects.framework file to your project.
In the target settings add the following libraries in "Link Binary with libraries" under "Build phases"
- PlotProjects.framework
- libsqlite3.tbd
- CoreLocation.framework
- MessageUI.framework
- UserNotifications.framework
You also need to add PlotProjects.framework to Embedded Binaries as well
Step 3: Add usage description¶
Add in "Custom iOS Target Properties" under "Info" the keys from the table below. Each value must be a message for the user describing why your app uses the location of the device. For example: "Your location is used to instantly inform you when you are near a location that is interesting to you."
| Required key | Description shown in XCode |
|---|---|
| NSLocationAlwaysUsageDescription | Privacy - Location Always Usage Description |
| NSLocationWhenInUseUsageDescription | Privacy - Location When In Use Usage Description |
| NSLocationAlwaysAndWhenInUseUsageDescription* | Privacy - Location Always and When In Use Usage Description |
* this key is added in XCode 9. If you're using XCode 8, you can add the key yourself.
This text is shown when permission to use the location of the device is requested. Note that for the app to be accepted in the App Store, the description why the app needs location services must be clear to the end user.
Step 4: Add configuration file¶
You can configure Plot through the configuration file. You can find an example config file and your public token on the Developer page on our dashboard.
Add this file as plotconfig.json in the root folder.
{
"publicToken": "REPLACE_ME",
"enableOnFirstRun": true
}
Step 5: Add PlotDelegate¶
Add PlotDelegate to the implemented protocols of your AppDelegate in the header (.h) file.
#import <PlotProjects/Plot.h>
@interface AppDelegate : UIResponder<UIApplicationDelegate, PlotDelegate>
Step 6: Implement AppDelegate¶
Warning
In the case that you need to register your own UNUserNotificationCenter delegate, you need to do that before initializing the plugin, so that Plot can forward notifications that aren't created by Plot. If you do it after initializing, then the notification handler/notification events will no longer work.
In the implementation file (.m) of your AppDelegate call [Plot initializeWithDelegate:self]; in application:didFinishLaunchingWithOptions:.
The initialize method must be called before the end of that method.
Plot is enabled by default on the first run. If you don't want Plot enabled by default,
you can set the enableOnFirstRun property in plotconfig.json to false if Plot shouldn't be enabled by default.
If you don't want the permission dialogs to appear straight away when it initializes, then you can add the automaticallyAskLocationPermission property and the automaticallyAskNotificationPermission property in plotconfig.json to false.
When setting those properties to false, you become responsible yourself for asking the user for location services and notification permissions.
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
return YES;
}
Now the Plot Projects library is ready for use! Create a notification in the dashboard at your current location and launch your app to verify it's working.
An example configuration file and your public token can be found on the Help page on our dashboard. You are now ready to receive your first notification. Need more help during testing, look at the test guide.
Recommended: Set User ID¶
By default the Plot Plugin uses a unique identifier per installation to connect the data generated by each device. We highly recommended setting your own user_id in the Plot Plugin in addition to ease the integration with your own tools.
To set your own User ID, set a segmentation property key user_id and value <Your User ID>. Following the previous step, add the following line to the AppDelegate:
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
[Plot setStringSegmentationProperty:@"<Your User ID>" forKey:@"user_id"];
return YES;
}
Read about why to use a custom User ID and more in User ID - How to get started.
Optional: Set Advertising Identifier (IDFA)¶
To send the IDFA to the Plot Plugin, add in the target settings the AdSupport.framework library in "Link Binary with libraries" under "Build phases". Then add the following lines to the AppDelegate:
@implementation AppDelegate
-(BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
//Register your notification center delegate before initializing Plot:
//[UNUserNotificationCenter currentNotificationCenter].delegate = ...
//initializes the Plot library:
[Plot initializeWithDelegate:self];
//This method must be called before the end of the application:didFinishLaunchingWithOptions: method
[Plot setAdvertisingIdentifier:[[ASIdentifierManager sharedManager] advertisingIdentifier] advertisingTrackingEnabled:[[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]];
return YES;
}
Read more about using the IDFA at Advertising identifier - How to get started.
Step 7: Test and Troubleshoot¶
If the integration was successful, look at the testing section of the documentation for more details. In case you had issues integrating our SDK, look into our troubleshooting section for help.