In Xcode, make sure the following conditions are met:
TapPoint SDK uses location services to find out information about the user's current location. As of iOS 8, when using location services, you are required to add a string value for the NSLocationAlwaysUsageDescription within your application's .plist file. iOS uses this string to display a message when asking the user for permissions to use their location information.
You can download the SDK reference app here.
The TapPoint SDK uses CocoaPods and can be found here. To use the SDK, simply add the following line to your Podfile dependancies:
pod 'TapPointSDK', '~> 3.3.0'If you need to add CocoaPods to your project, please follow the guide here.
As the TapPoint SDK uses categories, the final stage of installation requires you to add a linker flag to the main target of your application. This can be done by navigating to the Build Settings tab, then finding Other Linker Flags. Then add -ObjC as a linker flag, if it is not already there.
The TapPoint SDK has a set of APIs that you can use to:
Several of these APIs provide relevant and useful feedback via blocks. In the case where an API provides a failure callback, you can inspect an NSError object to find out more information on the reason for failure. In the case where the API does not provide a callback for failure, a log message will be provided to the debug console within your Xcode development environment, or using Console.app.
You can import the <TapPointSDK/TapPointSDK.h> header to use any of the TapPoint SDK APIs.
Authenticate with TapPoint by passing the application name (provided by Proxama) as a parameter to the authenticateWithAppName:success:failure: method.
It is important that you call this API in your AppDelegate's application:didFinishLaunchingWithOptions: method.
[[PRXAuthentication sharedAuthenticationManager] authenticateWithAppName:@"example_app_name" success:^{
// The application successfully authenticated with TapPoint
} failure:^(NSError *error) {
// The application failed to authenticate with TapPoint
}];
This API should be called every time your application launches to ensure that other APIs being called can be used.
One of the advantages of using TapPoint SDK is that it delivers campaign data even in areas of no connectivity (underground, stadiums). Triggers, which encapsulate campaign data, are required to be synced down to the SDK prior to a campaign starting.
For testing purposes we've sent 3 physical beacons to help you with your integration (or if you have an iOS device you can use our Virtual Beacon app to simulate a beacon). To add campaign data to these Triggers use the TapPoint Beacon Payload Editor tool. Once saved, perform a sync:
[[PRXSynchronisation sharedSynchronisationManager] synchroniseWithSuccess:^(PRXSyncResult *result) {
// The application synchronised successfully with TapPoint
} failure:^(NSError *error) {
// The application failed to synchronise with TapPoint
}];
Upon successful synchronisation with TapPoint, the success block provides a PRXSyncResult object that contains arrays of both Triggers that have been added, and Triggers that have been removed during this synchronisation. This is purely for your information, the Triggers will be automatically stored by the TapPoint SDK. In the instance where synchronisation has failed, you can inspect the NSError object to find out the reason for failure where both an error code and error description is provided.
Once Triggers have been successfully synced onto the device, you do not have to sync again, unless the Trigger data on TapPoint has changed (e.g. a new campaign has been created). A synchronisation strategy should be decided to best meet your use case.
A simple syncing strategy would be to perform a synchronisation with TapPoint every time your application launches. Thereafter, you could implement Background Fetch to perform a sync after every 24 hours. Register for Background Fetch in your App Delegate and in the performFetchWithCompletiongHandler: method you can call TapPoint as below:
-(void)application:(UIApplication *)application performFetchWithCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler
{
[[PRXSynchronisation sharedSynchronisationManager] synchroniseWithSuccess:^(PRXSyncResult *result) {
if (completionHandler) {
if (result.triggersAdded.count > 0 || result.triggersRemoved.count > 0) {
completionHandler(UIBackgroundFetchResultNewData);
} else {
completionHandler(UIBackgroundFetchResultNoData);
}
}
} failure:^(NSError *error) {
if (completionHandler) {
completionHandler(UIBackgroundFetchResultFailed);
}
}];
}
Notifications about Trigger events are emitted by the default NSNotificationCenter, and in order to listen to these events you need to add yourself an as observer to NSNotificationCenter notification events named PRXTriggersDetectedNotification and provide a callback message (e.g. triggerDetected:) which will be sent when a Trigger event is fired.
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(triggerDetected:) name:PRXTriggersDetectedNotification object:nil];
Call startMonitoring to begin scanning for Triggers. Notifications will then be generated in response to Trigger events.
[[PRXTriggers sharedTriggersManager] startMonitoring];
NOTE: If you are monitoring for Trigger events, any new Triggers subsequently added will automatically be monitored.
NOTE: Trigger events can only be detected and notifications sent when the user has bluetooth/location services turned on, but should the user disable bluetooth/location services, they will automatically start being detected and sending notifications once they are turned on again. There is no need to call startMonitoring again to make that happen.
If you wish to stop monitoring for Trigger events call the stopMonitoring method to stop being notified.
[[PRXTriggers sharedTriggersManager] stopMonitoring];
Upon receiving a Trigger event (e.g. coming in range of a beacon you are listening for), the callback message you previously defined will be sent and you will be delivered the PRXTrigger object which encapsulates your campaign data.
The PRXTrigger object is available in the userInfo dictionary of the NSNotification, using the PRXDetectedTriggerNotificationKeyForTrigger key. This includes the unique identifier of the trigger, and the trigger payload data that you defined earlier.
- (void)triggerDetected:(NSNotification *)notification
{
PRXTrigger *trigger = [notification.userInfo objectForKey:PRXDetectedTriggerNotificationKeyForTrigger];
NSLog(@"Trigger ID: %@", trigger.identifier);
NSLog(@"Trigger Payload: %@", trigger.payload);
}
NOTE: iOS does not report that the device has left the range of a beacon until its signal remains undetected for long enough to rule out temporary physical interference with the Bluetooth low-energy radio signal. This can take up to 1 minute.