The Permissions API helps you request permission’s from your users.

  • Included in the XAPP SDK
  • Monitors Performance
  • Server-side configurable

Permission Strategies

When requesting permission, the workflow for explaining the need for the permission to the user and requesting the permission is a permission strategy. The strategy consists of creative, typically text or an image, and requirements that need to be fulfilled to present the strategy. Both the strategy requirements and creative can be updated from the server without requiring an update to your app.

iOS

The primary method for requesting record permission is XAPermission requestRecordPermission:. When this method is called, the UI is blocked until the user either grants the permission other decides to wait for later. The parameter that is passed to the method is a callback that is called when either the user has accepted the system permission prompt or decides to grant the permission later. The BOOL parameter granted only returns YES when the system permission is granted.


[XAPermission requestRecordPermission:^(BOOL granted) {
    NSLog(@"%@", granted ? @"Permission Granted" : @"Permission Not Granted");
}];

This method can be used as a stand-in for AVAudioSession’s requestRecordPermission:.

In order to keep your UI fast and responsive, a strategy is only presented if there is one already loaded in the cache. This means that the first time this method is called, it will immediately return NO in the callback and then it will cache a strategy in the background.

If this method is called in your workflow before you start the XAPP session, you will see an NSInvalidArgumentException exception. To alleviate this exception, you can set your credentials with:


[XAPermission useAPIKey:apiKey]
         applicationKey:appKey];

Android

Setup

The Permissions API is included with the XappAds SDK, to get setup with the SDK please see the quick-start guide.

Update your Manifest

Add the activity to your AndroidManifest.xml:

<activity
    android:name="xappmedia.sdk.permissions.ui.RequestPermissionsSoftAskActivity"
    android:theme="@style/Xapp.Theme.Permissions.Activity"/>

Server Strategy

To use a permission strategy that is set up on the Permissions API server:

ArrayList<Permission> collection = new ArrayList<>();
collection.add(Permission.newPermission(Manifest.permission.RECORD_AUDIO).build());

RequestPermissionsSoftAskActivity.newIntent(collection)
        .keys(apiKey, appKey) // credentials are required
        .type(RequestPermissionsCreativeFragment.TYPE_IMAGE)
        .creativeOnly(true)   // this is the key to requesting server based creative
        .startActivity(getActivity(), REQUEST_PERMISSIONS);

When called, if a permission strategy is not already cached it will immediately return to onActivityResult that the permission was not granted and will call the server to retrieve a new strategy. When this call is made again, it will then display the cached strategy to the user.

Local Strategy

If you don’t want to rely on server based strategies, you can also create a permission workflow locally:

Permission recordPermission =
    Permission.newPermission(Manifest.permission.RECORD_AUDIO)
              .rationale("This app would like to use the microphone")
              .imageResourceDrawable(R.drawable.record_image)
              .build();

List<Permission> permissions = new ArrayList();
permissions.add(recordPermission);
RequestPermissionsSoftAskActivity.requestPermission(getActivity(),
                                                    collection,
                                                    REQUEST_PERMISSIONS);

The Activity will present a prompt with the given rationale asking the user for the permission. The Activity accepts a collection of Permissions so it is possible to include multiple permissions at once. If the user accepts, then the Android system prompt will be displayed to actually grant the permissions. The Activity will immediately return if all permissions have already been granted previously.

Activity Results

The results of the permission activity are passed to the onActivityResult, the list of granted and denied permissions can be retrieved as follows:

@Override
public void onActivityResult(int code, int result, Intent data) {
    super.onActivityResult(code, result, data);

    if (code == REQUEST_PERMISSIONS) {
        if (result == Activity.RESULT_OK) {
            final List<Permission> granted = data.getParcelableArrayListExtra(RequestPermissionsSoftAskActivity.RESULT_PERMISSION_GRANTED_LIST);
            final List<Permission> denied = data.getParcelableArrayListExtra(RequestPermissionsSoftAskActivity.RESULT_PERMISSION_DENIED_LIST);

            StringBuilder sb = new StringBuilder();

            if (!denied.isEmpty()) {
                sb.append("The following have not been granted:\n");
                for (Permission p : denied) {
                    sb.append(p.getName()).append("\n");
                }
            }

            if (!granted.isEmpty()) {
                sb.append("The following have been granted: \n");
                for (Permission p : granted) {
                    sb.append(p.getName()).append("\n");
                }
            }

            Toast.makeText(this, sb.toString(), Toast.LENGTH_SHORT).show();
        }
    }
}

Resources