Purpose Strings properties group

Official Content
This documentation is valid for:

This group of properties is available for Main Smart Device objects and is located under the iOS/Permissions properties group.

As of iOS 10, Apple forces developers to indicate the usage reason of device features (e.g. GPS, microphone, calendar, etc.).
This decision bets in favor of the user's privacy, allowing them to choose when some feature is allowed for use or not. 

The effect for the end user is a message displayed on the screen saying that the app is trying to use some feature for the reasons described by the developer. 
Usage description - Runtime behavior

 

Properties

By default, any of these properties are empty. Their values are strings indicating the purpose of usage for each feature used by the developer (it must be set).

Usage description property It must be set if the app... Required as of... GeneXus uses it for... Available as of GX15 ... Available as of GXEv3 ...
Apple Music Access the user's media library. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Bluetooth Peripherical Uses Bluetooth device. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Calendars Access the user's calendar. iOS 10.0 Calendar external object Upgrade 1 Upgrade 11
           
Camera Uses the camera device. iOS 10.0 Camera external objectScanner external objectScanner controlEditable Image data typeEdiatable Video data type Upgrade 1 Upgrade 11
           
Contacts Access the user's contacts. iOS 10.0 Contacts external object Upgrade 1 Upgrade 11
           
Health Share Reads the user's health data. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Health Update Makes changes to the user's health data. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Home Kit Access the user's HomeKit configuration. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Location Always Access the user's location at all times (Read more). iOS 8.0 Geolocation external objectMap control Release Upgrade 2
           
Location Always And When In Use Access the user's location at all times and when it is used. Substitution of "Location Always usage description" as of iOS 11. iOS 11.0 Geolocation external objectMap control Upgrade 7 -
           
Location When In Use Access the user's location while it is used (Read more info). iOS 8.0 Geolocation external objectMap control Release Upgrade 2
           
Microphone Uses the microphone device. iOS 10.0 Editable Audio data typeAudioRecorder external objectCamera external object (RecordVideo method) Upgrade 1 Upgrade 11
           
Motion Uses the accelerometer device. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
NFC Scan Uses the NFC sensor.  iOS 11.0 N/A Ugrade 7 -
           
Photo Library Access the user's photo library. iOS 10.0 PhotoLibrary external objectEditable Image data typeEdiatable Video data type Upgrade 1 Upgrade 11
           
Photo Library Additions  Write permission for photos and videos. iOS 11.0 PhotoLibrary external object (Save and SaveVideo methods) Upgrade 7 -
           
Remainders Uses the user's remainders iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Siri Send data to Siri. iOS 10.0 N/A Upgrade 1 Upgrade 11
           
Speech Recognition Send data to Apple's speech recognition. iOS 10.0 N/A Upgrade 1 Upgrade 11
           


 Column value "N/A" means there is not built-in GeneXus, but can be applied if the developer implements a custom User Controls or External Objects that requires that permission.

Warning: Developers who incorporate any of built-in User Controls or External Objects in their Knowledge Base must set the appropriate Usage Description property. In the same way, it must be set when developers use custom User Controls or External Objects.

Notes

  • A warning message like this will be displayed if the developer uses location services but this property is not set.
    warning: In iOS 10.0 or later, a value for one of these properties is required when you use location services. ('% Usage Description' of <Menu|Panel> for Smart Devices instance '%')
    The iOS version may vary depending on which XCode version is used. Most of them are required as of iOS 10.0.
  • As of Genexus 15 Upgrade 7 the message is similar to:
    warning: In iOS 11.0 or later, 'Location When In Use usage description' property value is required when you use location services. See descriptions of these properties: ‘Location When In Use’, 'Location Always' and 'Location Always and When In Use'.

Troubleshooting
 

If the appropriate Usage Description is not set, the behavior when the application is executed changes by GeneXus version because the iOS project is different:

GeneXus Evolution 3 GeneXus 15

Application crash. XCode indicates a message:
"The app's Info.plist must contain an <feature_key_name> key with a string
value explaining to the user how the app uses this data

Usage description - Evolution 3 - XCode crash

The application displays a pop-up message:
"<feature> usage description not found"

Usage description - GeneXus 15 - Runtime behavior when not found

Scope

Objects Panel for Smart DevicesWork With for Smart Devices, Menu for Smart Devices object 
Level Main object
SD Generators iOS
Languages .NET, Java

Availability

This group of properties is available as of GeneXus X Evolution 3 upgrade 11 / GeneXus 15 upgrade 1.

Was this page helpful?
What Is This?
Your feedback about this content is important. Let us know what you think.