Overview

Skill Level: Intermediate

Location support is provided in the Mobile App Messaging SDK for iOS apps, by default. If you want to use beacons or geofences in DLA, you can modify the default settings in the MCEConfig.json file to meet the specific requirements of your app.

Prerequisites

iOS 13 changes location permission requests so that uses can not grant “always” permission from in the application. Location “always” permission can be granted one of two ways.

  1. The app could request the “always” permission and the user would be prompted to allow for “while using” permission. Later, the app tries to use location in the background and fails for an unspecified amount of time. Until, at a certain point the user is asked if the app can have “always” location permission (typically while app is not running and within a day of original request).
  2. The app could instruct the user to manually open the settings app, select the app’s settings and then grant the “always” location permission from there. This is a bit of a heavy handed technique and might make users weary of the application in question.

See https://developer.apple.com/videos/play/wwdc2019/705/ and https://developer.apple.com/videos/play/wwdc2019/708/ for more details.
 

Before configuring the Mobile app messaging iOS SDK for geofence and beacon integration, configure locations in the Device Location Awareness (DLA) service. For more information, see Device Location Awareness.

 

About this task

The location section of the MCEConfig.json file enables DLA for beacons and geofences in the  Mobile app messaging SDK for iOS.

Note: If you do not want to use beacons or geofences, remove the corresponding section from the MCEConfig.json file. For example, to remove beacon support, remove ibeacon, or to remove geofence support, remove geofence. If you do not want DLA, remove the entire location section. 

"location": {

  "The location autoInitialize flag can be set to false to delay turning on the location services until desired.": "",
"autoInitialize": true,

"The sync key is only used to customize the iBeacon and Geofence syncing service, it is not required for those features":"",
"sync": {
"Location Sync radius is in meters, default 100km":"",
"syncRadius": 100000,

"Specify how long to wait before syncing again on significant location change in seconds, default 5 minutes":"",
"syncInterval": 300
},

"Please note, the existince of the location key will enable geofence location support, if geofence support is not desired, remove the key":"",
"geofence":{
"choose one of the following values for accuracy: ": ["best", "10m", "100m", "1km", "3km"],
"accuracy": "3km"
},

"Please note, the existince of the ibeacon key will enable iBeacon support, if iBeacon support is not desired, remove the key":"",
"ibeacon": {
"UUID": "SET YOUR IBEACON UUID HERE"
},
},



You can modify the following settings:

syncRadius lets you customize sync services for geofences and beacons. This setting specifies the radius from a site or zone at which the SDK syncs location info with the DLA server. When the mobile device crosses the sync radius, the server downloads a list of site and zone locations to the device for monitoring. A low value causes a full sync more frequently. Sync radius is different than the geofence radius that is specified in the DLA UI. The geofence radius specifies the radius at which a location event is triggered. The default value for syncRadius is 100000 meters (100 km).

syncInterval lets you customize sync services for geofences and beacons. syncInterval specifies the number of seconds to wait before syncing after a significant location change. The default value for syncInterval is 300 seconds (5 minutes). The minimum allowed value is 300 seconds. If you try to set the syncInterval to a value that is lower than 300 seconds, the SDK resets to 300 seconds. 

Accuracy represents the accuracy assigned to the location manager in the SDK. A higher accuracy setting uses more battery but delivers more accurate location information. A lower accuracy setting uses less battery but delivers less accurate location information. Available accuracy levels include best, 10 m, 100 m, 1 km, and the default 3 km.

UUID specifies a UUID for the beacons that you are tracking in locations. In DLA, beacons are identified by a hierarchical combination of a UUID, a major number, and a minor number, where UUID represents a group of associated beacons, such as the beacons associated with an organization.

autoInitialize lets you delay activation of location services until you determine that the user wants locations services. When you set this value to false, location services are delayed from starting until the SDK’s manualLocationInitialization method is called. This value is set to true, by default.¬†

If you are using either geofences or beacons, configure locations by performing these steps:

Step-by-step

  1. In the Project Settings screen for the target app, turn on the Background Modes capability in the Capabilities tab, and then enable Location updates and Background fetch.

  2. To use location services, add the NSLocation key and string to the Info.plist file for the app project.

    NSLocationAlwaysUsageDescription requests permission from the mobile app user to use location services when your app is running in the background. Because Apple recently started prohibiting apps from sharing location data with third parties when explicit user consent is absent, you might want to use NSLocationAlwaysUsageDescription to tell users how the SDK uses location data. The SDK stores location data locally on the device and when a geofence event is triggered, the event is sent to MCE, which a third party. The event does not contain raw location data. To convince users to grant permission, you might also want to let them know that battery usage is minimal when location sharing is enabled.

    <key>NSLocationAlwaysUsageDescription</key>
    <string>The SDK stores location data locally on the device and
    when a geofence event is triggered, the event is sent to MCE,
    which a third party. The event does not contain raw location data.
    Battery usage is minimal when sharing location.</string>

    Note: You might also consider using the NSLocationWhenInUseUsageDescription key to allow location access only when the app is in use.

     

    iOS 11 (and later)

    For iOS 11, you must add both the NSLocationWhenInUseUsageDescription key and the NSLocationAlwaysAndWhenInUseUsageDescription key to the Info.plist file.

    <key>NSLocationAlwaysUsageDescription</key>
    <string>The SDK stores location data locally on the device and
    when a geofence event is triggered, the event is sent to MCE,
    which a third party. The event does not contain raw location data.
    Battery usage is minimal when sharing location.</string>
    <key>NSLocationWhenInUseUsageDescription</key>
    <string>The SDK stores location data locally on the device and
    when a geofence event is triggered, the event is sent to MCE,
    which a third party. The event does not contain raw location data.
    Battery usage is minimal when sharing location.</string>
    <key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
    <string>The SDK stores location data locally on the device and
    when a geofence event is triggered, the event is sent to MCE,
    which a third party. The event does not contain raw location data.
    Battery usage is minimal when sharing location.</string>

     

  3. (Optional) If you want to be notified when a geofence or beacon event occurs, use NSNotification:

    Beacon entry:

      [[NSNotificationCenter defaultCenter] addObserverForName:EnteredBeacon object:nil queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification * _Nonnull note) {
    // use note.userInfo[@"minor"]// use note.userInfo[@"major"] }];

    Beacon exit:

      [[NSNotificationCenter defaultCenter] addObserverForName:ExitedBeacon object:nil queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification * _Nonnull note) {
    // use note.userInfo[@"minor"]// use note.userInfo[@"major"] }];

    Geofence entry:

      [[NSNotificationCenter defaultCenter] addObserverForName: EnteredGeofence object:nil queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification * _Nonnull note) {
    // use note.userInfo[@"region"].center
    // use note.userInfo[@"region"].radius
    }];

     Geofence exit:

      [[NSNotificationCenter defaultCenter] addObserverForName: ExitedGeofence object:nil queue:NSOperationQueue.mainQueue usingBlock:^(NSNotification * _Nonnull note) {
    // use note.userInfo[@"region"].center
    // use note.userInfo[@"region"].radius
    }];

Expected outcome

After you set up locations in the SDK, location Universal Behavior events are available in Acoustic Campaign queries and programs for iOS apps. For information about configuring location Universal Behavior events in Acoustic Campaign, see Configuring queries and programs for location-based mobile app messaging.

For information about other mobile app message advanced features, see the Documentation.

Go Back to the Mobile App Messaging home page.

Join The Discussion

Your email address will not be published. Required fields are marked *