Permissions

Custom and system permissions are basic building blocks of the ADvantage permission mechanism. If a custom permission is denied on an ADvantage instance, the proper action or feature will not be available for an ad. If a custom permission is granted on an Advantage instance , the system permissions will be checked and if it is granted, the action can be performed, otherwise the action is not available for an ad.

Custom Permissions

You can decide to allow special ad features like the following per ADvantage instance:

Permission	Description
Telephone	Allows ADvantage to initiate a phone call with going through the dialer user interface (dialer application).
Store Picture	NSPhotoLibraryAddUsageDescription or NSPhotoLibraryUsageDescription Allows an application to write to external storage.
SMS	Launch the SMS launcher application.
Sensors	SENSOR_COMPASS SENSOR_ACCELEROMETER SENSOR_GYROSCOPE SENSOR_LIGHT SENSOR_BAROMETER SENSOR_STEP_DETECTOR SENSOR_PROXIMITY
Rotation	SCREEN_PORTRAIT | SCREEN_LANDSCAPE
InlineVideo	Allows ADvantage to play inline videos
Contacts	NSContactsUsageDescription Allows an application to write to the user's contacts data.
Calendar	NSCalendarsUsageDescription Allows an application to write to the user's calendar.
Geo Location	NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription Allow an application to access the user's location.
Bluetooth	NSBluetoothPeripheralUsageDescription Allow an application to check if an application has access to bluetooth.

System Permissions

For the application be able to use some permissions it is needed to set usage description on info.plist for a couple of them.

• NSLocationWhenInUseUsageDescription or NSLocationAlwaysUsageDescription to ask for use of device's geo-location information.
• NSContactsUsageDescription to ask for permission on contacts list.
• NSPhotoLibraryAddUsageDescription or NSPhotoLibraryUsageDescription to ask for access of photo library of the device.
• NSCalendarsUsageDescription to ask access to write a new event into device's calendar.
• NSBluetoothPeripheralUsageDescription to ask the ability to read the device bluetooth information.

Custom Permission Example

To get a better understanding on how these two systems interact, view the following code example:

Swift

advantage.permissions.isContactAllowed = false

Objective-C

[self.banner.permissions setContactAllowed:NO];

If custom permission ContactAllowed is explicitly set to false, the ad will not be able to add any contact to the devices phone book, although in info.plist there might be NSContactsUsageDescription set and the user already accepted its usage.

If custom permission ContactAllowed is explicitly set to true (or implicitly by the default settings), the ad will be able to add contacts to devices phone book, but only if the necessary permissions (NSContactsUsageDescription in info.plist) and the user was prompted to accept it.

System Permissions

To make use of those features, these descriptions should be included in info.plist and the user must be prompted about the usage and accept it. ADvantage is only checking if the access is granted.

Usage Description examples

Some examples of usage descriptions that have to be declared in info.plist to be able to ask for system permissions:

NSLocationAlwaysUsageDescription or NSLocationWhenInUseUsageDescription description needed in order to ask GPS access for.

<key>NSLocationWhenInUseUsageDescription</key>
<string>App needs your location to provide you the most relevant ads.</string>

NSContactsUsageDescription description is needed in order to add or read the device contact list.

<key>NSContactsUsageDescription</key>
<string>App needs access to your contacts.</string>

NSPhotoLibraryUsageDescription or NSPhotoLibraryAddUsageDescription permission needed in order to enable the creative to store a picture to the local phone storage.

<key>NSPhotoLibraryUsageDescription</key>
<string>App needs to save some pictures in your photo library</string>

Revoke permissions

You can change the following custom permissions.

Default permission values

All custom permissions are granted TRUE by default.

For instance, an application that needs to prevent sending SMS messages would specify:

Swift

advantage.permissions.isSmsAllowed = false

Objective-C

//Disable Custom SMS Permission.
[self.ad.permissions setSmsAllowed:NO];