Locations and geofences

To support geofences for iOS:

1. Your integration must support background push notifications.
2. Braze Geofences must be enabled through the SDK either implicitly by enabling location collection or explicitly by enabling geofence collection. They are not enabled by default.

Step 1: Enable background push

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

Step 2: Enable geofences

By default, geofences are enabled based on whether automatic location collection is enabled. You can enable geofences using the Info.plist file. Add the Braze dictionary to your Info.plist file. Inside the Braze dictionary, add the EnableGeofences boolean subentry and set the value to YES. Note that prior to Braze iOS SDK v4.0.2, the dictionary key Appboy must be used in place of Braze.

You can also enable geofences at app startup time via the startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions method. In the appboyOptions dictionary, set ABKEnableGeofencesKey to YES. For example:

• objective-c
• swift

1
2
3
4
[Appboy startWithApiKey:@"YOUR-API_KEY"
          inApplication:application
      withLaunchOptions:options
      withAppboyOptions:@{ ABKEnableGeofencesKey : @(YES) }];

1
2
3
4
Appboy.start(withApiKey: "YOUR-API-KEY",
                 in:application,
                 withLaunchOptions:launchOptions,
                 withAppboyOptions:[ ABKEnableGeofencesKey : true ])

Step 3: Check for Braze background push

Braze syncs geofences to devices using background push notifications. Follow the iOS customization article to ensure that your application does not take any unwanted actions upon receiving Braze geofence sync notifications.

Step 4: Add NSLocationAlwaysUsageDescription to your Info.plist

Add the key NSLocationAlwaysUsageDescription and NSLocationAlwaysAndWhenInUseUsageDescription to your info.plist with a String value that has a description of why your application needs to track location. Both keys are required by iOS 11 or later. 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 5: Request authorization from the user

The Geofences feature is only functional while Always location authorization is granted.

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

• objective-c
• swift

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

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

Step 6: Enable geofences on the dashboard

iOS only allows up to 20 geofences to be stored for a given app. Using locations will use up some of these 20 available geofence 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 locations to work correctly, you should also confirm that your app is not using all available geofence spots.

Enable geofences from the locations page:

Enable geofences from the settings page:

Disabling automatic geofence requests

Starting in iOS SDK version 3.21.3, you can disable geofences from being automatically requested. You can do this by using the Info.plist file. Add the Braze dictionary to your Info.plist file. Inside the Braze dictionary, add the DisableAutomaticGeofenceRequests boolean subentry and set the value to YES.

You can also disable automatic geofence requests at app startup time via the startWithApiKey:inApplication:withLaunchOptions:withAppboyOptions method. In the appboyOptions dictionary, set ABKDisableAutomaticGeofenceRequestsKey to YES. For example:

• objective-c
• swift

1
2
3
4
[Appboy startWithApiKey:@"YOUR-API_KEY"
          inApplication:application
      withLaunchOptions:options
      withAppboyOptions:@{ ABKDisableAutomaticGeofenceRequestsKey : @(YES) }];

1
2
3
4
Appboy.start(withApiKey: "YOUR-API-KEY",
                 in:application,
                 withLaunchOptions:launchOptions,
                 withAppboyOptions:[ ABKDisableAutomaticGeofenceRequestsKey : true ])

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, starting in iOS SDK version 3.21.3, 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:

• objective-c
• swift

1
2
[[Appboy sharedInstance] requestGeofencesWithLongitude:longitude
                                              latitude:latitude];

1
Appboy.sharedInstance()?.requestGeofences(withLongitude: longitude, latitude: latitude)