Manage Android permissions, services, and receivers

Overview

The SDK requires your mobile app users to enable certain permissions and services. You can declare these permissions and services in the AndroidManifest.xml file.

Permissions

Permissions determine what your mobile app can access and can do. When you install the Android SDK in your mobile application, it also adds the SDK permissions. By default, permissions in the AndroidManifest.xml file are merged into your application's manifest.

📘

Note:

You can override the default merge into your application's manifest. For more information, see Merge multiple manifest files.

Manage permissions

You can manage the permissions merged from the SDKs AndroidManifest.xml file. You can choose what permissions to merge to your application's manifest. Defining this helps you to have only a minimum set of required permissions. Complete the following steps to define which permissions you want to merge.

  1. Add xmlns:tools=http://schemas.android.com/tools attribute to the <manifest … > tag.
  2. Define permissions in your AndroidManifest.xml file as shown in the following example:
<!-- Remove all inherited permissions -->
<uses-permission tools:node="removeAll">
 
<!-- Add back the specific permissions that the Acoustic SDK requires  -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
<uses-permission android:name="android.permission.VIBRATE" />
 
<!-- Add any additional permissions that you choose for your app (examples shown) -->
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
<uses-permission android:name="android.permission.BATTERY_STATS" />

📘

Note:

When you add the <uses-permission tools:node="removeAll"> directive to remove all inherited permissions, it prevents the merge of any app library permissions. You are responsible for managing the permissions necessary for your application to work. You must declare all required permissions in your AndroidManifest.xml file.

🚧

Warning:

For Android 6.0 and later, users are prompted to grant permission only when they start to use a feature that requires it. Therefore users can use the application for a long time without proper permissions. Users will receive the prompt only if it is declared in the manifest. When such permissions are not declared, it may cause the app to crash.

The following table lists of permissions declared in the Android manifest file:

Table 1 – Permissions in AndroidManifest.xml file

PermissionDescription
android.permission.INTERNET – (required)Internet is required for your mobile app to call the Acoustic server. This permission grants access for your app to access the mobile device's internet.
android.permission.WAKE_LOCK – (required)WAKE_LOCK is required for running scheduled tasks on some versions of Android. The task scheduling system helps conserves battery usage on users' mobile devices. Tasks perform actions and then shut down immediately when the work is done. This feature eliminates the need to keep services running in the background. Customers do not complain about apps that run all the time.
Background services like the MCE and GCM registration and metrics use task. These services need a partial wake lock (CPU only). The Task Framework manages these tasks. Tasks get the wake lock when the task starts and release the wake lock immediately after the task.
android.permission.RECEIVE_BOOT_COMPLETED – (required)RECEIVE_BOOT_COMPLETED is required for performing SDK tasks on device startup.

This permission is required for the SDK registration. The first time users open your app, the SDK attempts to register with the Campaign servers. In some cases, users might be in an area with a poor internet connection. The SDK then retries the registration with exponential back off. The exponential backoff helps to conserve battery usage. In this case, a task is scheduled that uses the Android Alarm service to run after a time to retry the registration. If the user reboots the phone, the Alarm service removes all scheduled tasks. This permission lets the SDK know when the device starts again, so the SDK is registered. Users do not receive notifications before a successful registration occurs.
Acoustic Campaign also sends metrics to Campaign servers when metrics are collected. Rescheduling the metrics tasks on boot complete ensures that servers receive the metrics. Metrics tasks do no work unless metrics that Campaign can send exists.
By default, all alarms are canceled when a device shuts down. You can use this permission to prevent the cancellation of alarms. You can design your application to restart a repeating alarm if the user reboots the device.
For more information, see Start an alarm when the device restarts.
android.permission.VIBRATE – (required)VIBRATE is required for notification configuration.
android.permission.BIND_JOB_SERVICE – (required for Android 5.0 and later).BIND_JOB_SERVICE is required to support Android 5.0 and later devices.
android.permission.CALL_PHONE – (optional)CALL_PHONE is only required when the dial action is used.
android.permission.ACCESS_FINE_LOCATION – (optional)ACCESS_FINE_LOCATION is only required when location services need to use GPS location.
android.permission.ACCESS_COARSE_LOCATION – (optional)ACCESS_COARSE_LOCATION is only required when location services need to use network location.
android.permission.BLUETOOTH – (optional)BLUETOOTH is only required when iBeacons are supported.
android.permission.BLUETOOTH_ADMIN – (optional)BLUETOOTH_ADMIN only required when iBeacons are supported.

Services

Services also help support the SDK functionalities on your mobile app. The services are listed in the AndroidManifest.xml file.

Table 2 – Services in AndroidManifest.xml file

ServiceDescription
co.acoustic.mobile.push.sdk.attributes.AttributesQueueConsumer – [required]AttributesQueueConsumer is required for attributes handling.
co.acoustic.mobile.push.sdk.events.EventsAlarmListener – (required)EventsAlarmListener is required for event handling.
co.acoustic.mobile.push.sdk.registration.PhoneHomeIntentService – (required)PhoneHomeIntentService is required for the client to update the state on the server.
co.acoustic.mobile.push.sdk.registration.RegistrationIntentService – (required)RegistrationIntentService is required for SDK registration.
co.acoustic.mobile.push.sdk.job.MceJobService – (required for Android 5.0 and later.)MceJobService is used for launching a job while the app is in the background. It is required only for Android 5.0 and later.
co.acoustic.mobile.push.sdk.messaging.fcm.FcmMessagingService with action com.google.firebase.MESSAGING_EVENT – (required to use FCM.)FcmMessagingService is required for FCM messaging.
co.acoustic.mobile.push.sdk.plugin.inbox.InboxUpdateService – (optional, required for inbox or in-app messages)InboxUpdateService is optional. It is used for retrieving inbox updates from the MCE server. It is only required when the inbox is used.
co.acoustic.mobile.push.sdk.location.LocationEventsIntentService – (optional, required for geofence, iBeacon)LocationEventsIntentService is optional. It is used to handle location events back off. It is only required when locations are enabled.
co.acoustic.mobile.push.sdk.location.LocationRetrieveService – (optional, required for geofence, iBeacon)LocationRetrieveService is optional. It is used for retrieving the device location. It is only required when locations are enabled.
co.acoustic.mobile.push.sdk.location.LocationSyncAlarmListener – [optional, required for geofence, iBeacon]LocationSyncAlarmListener is optional. It is used to schedule location sync. It is only required when locations are enabled.
co.acoustic.mobile.push.sdk.beacons.MceBluetoothScanner – (optional, required for iBeacon)MceBluetoothScanner is optional. It is used to run the Bluetooth scan. It is only required when iBeacons is used.
co.acoustic.mobile.push.sdk.beacons.BeaconsVerifier – (optional, required for iBeacon)BeaconsVerifier is used to verify the Bluetooth scan. It is only required when iBeacons are used.
co.acoustic.mobile.push.sdk.plugin.snooze.SnoozeIntentService – (optional, required for snooze action)SnoozeIntentService is optional. It is only required when the snooze action is used.

Receivers

Receivers are used when you register for system or application events.
Table 2 – Receivers in AndroidManifest.xml file

ReceiverDescription
co.acoustic.mobile.push.sdk.notification.NotifActionReceiver – (required)NotifActionReceiver is required for notification handling.
co.acoustic.mobile.push.sdk.wi.AlarmReceiver with actions android.intent.action.BOOT_COMPLETED, android.intent.action.TIMEZONE_CHANGED, android.intent.action.PACKAGE_REPLACED, and android.intent.action.LOCALE_CHANGED – (required)AlarmReciever is required to run SDK scheduled tasks and device status updates.
co.acoustic.mobile.push.sdk.location.GeofenceBroadcastReceiver – (optional, required for geofence)GeofenceBroadcastReceiver is optional. It is used to receive geofence events. It is required only if locations are enabled and geofences are used.
co.acoustic.mobile.push.sdk.location.LocationBroadcastReceiver – (optional, required for geofence, iBeacon)LocationBroadcastReceiver is optional. It is used to receive location events. It is only required if locations are enabled.
co.acoustic.mobile.push.sdk.location.LocationUpdateCaller – (optional, required for geofence, iBeacon)LocationUpdateCaller is optional. It is used to schedule location updates. It is only required when locations are enabled.