Locations and geofences

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.

Step 1: Enable background push

To fully utilize our geofence syncing strategy, you must have silent push notifications enabled in addition to completing the standard push integration.

Step 2: Enable Braze location services

Braze location services must be enabled through the SDK. They are not enabled by default.

Step 3: Enable geofences

Enable geofences by setting location.geofencesEnabled to true on the configuration object that initializes theBraze instance. Other location configuration options can be found here.

• swift
• OBJECTIVE-C

1
2
3
4
5
6
7
8
9
10
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
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
8
9
10
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;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

Step 4: Check for Braze background push

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’s geofence sync notifications.

Step 5: Add location usage description strings to your Info.plist

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.

Step 6: Request authorization from the user

The geofences feature is only functional while Always location authorization or AuthorizedWhenInUse with the Background Mode -> Location updates capability enabled is granted.

To request for Always or AuthorizedWhenInUse location authorization, use the following code:

• swift
• OBJECTIVE-C

1
2
3
4
var locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()
// or
locationManager.requestAlwaysAuthorization()

1
2
3
4
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
[locationManager requestWhenInUseAuthorization];
// or
[locationManager requestAlwaysAuthorization];

Step 7: Enable geofences on the dashboard

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 Braze’s location services to work correctly, you should also ensure 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 from the Locations page

Enable geofences on the Locations page of the dashboard.

1. Go to Audience > Locations.

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.

Enable geofences from the Manage Settings page

Enable geofences from your app’s settings.

1. Go to Settings > App Settings.

2. Select the app for which you wish to enable geofences.
3. Select the Geofences Enabled checkbox. Click Save.

Disabling automatic geofence requests

You can disable automatic geofence requests in your configuration object passed to [init(configuration)][4]. Set automaticGeofenceRequests to false. For example:

• swift
• OBJECTIVE-C

1
2
3
4
5
6
7
let configuration = Braze.Configuration(
  apiKey: "{BRAZE_API_KEY}",
  endpoint: "{BRAZE_ENDPOINT}"
)
configuration.automaticGeofencesRequest = false
let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
BRZConfiguration *configuration =
  [[BRZConfiguration alloc] initWithApiKey:{BRAZE_API_KEY}
                                  endpoint:{BRAZE_ENDPOINT}];
configuration.automaticGeofencesRequest = NO;
Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

If you choose to use this option, you will need to manually request geofences for the feature to work.

Manually requesting geofences

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:

• swift
• OBJECTIVE-C

1
AppDelegate.braze?.requestGeofences(latitude: latitude, longitude: longitude)

1
2
[AppDelegate.braze requestGeofencesWithLatitude:latitude
                                      longitude:longitude];