Apple is expected to release the next version of iPhone iOS (iOS 13) to the public around September 17th 2019. It will introduce some changes to the location permissions, as well as a brand-new Bluetooth permission.

If you’re an app developer using Xtremepush SDKs, then these changes affect your iOS app(s). In this article we walk you through what’s changing, and how to adapt to it. We’ll do this in an order that we think gives the most complete picture of the changes as related to iOS 13:

1. Core Location 
2. Core Location, Core Bluetooth and iBeacon
3. The Xtremepush SDK

If you do not use the Location Services of the Xtremepush SDK or any other Location Services in your App you may wish to skip the background info and jump straight to the Action point section that applies to you.

• Action points for Xtremepush iOS SDK users who do not use any of our location services

If you do use Location Services and are already well aware of the iOS 13 changes around location permissions, feel free to jump straight to the Action point section for an Xtremepush SDK user who uses our location service:

• Action points for Xtremepush iOS SDK users who use our location services but only for Geofences
• Action points for Xtremepush iOS SDK users who use our location services for Geofences and iBeacons

Core Location

If you use any Location capabilities in your iOS app you most likely use Core Location. In iOS 13 there are changes to some of the Core Location behaviour - let’s go through them.

Allow Once

There’s a new option for the location prompt: “allow once”. It grants location powers to the app for a single foreground session only. When the user leaves the app or locks the smartphone, the permission will automatically expire, and the app will need to ask again next time.

Changes to the Always location opt-in

Today, apps can choose to prompt the user for the background location permission (also known as “always” or “even when not using the app”) right away. This appears alongside an option for "when in use" or "never".  You can see the current behaviour in our article on location permissions changes for iOS 11 which was when the "when in use" option was added.

In iOS 13, if your app requests the “always” permission, the initial pop-up won’t actually include such an option—the choices for the user will be “just once”, “when in use” or “never”.

If the user agrees to “when in use”, then at some point in the future when your app would normally obtain a background location event (for example, an “enter” beacon region event), the user will be presented with an option to upgrade the permission to “always”. If they do, your app will receive the background event.

So if for example, if a user walks into a store or location where you have geo-fencing or an iBeacon, when they trigger an entry they will see a prompt on their phone similar to this:

Changes to the periodic background usage reminder

The periodic “app X has been using your location in the background, are you still okay with that?” pop-up will now show a map of places where the app accessed location data.

This previously only gave you the generic information that the app had been using your location in the background. Now it will show where your app triggered geo-fences and where it checked location to make sure that nearby geo-fences were set correctly. The location usage description is repeated here.

Core Location, Core Bluetooth and iBeacon

It is common for Apps or SDKs that work with iBeacons to use a combination of Core Location and Core Bluetooth. In iOS 13 there are changes to some of the Core Bluetooth behaviour - let’s go through them.

Apps have been required to explain their Bluetooth usage under the NSBluetoothPeripheralUsageDescription key in their Info.plist file (= internal metadata) since iOS 10, but that description was for the App Store review team only, and never actually shown to the user. If you forget the `NSBluetoothPeripheralUsageDescription` in your Info.plist file, you get an automated email in your inbox when uploading your app to the App Store.

Prior to iOS 13 if you were using Core Location and Core Bluetooth to work with iBeacons as long as you added the description for NSBluetoothPeripheralUsageDescription and made sure you didn't have the background mode "Acts as a bluetooth LE accessory" switched on, you did not receive an automated email when uploading your app to the App Store and your users did not receive a system prompt related to bluetooth.  If your app used the bluetooth LE accessory background mode for some other reason, users did receive a permissions prompt related to bluetooth usage. We covered this in our article on changes to NSBluetoothPeripheralUsageDescription before iOS 10 was released. 

iOS 13 is making any usage of Core Bluetooth more transparent to your users, with the new “allow this app to use Bluetooth?” prompt. It’ll pop up automatically the first time your app opens on iOS 13 if Core Bluetooth is included in your App.

There’s also a new key for the Info.plist file: NSBluetoothAlwaysUsageDescription, which you can use to explain how and why your app uses Bluetooth. In contrast to the existing NSBluetoothPeripheralUsageDescription, the new description will be shown as part of the new pop-up, and also in the Settings app on the Bluetooth Privacy screens.

The Xtremepush SDK

If you use the Xtremepush SDK in any iOS app you are impacted by the iOS 13 Location Permission changes because the Xtremepush iOS SDK (version 4.0.18 and older) includes Apples Core Bluetooth framework by default. Core Bluetooth is only actively used if you use iBeacons as part of our Location services offering. However iOS 13 is making any presence of the Core Bluetooth Framework more transparent to your users, with the new “allow this app to use Bluetooth?” prompt. This means the new Bluetooth Permission prompt will pop up automatically the first time your app opens on iOS 13 if a version of the Xtremepush SDK older than 4.1.0 is included in your App.

It will appear only once, and after the user interacts with it (selects "Don't Allow"/"OK") it will not be seen again.  We understand that if you do not use iBeacons you will not want your users to see this prompt even once. We have updated our SDK in version 4.1.0 so you can avoid this. 

In version 4.1.0 we updated the Xtremepush iOS SDK to separate the Location and Beacon services (previously bundled together) so that by default we will not instantiate any Core Bluetooth managers unless Beacons are explicitly enabled. This prevents the Bluetooth permissions prompt but also means that Beacon Services will be disabled by default.

What Do I Need To Do?

Instructions on how to update your app to adapt to the change brought in iOS 13 follow for the three possible location related SDK usage cases. Please follow the action points for the case that fits how you use the SDK, possible cases are:

• Action points for Xtremepush iOS SDK users who do not use any of our location services
• Action points for Xtremepush iOS SDK users who use our location services but only for Geofences
• Action points for Xtremepush iOS SDK users who use our location services and use iBeacons 

Action points for Xtremepush iOS SDK users who do not use any of our location services

If you are not using any of our Location Services and do not want your users to see a prompt asking for Bluetooth permissions for any reason you will need to update to the latest version of the Xtremepush SDK and release an app update prior to September 17th 2019.

You do not need to change any of your integration code but you need to update to the latest SDK version (should be SDK version 4.1.0 or higher). Also please review the advice on the NSBluetoothPeripheralUsageDescription from iOS 10 which still applies to avoid receiving an automated email when uploading your updated app. 

N.B. If after performing the update when testing on an iPhone running iOS 13 beta and still see the new Bluetooth Permissions prompt (as shown below) then check that your App or other dependencies you use in your App are not using Apple's Core Bluetooth Framework. The Xtremepush SDK is not the only possible source.

Action points for Xtremepush iOS SDK users who use our location services but only for Geofences

If you are using our Location Services but not using iBeacons and do not want your users to see a prompt asking for Bluetooth permissions for any reason you will need to update to the latest version of the Xtremepush SDK and release an app update prior to September 17th 2019. As a location user you are probably already aware of how the upcoming changes in iOS 13 affect your app but below are some other items you may need to consider along with details about updating:

• You will need to update to the latest version of the Xtremepush SDK and release an app update prior to September 17th 2019. You do not need to change any of your integration code but you need to update to the latest SDK version (should SDK version 4.1.0 or higher).  Also please review the advice on the NSBluetoothPeripheralUsageDescription from iOS 10 which still applies to avoid receiving an automated email when uploading your updated app. 

• For the new background opt-in flow for Location, if your app’s copy or images reference the “always allow” option that used to be available right away, you may need to adjust that to explain the new, 2-step process.

• Due to the new background-usage map, you should also double-check that your description of how you describe your location usage or you risk losing the user’s trust, and with it, your background-location-access privileges.

N.B. If after performing the update when testing on an iPhone running iOS 13 beta and still see the new Bluetooth Permissions prompt (as shown below) then check that your App or other dependencies you use in your App are not using Apple's Core Bluetooth Framework. The Xtremepush SDK is not the only possible source.

Action points for Xtremepush iOS SDK users who use our location services and use iBeacons

If you are using Beacon Services note that users on iOS 13 will be prompted to allow Bluetooth via the new Bluetooth Permissions prompt, this is necessary for iBeacons to work. If you do not like this behaviour and want to disable iBeacons so users do not see the prompt you can do this by updating to the latest iOS SDK You do not need to change any of your integration code but you need to update to the latest SDK version (should SDK version 4.1.0 or higher).  Also please review the advice on the NSBluetoothPeripheralUsageDescription from iOS 10 which still applies to avoid receiving an automated email when uploading your updated app. 

If you want to continue using iBeacons you do not need to urgently update your Xtremepush SDK but if you are updating the SDK and want to continue using iBeacons the functionality must now be explicitly enabled. Previously both Geofencing and iBeacon functionality was enabled using 

XPush.setLocationEnabled(true)

along with your other XPush configurations in your AppDelegate.  In SDK version 4.1.0 or higher you will need to explicitly enable beacon capabilities. 

XPush.setLocationEnabled(true)
XPush.setBeaconsEnabled(true)

As an extensive locations user you are probably already aware of how the upcoming changes in iOS 13 affect your app but below are some other items you may need to consider:

• Craft and add the new NSBluetoothAlwaysUsageDescription message to explain Bluetooth usage to the users of your app.

• If you’re creating any Core Bluetooth Manager objects yourself, investigate whether you need to move them to a different spot in your code, to avoid triggering the Bluetooth-permission pop-up prematurely.

• If you have Bluetooth dependent sections in your app update your centralManagerDidUpdateState delegate to properly handle the unauthorized state from the new permissions prompt. For example, you may want to visibly disable any Bluetooth-dependent features in your app, and inform the user how they can re-enable this permission via the iOS Settings app.

FAQ