Last modified September 3, 2018 by Shelly Wolfe

Swrve Geo SDK

Swrve’s Geo SDK add-on lets you send targeted, geo-triggered notifications to your app users. To use this feature, you must integrate the Swrve Geo Sample project alongside the general Swrve SDK for your platform. This guide explains how to integrate the Geo SDK add-on for iOS and Android.


Requirements

  • Request a copy of the Swrve Geo Sample project for your app platform from your Customer Success Manager at support@swrve.com. They will enable Geoplaces in your Swrve dashboard and give you your Geo API key.
  • The Geo SDK add-on requires a minimum of the native Swrve SDK version 5.3.
  • For iOS, use a minimum of Xcode version 9.3.

Integration instructions

Select one of the platform tabs below for integration instructions.

Android

The SwrveGeoSDK add-on is an Android library project and is integrated as a separate Gradle dependency alongside the standard Swrve Android SDK.

The SwrveGeoSDK package includes a Samples folder that provides basic examples of how to integrate the Geo SDK add-on.

Integration steps

Step 1: Add the repositories to your root build.gradle file:

Step 2: Add the following dependencies to your app build.gradle file:

Step 3: In the Application class where the SwrveSDK instance is created, initialize SwrveGeoSDK directly after you initialize SwrveSDK. However, you should check the location permission first.

Replace <app_id> and <api_key> with your app ID and API key. Replace <geo_api_key> with your Geo API key.

You also need to include the following parameters in SwrveGeoSDK.init:

  • context – a regular Android context.
  • foregroundNotification – to operate on Android Oreo and above, the app must provide and display a persistent foreground notification.

The app must also request location permission (see step 4). If the app has not been granted the location permission, then the initialize method will silently do nothing.

Step 4: Choose when and where to ask for location permission.

For Android Marshmallow and above, the app requires location permission from the user for the SwrveGeoSDK to initialize. Decide where and when this is done from an Activity or Fragment. The Geo SDK Sample project includes the SwrveGeoSDK.requiresLocationPermissionRequest method to help the app decide if the location permission request is required. For an example, see the Geo SDK Sample project. For best practices around requesting permissions, see the Android  article, Request permissions at runtime appropriately.

iOS

The SwrveGeoSDK is a CocoaPod with a dependency on the iOS Bluedot CocoaPod and is integrated alongside the standard Swrve iOS SDK.

The SwrveGeoSDK package includes a Samples folder that provides basic examples of how to integrate the Geo SDK add-on.

Integration steps

Step 1: Install the standard Swrve iOS SDK as per the documentation for installing from CocoaPods. For more information, see the iOS Integration Guide.

Step 2: Add the following dependencies to your Podfile:

The SwrveGeoSDK requires that you have use_frameworks! in your CocoaPods.

Step 3: In your AppDelegate, implement the following:

  1. Import the SwrveGeoSDK framework.
  2. Initialize SwrveGeoSDK directly after initializing SwrveSDK. Replace <app_id> and <api_key> with your app ID and API key. Replace <geo_api_key> and with your Geo API key.

Step 4: In your Info.plist, make sure you have values for the following keys:

  • NSLocationAlwaysUsageDescription – enter a value similar to “Your location is used to instantly inform you when you are near a location that is of interest to you.”
  • NSLocationWhenInUseUsageDescription – enter a value similar to “Your location is used to instantly inform you when you are near a location that is of interest to you while the app is in use.”
  • NSLocationAlwaysAndWhenInUseUsageDescription – enter a value similar to “Your location is used to instantly inform you when you are near a location that is of interest to you.”

Step 5: The SwrveGeoSDK requires Location Services with GPS accuracy to operate as intended. In your Info.plist, declare the following requirements:

  1. In the Supporting Files folder for your app, select the Info.plist to display the Key/Value fields in the editor pane.
  2. Locate the Required Device Capabilities key, or create one if it does not exist.
  3. Next to the the Required Device Capabilities key, click add (+) to add new items with the following string values:
    • gps
    • location-services
    • accelerometer

Step 6: The SwrveGeoSDK requires access to location updates, including when the app is running in the background. In your Info.plist, you must declare the background execution mode:

  1. In the Supporting Files folder for your app, select the Info.plist to display the Key/Value fields in the editor pane.
  2. Locate the Required background modes key, or create one if it does not exist.
  3. Next to Required background modes, click add (+) and select App registers for location updates from the list.

Step 7: Under your app Targets, select the Build Settings tab, and set Always Embed Swift Standard Libraries to Yes.


Custom filtering

To filter notifications or modify their content based on custom properties, you can set a custom filter when initializing the Geo SDK.

Android

iOS


Next steps