Geofences

Prerequisites

Before you can use this feature, you’ll need to integrate the Swift Braze SDK.

Setting up geofences

Step 1: Enable in Braze

You can enable geofences for your app in one of the following places:

• locations
• app settings

Step 2: Enable your app’s location services

By default, Braze location services are not enabled. To enable them in your app, complete the following steps. For a step-by-step tutorial, see Tutorial: Braze Locations and Geofences.

Step 2.1: Add the BrazeLocation module

In Xcode, open the General tab. Under Frameworks, Libraries, and Embedded Content, add the BrazeLocation module.

Step 2.2: Update your Info.plist

In your info.plist, assign a String value to one of the following keys that describes why your application needs to track location. This string will be shown when your users are prompted for location services, so be sure to clearly explain the value of enabling this feature for your app.

• NSLocationAlwaysAndWhenInUseUsageDescription
• NSLocationWhenInUseUsageDescription

Step 3: Enable geofences in your code

In your app’s code, enable geofences by setting location.geofencesEnabled to true on the configuration object that initializes the Braze instance. For other location configuration options, see Braze Swift SDK reference.

• swift
• objective-c

1
2
3
4
5
6
7
8
9
10
11
12
13
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

// Additional configuration customization...

let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
8
9
10
11
12
13
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;

// Additional configuration customization...

Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

Step 3.1: Enable background reporting (optional)

By default, geofence events are only monitored if your app is in the foreground or has Always authorization, which monitors all application states.

However, you can choose to also monitor geofence events if your app is in the background or has When In Use authorization.

To monitor these additional geofence events, open your Xcode project, then go to Signing & Capabilities. Under Background Modes, check Location updates.

Next, enable allowBackgroundGeofenceUpdates in your app’s code. This lets Braze extend your app’s “When In Use” status by continuously monitoring location updates. This setting only works when your app is in the background. When the app re-opens, all existing background processes are paused and foreground processes are prioritized instead.

• swift
• objective-c

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
let configuration = Braze.Configuration(
  apiKey: "<BRAZE_API_KEY>",
  endpoint: "<BRAZE_ENDPOINT>"
)

// Additional configuration customization...

// Enable background geofence reporting with `When In Use` authorization.
configuration.location.allowBackgroundGeofenceUpdates = true

// Determines the number of meters required to trigger a new location update.
configuration.location.distanceFilter = 8000

let braze = Braze(configuration: configuration)
AppDelegate.braze = braze

1
2
3
4
5
6
7
8
9
10
11
12
13
14
BRZConfiguration *configuration =
    [[BRZConfiguration alloc] initWithApiKey:brazeApiKey
                                    endpoint:brazeEndpoint];

// Additional configuration customization...

// Enable background geofence reporting with `When In Use` authorization.
configuration.location.allowBackgroundGeofenceUpdates = YES;

// Determines the number of meters required to trigger a new location update.
configuration.location.distanceFilter = 8000;

Braze *braze = [[Braze alloc] initWithConfiguration:configuration];
AppDelegate.braze = braze;

Step 4: Request authorization

When requesting authorization from a user, request either When In Use or Always authorization.

• when in use
• always

1
2
var locationManager = CLLocationManager()
locationManager.requestWhenInUseAuthorization()

1
2
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
[locationManager requestWhenInUseAuthorization];

1
2
var locationManager = CLLocationManager()
locationManager.requestAlwaysAuthorization()

1
2
CLLocationManager *locationManager = [[CLLocationManager alloc] init];
[locationManager requestAlwaysAuthorization];

Step 5: Verify background push

Braze syncs geofences to devices using background push notifications. Follow these instructions to set up silent push notifications so that geofence updates from the server are properly handled.

Manually request geofences

When the Braze SDK requests geofences 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.

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 desired coordinates.

Step 1: Set automaticGeofenceRequests to false

You can disable automatic geofence requests in your configuration object passed to init(configuration). Set automaticGeofenceRequests to false.

• 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;

Step 2: Call requestGeofences manually

In your code, request geofences with the appropriate latitude and longitude.

• swift
• objective-c

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

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

Frequently Asked Questions (FAQ)

Why am I not receiving geofences on my device?

To confirm whether or not geofences are being received on your device, first use the SDK Debugger tool to check SDK’s logs. You will then be able to see if geofences are successfully being received from the server and if there are any notable errors.

Below are other possible reasons geofences may not be received on your device:

iOS operating system limitations

The iOS operating system 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.

Rate limiting

Braze has a limit of 1 geofence refresh per session to avoid unnecessary requests.

How does it work if I am using both Braze and non-Braze geofence features?

As mentioned above, iOS allows a single app to store a maximum of 20 geofences. This storage is shared by both Braze and non-Braze geofences and is managed by CLLocationManager.

For instance, if your app contains 20 non-Braze geofences, there would be no storage to track any Braze geofences (or vise versa). In order to receive new geofences, you will need to use Apple’s location APIs to stop monitoring some of the existing geofences on the device.

Can the Geofences feature be used while a device is offline?

A device needs to be connected to the internet only when a refresh occurs. Once it has successfully received geofences from the server, it is possible to log a geofence entry or exit even if the device is offline. This is because a device’s location operates separately from its internet connectivity.

For example, say a device successfully received and registered geofences on session start and goes offline. If it then enters one of those registered geofences, it can trigger a Braze campaign.

Why are geofences not monitored when my app is backgrounded/terminated?

Without Always authorization, Apple restricts location services from running while an app is not in use. This is enforced by the operating system and is outside the control of the Braze SDK. While Braze offers separate configurations to run services while the app is in the background, there is no way to circumvent these restrictions for apps that are terminated without receiving explicit authorization from the user.