Last modified August 29, 2019 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 CSM at support@swrve.com. They will enable Geoplaces in your Swrve dashboard and give you your Geo API key.
  • The latest version of the Geo SDK add-on requires a minimum native Swrve SDK version 6.2.
  • For iOS, Swift 5.0 is currently not supported. Speak to your CSM at support@swrve.com for further information.

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.

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. To facilitate this, 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 Samples folder. 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.

The SwrveGeoSDK will automatically request location permission upon install. See step 8 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 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

Note: To prevent issues with updating your app on devices that do not support GPS (for example, wi-fi only iPads), skip this step if your app is already published to the App Store and doesn’t already include these capabilities. For more information, see Apple’s iOS Device Compatibility Reference.

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.

Step 8: 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