Implement Location Messaging on iOS

The MobilePush iOS SDK uses location capabilities of mobile devices to trigger location-based notifications. The SDK caches geofence messages and displays them on user devices whenever users cross a geofence boundary. To implement location-based messaging on your app using the MobilePush SDK, you must obtain user permission for location services.

To successfully use this functionality, your Marketing Cloud Engagement admin must enable your account with access to MobilePush and Location Services.

Starting with iOS 14, users have the option to use approximate instead of precise location. Geofences and beacons aren't triggered for users who choose to provide approximate location permission. For more information, see Apple's documentation on Accuracy Authorization.

To work, location messaging and beacon support in iOS versions 14 and above require precise location authorization. The MobilePush SDK sends only precise location updates to Marketing Cloud, while ignoring approximate location updates from user devices.

If location is enabled in your MobilePush SDK configuration, you can use Engagement location messaging by calling a single method. You can enable location in your SDK configuration using the setLocationEnabled method of the PushConfigBuilder class.

Apple also requires that you add the following keys to your Info.plist file to enable location services.

  • NSLocationAlwaysUsageDescription
  • NSLocationAlwaysAndWhenInUseUsageDescription
  • NSLocationWhenInUseUsageDescription

For more information, see Choosing the Location Services Authorization to Request on Apple's Developer Documentation site.

The MobilePush SDK requires “Always” permissions for full geofence and beacon functionality. An application doesn't receive location messages if an app user selects “When-in-use authorization”.

When your application is ready to enable location features, including geofence and beacon messaging, call the SDK's startWatchingLocation method to start watching location.

The MarketingCloudSDK+Location.h header file details additional methods to get information about location and control the frameworks behavior.

MobilePush prevents the app from displaying a geofence message with an empty alert. If you include AMPscript in your message that returns no content or an empty string, the mobile app doesn't display that message.

We enable beacon support when you implement the location requirements on this page.

To range for beacons in the background, add an entry to your app’s Info.plist. This permission ensures that your app can range for beacons when your app is in the background or suspended.

MobilePush prevents the app from displaying a beacon message with an empty alert. If you include AMPscript in your message that returns no content or an empty string, the mobile app doesn't display that message.

To understand how beacons behave in different situations, see Beacon Behavior.

If you create your own CLLocationManager object, we can’t guarantee that features of our SDK work as intended.

If you have enabled notifications using MarketingCloudSDK and have called mp.startWatchingLocation(), you can access the device’s last known location using the SDK.

Normally, the app downloads new regions and messages as the device moves more than 5 kilometers from the last location and download of this data. However, if your app serves customers who spend much time within a single 5-K radius, consider adding the ability to do a background refresh of regions and messages. Since Apple controls when this background refresh takes place, we can’t guarantee when the refresh occurs. However, Apple allows the SDK to download new regions and messages for those times your customer spends a considerable amount of time in a single 5-K region.

In your Info.plist, implement this key to enable this function. We require “App downloads content from the network” to perform a Background App Refresh periodically to refresh geofences and beacons.

In your Info.plist, add keys under UIBackgroundModes:

  • fetch : We require “App downloads content from the network” to perform a background app refresh periodically to refresh geofences and beacons.
  • location : We require “App registers for location updates” to enable location in the MarketingCloudSDK and to range for beacons in the background.

In your application delegate method -application:didFinishLaunchingWithOptions:, implement this code:

Implement the handler for this functionality in your application delegate class:

See MarketingCloudSDK+Base.h for more information about this method.

You can deliver location messages to a subset of your MobilePush audience by using the MobilePush SDK. When a mobile device breaks a geofence or comes into proximity of a Bluetooth beacon, the SDK triggers a callback to your mobile app. This callback is used to evaluate whether to show the message.

Your app can apply criteria, including information within the MobilePush message itself, to determine whether to show the message. Here are some use cases.

  • Show the message if the user’s my store location is within the geofence region.
  • Show the message if the user has items in the app shopping cart and if the message has an “abandonedCart”:”true” custom key.
  • Show the message only when the store is open based on the app’s store location list and the region and local time.
  • Don’t show messages if the user isn’t logged in to the app.
  • Show specific messages based on the user’s customer profile. For example, customers who are coffee lovers get messages about coffee, but customers who prefer pastry receive a message to “add a coffee” when they’re in the shop.

MarketingCloudSDK+Location.h