iOS – Integrating the SDK

To integrate Point SDK, please register for a Bluedot account here. An SDK works with iOS 10 and above.

Bluedot Point SDK enables an ‘always-on’ geo-location capability for apps by delivering accurate location awareness, while substantially reducing battery consumption compared to Core Location or other standard methods. Point SDK connects to Bluedot’s backend system, Point Access, to download your pre-configured Geofences, GEOLINE™, Bluetooth Beacons, conditions, and actions.

Point SDK enables rapid development of location-aware apps. It delivers precise location awareness to the mobile application, without the battery drain that would typically occur. It requires no additional hardware, making it highly scalable.

Point SDK enables you to provide next-generation experiences on your location-based app.

Please follow the step by step instructions below to integrate Point SDK:


Step 1: Creating the Xcode project

Create the Xcode project:

    1. Start a new Xcode project, using a template appropriate for your app. The following example uses ‘Single View Application‘ for simplicity:
    2. Enter a Product Name and other required details.
      Device selection: Point SDK supports iOS devices with GPS capabilities, running iOS 10.0 or above. It includes most iPhones and cellular models of iPad. For the devices field, any of the ‘iPhone,’ ‘iPad’ or ‘Universal’ options are valid when developing a Point SDK integrated app.
    3. Choose a folder to save the project (e.g. ‘Projects’) and select ‘Create’. Note that Xcode creates the project sub-folder for you. In this case, it will be named ‘BDHelloPointSDK’.

Step 2: Importing Point SDK

To import the Point SDK, you can either:

  1. Import Point SDK with CocoaPods; or
  2. Import Point SDK with Carthage; or
  3. Import Point SDK as a dynamic framework

Option 1: Importing Point SDK with CocoaPods

Follow the CocoaPods installation instructionsBluedotPointSDK can be added into the `Podfile` as a dependency:

    1. Create a Podfile in your project directory, and add a ‘BluedotPointSDK’ dependency
      pod 'BluedotPointSDK'
    2. Run $ pod install in your project directory
    3. Open up the *.xcworkspace and follow the rest of the steps on this page to complete the project setup.
image

Do NOT use *.xcodeproj. If you open up a project file instead of a workspace, you will receive an error.

Option 2: Importing Point SDK with Carthage

Follow the Carthage installation instructions. BluedotPointSDK can be added into the Cartfie as a dependnency.

  1. Create a Cartfile in your project direcotry, and add a ‘BluedotPoinmtSDK’ dependency
    github "Bluedot-Innovation/PointSDK-iOS"
  2. Run $ carthage bootstrap in your project directory. This will fetch BDPointSDK into a Carthage/Checkouts folder and download a pre-compiled framework.
  3. On your application targets’ General settings tab, in the Embedded Binaries section, drag and drop BDPointSDK from the Carthage/Build folder on disk.
  4. On your application targets’ Build Phases settings tab, click the + icon and choose New Run Script Phase. Create a Run Script in which you specify your shell (ex: /bin/sh), add the following contents to the script area below the shell:
    /usr/local/bin/carthage copy-frameworks
  5. Add the path to the BDPointSDK under “Input Files”.
    $(SRCROOT)/Carthage/Build/iOS/BDPointSDK.framework
  6. Add the paths to the copied BDPointSDK to the “Output Files”.
    $(BUILT_PRODUCTS_DIR)/$(FRAMEWORKS_FOLDER_PATH)/BDPointSDK.framework

    With output files specified alongside the input files, Xcode only needs to run the script when the input files have changed or the output files are missing. This means dirty builds will be faster when you haven’t rebuilt frameworks with Carthage.

This script works around an App Store submission bug triggered by universal binaries and ensures that necessary bitcode-related files and dSYMs are copied when archiving.

Option 3: Importing Point SDK as a dynamic framework

Point SDK is distributed as a dynamic framework.

A copy of the framework can be downloaded from the Downloads section of your Point Access Dashboard.

A link to this file is also provided in the confirmation email sent after account registration.

Adding the Point SDK Framework to your Xcode project:

  1. In your application’s Target setting, add BDPointSDK.framework to the Embedded Binaries section.

Step 3: Configure Xcode project

  1. Add required iOS SDK frameworks.
    Point SDK requires the usage of some iOS SDK frameworks. Add the following frameworks in the ‘Link Binary with Libraries’ section of your Target’s Build Phases.

    • CoreLocation
    • CoreMotion
    • System Configuration
    • MapKit
    • CoreGraphics
    • UIKit
  2. Go to Build Settings, and set the “Always Embed Swift Standard Libraries” Option to “Yes”.
    NOTE: If BitCode is set to YES, the resulting IPA file size will increase. However, when you submit the app, Apple will recompile it for each platform, and the resulting size installed by app user will be much smaller.
image

Skip steps 3 to 5 if you are integrating via Cocoapods or Carthage

  1. In the Target’s Build Phases tab, Click the “+” button and select “New Run Script Phase”.
    Important:  For your convenience, PointSDK is distributed as one Universal framework to work with both devices and simulators. However, this step is necessary to strip out the simulator slice before submitting to the App Store.
  2. Rename “Run Script” to “Strip Symbols”.
  3. Add the following script:
#/bin/bash
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"
 
# This script loops through the frameworks embedded in the application and
# removes unused architectures.
find "$APP_PATH" -name 'BDPointSDK.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"
 
EXTRACTED_ARCHS=()
 
for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done
 
echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"
 
echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"
 
done

Step 4: Configure info.plist settings

To address differences in hardware capability of iOS devices, Apple has implemented a scheme of string-keys for apps to declare the hardware features it requires. These are stored in a file named info.plist. Running an app on an iOS device with insufficient hardware support may crash the app or result in a degraded experience. Declaring the required hardware features within info.plist allows iOS, and the AppStore, to identify in advance whether a given device should even attempt to download and execute the app.

Further information on this can be found here:

  1. Requiring the Presence of Location Services in an iOS App
  2. info.plist iOS Keys Reference

Follow the steps below to configure the info.plist settings:

1. Device capabilities

Point SDK requires Location Services with GPS accuracy to operate as intended. This should be declared in the info.plist file of any integrating app.

To declare requirements:

  1. Locate the app’s info.plist file in the Supporting Files folder.
  2. Select it once to display the Key/Value pairs in the editor pane.
  3. Find the existing entry titled ‘Required Device Capabilities’, or create one if it does not exist.
  4. Select the (+) icon to add new Item lines containing the following values:
    1. gps
    2. location-services
    3. accelerometer

2. Required background modes

If your app requires “Always” location permission, Point SDK requires access to location updates when the app is in the background. Please follow the steps below to turn on background location updates.

Note: From iOS Point SDK version 1.14.0 and above, if your app requires only “When in use” permission, you may skip this section.

To declare background execution mode:

  1. Locate the app’s info.plist file in the Supporting Files folder of the Xcode project.
  2. Select the file once to display the Key/Value pairs in the editor pane.
  3. Find the entry titled ‘Required background modes‘ or create one if it does not exist.
  4. Select the (+) icon and select from the drop-down list provided: App registers for location updates

3. Required background updates description

Usage description is required when utilizing Location services; this is also provided in info.plist. This message will be prompted to the user when location services are first requested.

  1. Locate the app’s info.plist file in the Supporting Files folder of the Xcode project.
  2. Select the file once to display the Key/Value pairs in the editor pane.
  3. Select the top row ‘Information Property List‘ then click on the ‘+’ symbol to the right to create a new row in the property list.
  4. Select Privacy – Location Always Usage Description as the key, and select the type of String.
  5. Enter a usage description that denotes the use of location services by your app.
    • Example, Your location is used by the app to get you deals closer to you while in the background. As Point SDK supports devices running iOS 10.0 and above, this key is mandatory for backward compatibility.
  6. Click on the ‘+’ symbol to create another new row.
  7. Enter Privacy – Location Always and When In Use Usage Description as the key, and select the type of String.
  8. Enter a usage description that denotes the use of location services by your app.
    • For example: Your location is used by the app to get you deals closer to you while in use or in the background. This key is mandatory to support devices running iOS 11 and above.
    • Note that if your app only requires “When in use” location permission, this key is Optional.
  9. Click on the ‘+’ symbol to create another new row.
  10. Enter Privacy – Location When In Use Usage Description as the key, and select the type of String.
  11. Enter a usage description that denotes the use of Location Services by your app.
    • Example, Your location is used by the app to get you deals closer to you while in use. This key is mandatory to support devices running iOS 11 and above.

4. (Optional) Local Notification Permission Prompt

The Local Notification Permission Prompt is enabled by default to make sure the SDK delivers local notifications for the ‘Message Action’ and/ or ‘URL Action’ set on a Zone through Point Access User Interface.

Optional: To disable the notification permission prompt, the following key should be declared in the info.plist of any integrating app:

1. Locate the app’s info.plist file in the Supporting Files folder.
2. Select the (+) icon to add a new key. BDPointLocalNotificationEnabled, and set the value to Boolean Type.

  1. set the value to YES to enable default notification prompt.
  2. set the value to NO to disable default notification prompt.

Step 5: Integration Checklist

1. Xcode Project Configuration Checklist

The following is a checklist of project configurations that must be made for successful integration of Point SDK into an app.

  • The BDPointSDK.framework files are included in the Embedded Binaries section.
  • The Strip Symbols Run Script Phrase are included in the Build Phase section
  • Always Embed Swift Standard Libraries is set to Yes.
  • The necessary iOS SDK Frameworks are linked to the executable target. These are:
    • CoreLocation
    • CoreMotion
    • SystemConfiguration
    • MapKit
    • CoreGraphics
    • UIKit
  • The following keys are added to the UIRequiredDeviceCapabilities section of the info.plist: (skip this step if it is an already published app and these capabilities did not exist previously – refer to Apple guideline on this here)
    • gps
    • location-services
    • accelerometer
  • The following keys are added to the UIBackgroundModes section of the info.plist:
    • location
  • The following keys are added to the Information Property List in the info.plist:
    • Privacy - Location Always Usage Description, Privacy - Location Always and When In Use Usage Description, Privacy - Location When In Use Usage Description
      • Type: String
      • A description of the usage of location services by your app in the Value field.

2. Source Checklist

The following is a checklist of the source code implementations that will assist in making a successful integration of Point SDK into an app

image

In order to use enhanced restart mode, the following code MUST BE located in AppDelegate. As per iOS lifecycle, during an app restart after termination, the app WILL NOT initialise views.

  • Implement the BDPSessionDelegate and BDPLocationDelegate protocols.
  • Assign an object implementing the protocols to a class (for example, AppDelegate)
    // Swift
    BDLocationManager.instance().sessionDelegate = myDelegateImplementation
    BDLocationManager.instance().locationDelegate = myDelegateImplementation
     
    // Objective C
    BDLocationManager.instance.sessionDelegate = myDelegateImplementation;
    BDLocationManager.instance.locationDelegate = myDelegateImplementation;

3. iOS Caveats

To avoid unexpected behavior in the app, implementations of the following two selectors must be present in the Application Delegate:

// Swift
func applicationDidEnterBackground(_ application: UIApplication)
func applicationWillEnterForeground(_ application: UIApplication)
func applicationWillResignActive(_ application: UIApplication)
 
// Objective C
- (void)applicationDidEnterBackground:
- (void)applicationWillEnterForeground:
- (void)applicationWillResignActive:

This requirement is already satisfied by the empty implementations that Xcode includes as part of the initial UIApplicationDelegate template.

If these are removed or missing for any reason, then an “unrecognized selector sent to instance” error will occur at runtime.


Step 6: Next Steps

Essential Guides:

  • Please refer to the introductory guide to Programming a minimal Point SDK app here.
  • For a list of detailed iOS Features, please refer to the documentation section on iOS – Features
  • For interacting with our Point Access backend, please refer to the documentation on iOS – Session Management

Swift and Objective-C integration examples on GitHub

You can refer to Swift and Objective C integration examples via the link below:

GitHub Examples

API Documentation can be accessed via the link below:

API Documentation

Created by Bluedot DevOps on June 19, 2018

Start the discussion