Backspin iOS SDK

The REST API offers some extended functionality that is currently not covered by the v1.2.0 Beta iOS SDK (Mid June 2016 A.D.). In the following examples, the placeholders {appid}, {appaccountid}, {useraccountid}, {rootscopeid}, and {language} can be used in server-requests directly (if using the SDK-methods) and will be replaced with the currently set values.

If using the source/dependency/library manager Cocoa Pods, the installation is straightforward. Paste the following line inside your podfile:

You might need to replace the linked .podspec.json file with Backspin-iOS-SDK_1.2.0-beta.1.92.podspec.json

Since the SDK contains Swift code, you need to configure CocoaPods to use frameworks and work with iOS 8.0 upward. Insert the following at the top of your podfile:

The frameworks can also be installed manually.

Download the zipped framework from here: http://sdk.favendo.de/Backspin-iOS-SDK/Backspin-iOS-SDK_1.2.0-beta.1.92.zip

Extract the ZIP and add all frameworks from the “/Framework” folder to your framework as embedded: Select your target(s), go to “General” and drag the following frameworks from the folder above into the “Embedded Binaries” section:

To be able to access the current location of the user, you have to ask about permission to do so.

For different platforms there are different configurations needed:

iOS 8: Add the NSLocationWhenInUseUsageDescription key to the Information Property List. Add a custom string value describing why you have to access the user’s current location.

iOS 9: In order to work with indoor-positioning/location-based-content/beacon-proximity in the background, you need to enable the “Location Updates” Background-Mode. If you do not use any of these features in background mode, you should restrain from setting this flag. Otherwise it is likely for Apple to question its use during the review process. See more detail in the Troubleshooting / FAQ section and the official documentation Apple Documentation for CLLocationManager.

This will only concern you if you are using CocoaLumberjack as a logging framework.

If so, the unique Backspin iOS SDK logging-flags will not interfere with the default ones. However, in order to manage logging-levels, all current DDTTYLoggers will be removed on calling setupBackspinWithApiKey:. A default logger is added again via [DDLog addLogger:[DDTTYLogger sharedInstance]]. If this doesn’t suit your needs, you can change it in the success or error-block of the setup-method. All other Cocoalumberjack loggers will not be affected.

If you are do custom Beacon Region Monitoring with the CLLocationManager, you should notify the BackspinSDK about the regions that are monitored. When starting monitoring/positioning, all current regions are removed from monitoring and the current positioning-regions are added again. This is done to ensure there are no dangling/unused regions if the positioning-UUID is changed.

Obviously this leads to the removal of any custom created beacon-regions that are monitored somewhere else in the app. You need to whitelist these regions for the SDK to keep them. Before calling setupBackspinWithApiKey, you need to add your UUIDs to this set:

Geo-Regions (CLCircularRegion) are NOT affected by the cleanup.

In order to use any functionality of the Backspin iOS SDK, make sure you import the header file.

The BackspinSDKController is the main interface for communicating with Backspin.

for an extensive list of functions, see the sections List of Functions

In the following section you’ll see how to set up the controller and implement a delegate method to receive location updates. If you are using crypto-beacons with rolling-ids, make sure you configure the start-region-monitoring or beacon-ranging methods accordingly (see code-example below).

Two properties should be set before calling setupBackspinWithApiKey:. 1.) The root-scope-id, otherwise a random scope-id will be used for the initial model-download (this is relevant only if you have more than one root-scope-id, e.g. multiple root-venues). 2.) As mentioned in Custom Region Monitoring, add custom monitored beacon UUIDs to whiteListBeaconUuidsForBeaconMonitoring.

For further implementation details look at the public header files.

The following methods are required even if your App is confined to beacon-proximity-notifications (without indoor-positioning). In the end all methods will trigger/handle beacon-ranging.

If no positioning-beacons are available in the backend but notifications are linked to proximity beacons, monitoring will be started automatically.

Since iOS 7.1, beacon region monitoring is reliable and responsive enough to be preferable to manual positioning ranging.

If the positioning is only used to display the position on the map and will be stopped if the map is invisible, monitoring might not be needed. In scenarios that require beacon responsiveness in the background, e.g. for proximity-notifications (see Location Based Notifications) which fire in the background upon entering a venue, monitoring makes more sense.

Monitoring in iOS means, the app can be woken up by iOS and to start ranging/positioning and also deliver Location Based Notifications in the background. The app is active for up to 10 seconds (if background mode is disabled) or 3 minutes (if enabled). After that time, the App will be shut down again. Keep in mind the considerations mentioned at Notes about iOS Background Modes.

Two different methods for positioning can be used:

There are three different methods to stop beacon-ranging / monitoring:

There are two settings presets which bundle a number of specific configurations to optimize the SDK for certain scenarios.

While the use of these presets are not required, they are recommended in terms of user experience.

These settings are explained in the BSSDKPositioningConfiguration enum which can be found in the header-file <BackspinSDK/BackspinSDKControllerPositioningConfiguration.h>. The default setting for each configuration per preset is listed there.

Each of these settings can be set once the success block of the setup method has been called. At this point, the accuracy-presets can be activated as well.

Supplementary to the set of stability filters provided by the SDK, there are some UI adjustments that can facilitate more satisfactory user experience.

The Backspin iOS SDK listens to compass heading updates by default. The results are published via global NSNotifications with the key kFAVCompassHeadingUpdateNotification.

The delegate callback shouldDisplayHeadingCalibrationPopup determines the display of the calibration overlays for the compass. Note that the compass-bearing is only available on iPhone and iPad, not iPod Touch.

For all internal notifications (location-based-content and beacon-proximity-notifications), beacon-ranging is required. If neither WhenInUse nor AlwaysUsage location-services permissions are granted by the user, then obviously the SDK cannot produce these notifications.

If AlwaysUsage is granted, then the notifications-module will start monitoring for proximity notifications automatically (or rather the UUID of linked proximity-beacons). For location-based notifications, positioning needs to be triggered explicitly. See also die Positioning chapter of this documentation.

To receive notifications from Backspin SDK, implement the corresponding delegate method:

This delegate method uses the BSAppNotificationModel with the following properties (Source comments omitted here, please refer to the public header file):

The notificationKeyValueData property contains all the custom key-value pairs that were defined for this notification in the Backspin Dashboard, for instance:

The actions-array contains actions that are associated with this notification, mainly to be interpreted and executed by the Backspin iOS SDK itself.

If you want the actions to be executed, forward the model to the SDK: [[BackspinSDKController sharedInstance] executeAppNotification:appNotificationModel];

At the moment, two action types are available:

If a detailview (e.g. for an offer or a venue/shop) shall be displayed as a result of a notification that is executed via executeAppNotification:, a module-interface needs to be provided, as described here: How to create Custom Views through BackspinSDK Push Service

The Backspin iOS SDK automatically searches for the Localizable.string file to localise any popups. If you don’t use the Localizable.string file you should implement the BackspinSDKControllerDatasource protocol and return your own custom translations.

The following keys exist and should be translated:

Without a Localizable.strings, implement the datasource method:

A short example on how the workflow should look like:

The REST v2 API (introduced in SDK v1.2) is designed to be less "chatty", thus reducing the amount of REST calls for each client. Instead of separate endpoints for each model-type, there is now one global endpoint for all models. Since not all model-types might be required, the amount of data downloaded can be reduced with exclusion filters or a positive list of "objects of interest".

To reduce the number of requests, the SDK itself will not perform any updates on its own. It is advisable to call triggerContentUpdateFromServer inside the completion-block of the initial setup, which will download the minimum set of model-types:

Additionally, three (root) model-types can be requested. For each one of these, a set of exclusions can be defined for unwanted properties (at the root-level)

To complete the source-example from the prior section to request an extended set of model-types:

In this request, besides Beacon, Level, NavigationGraph, and NotificationConfig model-types, all Venue models will be downloaded but without their venueLocations property. All models would be downloaded in German (de) and for the root-venue with scope-id 23.

You may reuse the objectsOfInterest set for other rootscope requests as well.

If you require a custom model-type to be loaded/updated, you must use requestModelDownloadOrUpdateForRestEndpoint every time rather than triggerContentUpdateFromServer

All models downloaded from Backspin are persisted as JSON, so the only model-object that is available is BSGenericModelSQLite which offers generic accessors according to object-type (e.g. stringForName:). All nested/linked models will be replaced with generic-model-instances automatically, e.g. the linked VenueCategory models from within a Venue model:

The SDK provides a set of Objective-C categories for BSGenericModelSQLite models returned by the rootscopedata REST endpoint:

In order to save client and server resources, an update-operation is only performed at most every 30 minutes. For an instant update-operation, call resetServerUpdateTimestampsAndTriggerModelDownloadOrUpdateForRestEndpoint:andCompletionBlock: While the update-operation is in progress, all existing models remain available.

Particularly for the User Accounts API, it is advisable to download and upload plain JSON data:

If you cannot compile the project, some additional flags might need to be set. First, make sure all flags are set as described in Adjust Project Settings.

If this error shows up after starting the app, make sure that the Build-Setting flag “Embedded Content Contains Swift Code” is set to “Yes”

During the review process, Apple might take a second look if an app requires any kind of background activity as indicated by settings in the apps Info.plist.

Since iOS 9, suspended apps that want to work with the CLLocationManager in any way need a "Location Updates" background mode flag, which is a permission for GPS as well as beacon updates. However, even if an app uses beacon related activity in background-mode, Apple wants to make sure this use is justified. As generally the case in App Store Reviews, it will be Apple deciding whether your reasons meet their standards of justifiability.

Remember that even without the "Location Updates" background mode, the app will be woken up with monitoring and can performs tasks for 10 seconds. Proximity events triggered by smartly placed beacons usually suffice.

See more Apple Documentation "Declaring Your App’s Supported Background Tasks "

Apple does allow background mode for "Navigation" apps which provide continuous turn-by-turn directions in the background. Such apps usually provide speech output for the next direction while in background.

Apple wants to make sure that the privacy of app-end-users is a high priority, while at the same time use battery power as conservatively as possible. Any kind of background activity, especially in combination with the users location, is not taken lightly - which is one reason why the AlertView text sounds so "scaring".

Allow "App X" to access your location even when you are not using the app?

Unfortunately, beacon monitoring does not work - neither in background nor in foreground - if the AlwaysUsage permission is not granted. Positioning and beacon ranging can still be started "manually" though.

You do not need the AlwaysUsage permission if you do not perform anything in the background - as described in detail above. But if AlwaysUsage is enabled and granted by the user, even without Background Mode, it is still possible to wake up the app for about 10 seconds even by monitoring. If you do not intend to publish a location-based or beacon-proximity notification while the app is in background (or any notification that is related to entering a beacon-region), the WhenInUse permission suffices. Likewise, if you merely display a map with a user’s position and stop any Beacon-related activities if the map is not visible, neither a Background Mode nor the AlwaysUsage permissions are required.

Make sure that Bluetooth is enabled on the device and a permission has been granted for Location Services, either AlwaysUsage or WhenInUse.

The positioning will NOT start if monitoring is used and the AlwaysUsage permission has not been granted by the app-user, even if the app is in foreground.

If the user has just revoked the permission or disabled Bluetooth, the monitoring will start (again) as soon as the AlwaysUsage permission is given again and Bluetooth is enabled.

With WhenInUse permissions, the positioning/ranging has to be started "manually":

In this case positioning will stop once the app goes in to background mode.

It is also possible that your data is not available yet. Since with version 1.2, no data is downloaded automatically, you will need to call triggerContentUpdateFromServer or requestModelDownloadOrUpdateForRestEndpoint: before positioning, navigation, or notifications can be used. See also Model-Store & Server API for the API to request models from the server.

Make sure that the beacons are configured for "Navigation" in the dashboard and the correct root-scope is selected. A useful indicator for incorrect data is to check whether beacons are ranged at all (e.g. if the global kFAVBeaconsRangedNotification notification is fired).

See also The setup and/or data download takes too long if you can see ranged beacons, yet still do not receive notifications or a position.

It is possible that your data is not available yet. Since with version 1.2, no data is downloaded automatically, you will need to call triggerContentUpdateFromServer or requestModelDownloadOrUpdateForRestEndpoint: before positioning, navigation, or notifications can be used. See also Model-Store & Server API for the API to request models from the server. See also the next section for timeouts.

Make sure that a valid path actually exists. If you defined a KML with directed paths, there should be at least one route in the desired direction that is passable. Likewise, if barrier-free navigation is enabled, there should be at least one barrier-free path.

There are multiple reasons why the setup-block is not called or with a high delay. Usually, either the Backspin server is offline/not reachable or the device has no sufficient internet connection.

If this is the first time the setup-method is called, the SDK will render functionless, since it needs to initially register at the server and download data. The SDK will wait until it finds the Backspin server reachable (see Apple Reachability for iOS). Only if the reachability status changes, an request-attempt is made. After the initial download, all data is available offline. If the reachability status indicates that the Backspin server is reachable, an update request might be attempted.

If cellular data is available but no data can be received (e.g. exhausted mobile data plan), iOS will determine the device to be online and the SDK will try to perform data updates if the SDK-data has "expired", so the SDK callbacks are called with a delay until the requests time-out. Custom timeouts can be set in order for the update-requests to terminate faster. There are three configurable network timeouts in the SDK:

requestTimeoutForAccountRegistration An account is created at the very first start of the SDK and update whenever a new APNS-token is provided. If it is not the first start any more, the setup will return immediately and use offline-data.

Only after the account-request returns, the setup is continued. By default, the account-request times out after 10 seconds

requestTimeoutForRootVenues After the account data has been loaded (from server or the offline storage), the root-venues are updated. An update is only performed every half an hour and only if the Backspin server reachability status is Reachable. Only if the setup will continue/complete, the root-venue-request returns. By default, the root-venue-request times out after 10 seconds.

requestTimeoutForOtherRequests Used fo all other requests.

In the worst-case scenario where all consecutive timeouts are triggered, it can take up to 20 seconds until the setup is completed and another 10 seconds for the SDK is to start loading data (if prior setup was successful).