Last modified April 28, 2020 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 SDK 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 CSM at support@swrve.com. They will enable Geoplaces in your Swrve dashboard.
  • The latest version of the Geo SDK add-on requires a minimum iOS Swrve SDK 6.2 and Android Swrve SDK 7.0.
  • The Android Geo SDK add-on uses Android’s native geofencing APIs and thus requires the following:
    • Google Play Services to be installed
    • Wi-fi location scanning to be enabled
    • Location services to be enabled
    • Background location permission to be granted (API level 29). This is the “Allow all the time” permission. The “Allow only while using the app” permission is not supported.
  • The iOS Geo SDK add-on uses iOS’s native region monitoring and Significant Location Changes APIs and thus requires the following:
    • Location services to be enabled
    • “Always on” location permission to be granted
  • The Swrve Geo SDK will silently do nothing on devices that don’t have the appropriate device capabilities. Both iOS and Android platforms can restrict installations of an app to devices that only support these capabilities. If you’d like to restrict your app to be only installed on those devices please, speak to your CSM.

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 following dependencies to your app build.gradle file:

Step 2: 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. Otherwise, if the app hasn’t been granted location permission, the initialize method will silently do nothing. To request the permission at an opportune moment, set the DelayStart property of the SwrveGeoConfig to true and pass this as a parameter into the init method in Step 3. Then decide which Activity/Fragment to request location permission and call SwrveGeoSDK.start when users grant permission. For an example of delay start functionality, see the SwrveGeoSDK sample project, which is available from your CSM. For best practices around requesting permissions, see the Android article, Request permissions at runtime appropriately.

Step 3: In the Application class where the SwrveSDK instance is created, initialize SwrveGeoSDK directly after you initialize SwrveSDK. For better performance on devices running Android Oreo and above, we also highly recommend setting the foreground notification in the SwrveGeoConfig properties. Provide some value in the content of the foreground notification that makes it easier for users to opt in to allowing this.

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

Step 4: Optionally, update the foreground notification with more relevant content.

iOS

The SwrveGeoSDK is a CocoaPod and is integrated alongside the standard Swrve iOS SDK.

The SwrveGeoSDK package includes a Sample project that provides a basic example 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.

The SwrveGeoSDK will automatically request location permission upon install. See Step 6 to delay this to an opportune time.

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 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 6: To facilitate delaying the request for location permission, set the DelayStart property of the SwrveGeoConfig to YES and pass this as a parameter into the init method in Step 3. Then at the opportune time call [SwrveGeoSDK start] when users grant permission. For an example of delay start functionality, see the Sample folder.


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