Last modified March 9, 2016 by Shelly Wolfe

Location-Based

Swrve’s Location-based Campaigns enable you to send targeted, geo-triggered notifications to your app users. To make use of this feature, you must integrate the Location SDK alongside the general Swrve SDK for your platform. This guide explains how to integrate the Location SDK for iOS, Android and Unity.


Prerequisites

Request a copy of the Location SDK for your app platform from your Customer Success Manager at support@swrve.com. They will enable Locations in your Swrve dashboard and provide a public token for the Location SDK, which is used in the plotconfig.json file.


Integration Instructions

Click one of the platform tabs below for integration instructions.

Android

The Swrve Location Android SDK is an Android Library project in the form of an aar file (swrve-location-X.X.X.aar) that contains the Swrve Location code and is integrated locally as a Gradle dependency alongside the standard Swrve Android SDK.

Integration Steps

Step 1: Drop the aar file into a directory called libs in the Android module in Android Studio.

Step 2: Integrate the Locations SDK into your Gradle build system by adding the following two details to the build.gradle file:

  1. At the top of the build.gradle file:
  2. Add to dependencies (replace X.X.X with the latest native Android SDK and Locations SDK version number):

Step 3: Add a file called plotconfig.json to your assets directory in Android Studio. For example:

where token is the Locations SDK public token provided by your CSM.

Step 4: In the Application class where the SwrveSDK instance is created, initialize the general Swrve SDK as per normal. Replace <app_id> and <api_key> with your app ID and API key. For example:

Step 5: In the Main Activity class of the app, initialize the Location SDK in the onCreate method. For example:

The Location SDK integration is complete. For information on creating location-based campaigns, see Creating Location-Based Campaigns.

iOS

The Swrve Location iOS SDK is a local CocoaPod that contains the Swrve Location code (with a dependency on the remote iOS Plot Projects CocoaPod) and is integrated locally alongside the standard Swrve iOS SDK.

The SwrveLocationSDK package includes a Samples folder that provides basic examples of how to integrate the Location SDK. Note: Set the Podfile to remote and set both the Swrve Details and plotconfig.json file before you run the project.

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 line to your Podfile:

Step 3: In your Xcode build target, select the Info tab. Under Custom iOS Target Properties, right-click a row, select Add row and add each of 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.” (This key is added in XCode 9. If you’re using XCode 8, you can add the key yourself.)
With the release of iOS 11, the above location permission keys and descriptions are required in order for new users who install your app to give permission for location services. Users who already installed your app prior to upgrading to iOS 11 will not be affected.

Step 4: In the header (.h) file of your AppDelegate, add PlotDelegate to the implemented protocols. For example:

Step 5: In Appdelegate.m, implement the following:

  1. Import SwrvePlot:
  2. Directly after the Swrve SDK is initialized, initialize Plot:
  3. Add the following:

Step 6: In your root directory, add a file called plotconfig.json. For example:

where token is the Location SDK public token provided by your CSM.

The Location SDK integration is complete. For information on creating location-based campaigns, see Creating Location-Based Campaigns.

iOS using Swift

The SwrveLocationSDK package includes a Samples folder that provides basic examples of how to integrate the Location SDK. Note: Set the Podfile to remote and set both the Swrve Details and plotconfig.json file before you run the project.

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 line to your Podfile:

Step 3: In your Xcode build target, select the Info tab. Under Custom iOS Target Properties, right-click a row, select Add row and add each of 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.” (This key is added in XCode 9. If you’re using XCode 8, you can add the key yourself.)
With the release of iOS 11, the above location permission keys and descriptions are required in order for new users who install your app to give permission for location services. Users who already installed your app prior to upgrading to iOS 11 will not be affected.

Step 4: Add the PlotDelegate to your AppDelegate.swift as outlined below:

Step 5: In Appdelegate.swift, implement the following:

  1. Import the Swrve SDK:
  2. Directly after the Swrve SDK is initialized, initialize Plot:
  3. Add the following:

Step 6: In your root directory, add a file called plotconfig.json. For example:

where token is the Location SDK public token provided by your CSM.

The Location SDK integration is complete. For information on creating location-based campaigns, see Creating Location-Based Campaigns.

Unity

The Swrve Location Unity SDK is a Unity package (swrveUnityLocationSDK.unityPackage) that contains the Swrve Location code and is integrated locally alongside the standard Swrve Unity SDK.

Integration Steps

Step 1: Open your project in Unity and import swrveUnityLocationSDK.unityPackage.

Step 2: In Assets/Plugins/Android/SwrveLocationSDK, create a folder called assets and add the plotconfig.json file to it.

Step 3: In the Unity editor, under Config, select Location Enabled and Location Autostart.

locations_unity

Alternatively, to configure the value directly in the code, use the following:

Build Process

Navigate to Assets > Swrve > Editor, and in the postprocess.json config file, edit the following keys:

  • PlotToken – replace REPLACEME with the Location SDK public token.
  • NSLocationAlwaysUsageDescription – enter a value that you want to display for the permissions dialog. For example, “Your location is used to instantly inform you when you are near a location that is of interest to you.”

Android

Remember to run the Swrve -> Android Prebuild tool in AndroidManifests / SwrveBuildComponent.AndroidPrebuild() before building your project in Unity.

The Location SDK integration is complete. For information on creating location-based campaigns, see Creating Location-Based Campaigns.


Custom Location Filtering

The Swrve Locations SDK now enables you to implement custom filters that give final sign-off to a notification before displaying it to a customer. Examples of these final checks include:

  • Confirm the user’s current time is within the opening hours of a restaurant geofence.
  • Personalize the notification text with your own user properties.
  • Add tracking codes to the deeplink.

When the user triggers a geofence, the SDK returns a list of all the eligible campaigns for that location. If you want to exclude certain campaigns from the list, the custom filter acts to remove them and return the altered list at the end of the method. In the first example above, you might want to confirm the user’s current time and only display the notification if it is within the opening hours of a restaurant geofence they just triggered. To remove all notifications past a certain time, you would first check the time. If the user’s current time was past that specified time, the app would return an empty list and the notification would not be displayed.

For details on how to include custom location filtering, click a tab below for the relevant platform.

iOS

Step 1: Make the same class that’s a delegate of PlotDelegate also a delegate of SwrveLocationCustomFilterDelegate.

Step 2: Implement the function filterNotifications from the delegate class SwrveLocationCustomFilterDelegate.

Step 3: Change the SwrvePlot method in PlotFilterNotifications to

iOS using Swift

Step 1: Add SwrveLocationCustomFilterDelegate to your App Delegate

Step 2: Change PlotFilterNotifications

Step 3: Add SwrveLocationCustomFilterDelegate Method. The sample code below (in Swift 3) shows one example of how to do this, however you’re free to use your own format.

Android

Implement interface SwrveLocationCustomFilter and pass it to SwrvePlot after SwrveSDK.createInstance is called in the main Application (not the Activity).

Unity

Due to the nature in which custom filtering methods are accessed and referenced, it is not possible at this time to make a C# method that is accessed from the native layer at runtime.

To integrate custom location filters in a Unity project, after you export the project, complete the steps outlined on the native iOS and Android tabs.


Next Steps