nav_title | article_title | platform | page_order | description | Tool | |
---|---|---|---|---|---|---|
Locations and Geofences |
Location and Geofences for iOS |
Swift |
4 |
This reference article covers how to implement locations and geofences in your for the Swift SDK. |
|
This article covers setting up geofences for your iOS SDK integration. Geofences are only available in select Braze packages. Reach out to your Braze customer success manager to get started.
At the core of Braze’s real-time location offering is the concept of a geofence. A geofence is a virtual geographic area, represented as latitude and longitude combined with a radius, forming a circle around a specific global position.
{% alert important %} As of iOS 14, geofences do not work reliably for users who choose to give their approximate location permission. {% endalert %}
To fully utilize our geofence syncing strategy, you must have silent push notifications enabled in addition to completing the standard push integration.
Braze location services must be enabled through the SDK. They are not enabled by default.
Enable geofences by setting location.geofencesEnabled
to true
on the configuration
object that initializes theBraze
instance. Other location
configuration options can be found here.
{% tabs %}
{% tab swift %}
let configuration = Braze.Configuration(
apiKey: "<BRAZE_API_KEY>",
endpoint: "<BRAZE_ENDPOINT>"
)
configuration.location.brazeLocationProvider = BrazeLocationProvider()
configuration.location.automaticLocationCollection = true
configuration.location.geofencesEnabled = true
configuration.location.automaticGeofenceRequests = true
// Configurations for background geofence reporting with `When In Use` authorization.
configuration.location.allowBackgroundGeofenceUpdates = true
configuration.location.distanceFilter = 8000
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze
{% endtab %} {% tab OBJECTIVE-C %}
BRZConfiguration *configuration =
[[BRZConfiguration alloc] initWithApiKey:brazeApiKey
endpoint:brazeEndpoint];
configuration.logger.level = BRZLoggerLevelInfo;
configuration.location.brazeLocationProvider = [[BrazeLocationProvider alloc] init];
configuration.location.automaticLocationCollection = YES;
configuration.location.geofencesEnabled = YES;
configuration.location.automaticGeofenceRequests = YES;
// Configurations for background geofence reporting with `When In Use` authorization.
configuration.location.allowBackgroundGeofenceUpdates = YES;
configuration.location.distanceFilter = 8000;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;
{% endtab %} {% endtabs %}
By default, geofences are only monitored if your app is in the foreground, or it has Always
authorization (which monitors all application states).
However, you can choose to monitor geofence events when your app is in the background or when it has When In Use
authorization by adding the Background Mode -> Location updates
capability to your Xcode project and enabling allowBackgroundGeofenceUpdates
. This let's Braze extend your app's "in use" status by continuously monitoring location updates.
allowBackgroundGeofenceUpdates
only works when your app is in the background. When it re-opens, it's existing background processes are paused, so foreground processes can be prioritized instead.
{% alert important %}
To prevent battery drain and rate limiting, be sure to configure distanceFilter
to a value that meets your app's specific needs. Setting distanceFilter
to a higher value prevents your app from requesting your user's location too frequently.
{% endalert %}
Braze syncs geofences to devices using background push notifications. Follow the ignoring silent push article to ensure that your application does not take any unwanted actions upon receiving Braze geofence sync notifications.
Add the key NSLocationAlwaysUsageDescription
, NSLocationAlwaysAndWhenInUseUsageDescription
or NSLocationWhenInUseUsageDescription
to your info.plist
with a String
value that has a description of why your application needs to track location.
This description will be shown when the system location prompt requests authorization and should clearly explain the benefits of location tracking to your users.
When requesting authorization from a user, you can request When In Use
or Always
authorization.
To request When In Use
authorization, use the requestWhenInUseAuthorization()
method:
{% tabs %} {% tab swift %}
var locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()
{% endtab %}
{% tab OBJECTIVE-C %}
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
[locationManager requestWhenInUseAuthorization];
{% endtab %} {% endtabs %}
By default, requestAlwaysAuthorization()
only grants your app When In Use
authorization and will re-prompt your user for Always
authorization after some time has passed. However, you can choose to immediately prompt your user by first calling requestWhenInUseAuthorization()
, then calling requestAlwaysAuthorization()
after receiving your initial When In Use
authorization.
{% alert important %}
You can only immediately prompt for Always
authorization a single time.
{% endalert %}
{% tabs %} {% tab swift %}
var locationManager = CLLocationManager()
locationManager.requestAlwaysAuthorization()
{% endtab %}
{% tab OBJECTIVE-C %}
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
[locationManager requestAlwaysAuthorization];
{% endtab %} {% endtabs %}
iOS only allows up to 20 geofences to be stored for a given app. With geofences enabled, Braze will use up some of these 20 available slots. To prevent accidental or unwanted disruption to other geofence-related functionality in your app, location geofences must be enabled for individual apps on the dashboard. For our location services to work correctly, check that your app is not using all available geofence spots.
There are two ways to enable geofences for a particular app: from the Locations page or from the Manage Settings page.
Enable geofences on the Locations page of the dashboard.
- Go to Audience > Locations. {% alert note %} If you are using the older navigation, you can find Locations under Engagement. {% endalert %}
{:start="2"} 2. The number of apps in your workspace that currently have geofences enabled is displayed beneath the map, for example: 0 of 1 Apps with Geofences enabled. Click this text. 3. Select the app to enable geofences. Click Done. ![The geofence options on the Braze locations page.]({% image_buster /assets/img_archive/enable-geofences-locations-page.png %})
Enable geofences from your app's settings.
- Go to Settings > App Settings. {% alert note %} If you are using the older navigation, you can find geofences at Manage Settings > Settings. {% endalert %}
{:start="2"} 2. Select the app for which you wish to enable geofences. 3. Select the Geofences Enabled checkbox. Click Save.
![The geofence checkbox located on the Braze settings pages.]({% image_buster /assets/img_archive/enable-geofences-app-settings-page.png %})
You can disable automatic geofence requests in your configuration
object passed to init(configuration)
. Set automaticGeofenceRequests
to false
. For example:
{% tabs %} {% tab swift %}
let configuration = Braze.Configuration(
apiKey: "{BRAZE_API_KEY}",
endpoint: "{BRAZE_ENDPOINT}"
)
configuration.automaticGeofencesRequest = false
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze
{% endtab %} {% tab OBJECTIVE-C %}
BRZConfiguration *configuration =
[[BRZConfiguration alloc] initWithApiKey:{BRAZE_API_KEY}
endpoint:{BRAZE_ENDPOINT}];
configuration.automaticGeofencesRequest = NO;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;
{% endtab %} {% endtabs %}
If you choose to use this option, you will need to manually request geofences for the feature to work.
When the Braze SDK requests geofences to monitor from the backend, it reports the user's current location and receives geofences that are determined to be optimally relevant based on the location reported. There is a rate limit of one geofence refresh per session.
To control the location that the SDK reports for the purposes of receiving the most relevant geofences, you can manually request geofences by providing the latitude and longitude of a location. It is recommended to disable automatic geofence requests when using this method. To do so, use the following code:
{% tabs %} {% tab swift %}
AppDelegate.braze?.requestGeofences(latitude: latitude, longitude: longitude)
{% endtab %} {% tab OBJECTIVE-C %}
[AppDelegate.braze requestGeofencesWithLatitude:latitude
longitude:longitude];
{% endtab %} {% endtabs %}