Last modified November 12, 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.

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.

Cordova

The SwrveGeoSDK is a Cordova Plugin called cordova-plugin-swrvegeo that gets packaged with every release but not directly imported along with SwrvePlugin. To add it manually, complete the following steps.

Integration steps

Step 1: Install the standard SwrvePlugin as per the documentation. For more information, see the Cordova integration guide.

Step 2: Add the SwrveGeoSDK plugin:

Step 3: In your Config.xml, add the following:

Add the Geo API Key to the preferences of the platforms you want to support. This informs our hooks to include a geo initialization as part of your platforms.

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

Step 4: In the Config.xml of your iOS platform, make sure you have values for the following keys:

Note: The descriptions should be something similar to this:

  • 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 SwrveGeoPlugin requires access to location updates, including when the app is running in the background. In your Config.xml, you must declare the following background execution modes:

Step 6: To delay the request for location permission, set the swrve.geoDelayStart boolean in Config.xml before generating your platform.

Then at the opportune time, call window.plugins.swrvegeo.start() when users grant permission.

You can also call window.plugins.swrvegeo.stop() to turn off tracking if required.


Custom filtering

To filter notifications or modify their content based on custom properties, you can set a custom filter when initializing the Geo SDK. For Cordova integrations, refer to the native SDK method if you want to use custom filtering.

Android

iOS


Next steps