The Geotrigger SDK for iOS is a set of tools to help your app communicate with the Geotrigger Service and provide it with accurate location data without using any more of the device's battery power than absolutely necessary.
At the core of the Geotrigger SDK for iOS is the AGSGTGeotriggerManager
, a wrapper around iOS's native location services, which provides a set of tracking
profiles to support a variety of use cases while preserving battery life as much
as possible. The AGSGTGeotriggerManager
also handles uploading device
locations to the Geotrigger API.
In addition to the manager there is the AGSGTApiClient
which can be used to call any of the server's API methods using the postPath:parameters:success:failure:
method.
Below you'll find the steps required to get your app (new or existing) up and running with the Geotrigger SDK. You also may find the sample project helpful to see a project with the steps outlined here already completed.
NSLocationAlwaysUsageDescription
in your Info.plist
file. This message will be shown to the user when
the operating system first prompts them for permission to use their location. See the Apple Documentation on the subject
for more details.There are two ways to add the Geotrigger SDK for iOS to your project -- manually or using CocoaPods.
Before you can start tracking the device's location or communicating with the Geotrigger API
you'll need to set up the AGSGTGeotriggerManager
singleton by calling one of the setupWithClientId:...
methods.
It is recommended you do this in your UIApplicationDelegate
's application:didFinishLaunchingWithOptions:
so that the manager can be ready to go as soon as possible.
The minimum required parameters to these methods are:
clientId
: Your ArcGIS Online Application's ClientIdisProduction
: A boolean value signifying whether the app is built using a Production or Sandbox Provisioning Profile. This is used to tell the
Geotrigger Server where to send push notifications.completion
: A block that will be executed once the AGSGTGeotriggerManager
is done initializing. The error
parameter will be nil
if setup
was completed successfully, or the error that was encountered otherwise.Other optional parameters include:
tags
: Passing this parameter will cause the AGSGTGeotriggerManager
to add the specified tags to the device automaticallly once it is ready.trackingProfile
: Passing this parameter will cause the AGSGTGeotriggerManager
to turn on location updates automatically when it is ready using
this profile.Here is a common way to start the manager.
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
[AGSGTGeotriggerManager setupWithClientId:kClientId isProduction:NO tags:@[@"test"] completion:^(NSError *error) {
if (error != nil) {
NSLog(@"Geotrigger Service setup encountered error: %@", error);
} else {
NSLog(@"Geotrigger Service ready to go!");
// Turn on location tracking in adaptive mode
[AGSGTGeotriggerManager sharedManager].trackingProfile = kAGSGGTTrackingProfileAdaptive;
}
}];
...
}
By default when you call one of the setupWithClientId:...
methods, AGSGTGeotriggerManager
will set itself up to receive and handle push notifications
automatically by becoming the primary UIApplicationDelegate
and forwarding all UIApplicationDelegate
methods to your UIApplicationDelegate
. This sets it up
so that if your app is in the foreground when a notification is received this will display the notification text in a UIAlertView
with a "Close"
button and a "View" button which will take the user to the URL in the payload if there is one. The View button only shows up if there is a URL in the payload.
If you want to send the user straight to the URL when they open your app in response to a push notification you will need to add the following to your
application:didFinishLaunchingWithOptions:
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
...
// If we were launched from a push notification, send the payload to the Geotrigger Manager
if (launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey] != nil) {
[AGSGTGeotriggerManager handlePushNotification:launchOptions[UIApplicationLaunchOptionsRemoteNotificationKey] showAlert:NO];
}
...
}
If you need to implement custom handling of push notifications you can do so using the normal UIApplicationDelegate
method
(application:didReceiveRemoteNotification:
). Be sure not to call the handlePushNotification:...
methods on AGSGTGeotriggerManager
in this
method though, or your app will notify your user twice!
If you prefer to set up push notifications manually put the following in before your call to setupWithClientId:...
:
[AGSGTGeotriggerManager sharedManager].autoSetupEnabled = NO;
After registering for remote notifications (either by calling the UIApplication
method yourself or via the AGSGTGeotriggerManager
) you’ll need to
send the deviceToken that Apple sends to your UIApplicationDelegate to the Geotrigger Manager so that we can attach it to the device on the server.
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken
{
[[AGSGTGeotriggerManager sharedManager] registerAPNSDeviceToken:deviceToken completion:nil];
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error
{
NSLog(@"Failed to register for remote notifications: %@", error);
}
Guides on various topics are available as part of the Geotrigger Documentation, including interacting with the AGSGTGeotriggerManager
, working with the Geotrigger API, and configuring push notifications. Information about other platforms and the API itself are also available.
The SDK's reference doc is also available in this repo.