Mobile Guidelines — Android

This topic addresses considerations when developing for an Android device:

Permissions

For permissions required by the OpenTok Android SDK, see the Permissions section of the Android SDK overview.

Creating a VoIP app using the Android ConnectionService

Use the Android ConnectionService class to create a VoIP app that uses the audio-video capabilities of the OpenTok Android SDK.

At a minimum, follow these guidelines to create a basic VoIP app:

<service android:name="com.example.package.MyConnectionService"
    android:label="@string/some_label_for_my_connection_service"
    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE">
    <intent-filter>
        <action android:name="android.telecom.ConnectionService" />
    </intent-filter>
</service>

Create a class that extends the android.telecom.ConnectionService class. Implement methods of the ConnectionService class, including onCreateIncomingConnection(), onCreateOutgoingConnection, onCreateIncomingConnectionFailed(), and onCreateOutgoingConnectionFailed().
Create a class that extends the android.telecom.Connection class. Implement methods of the Connection class, including onAnswer() and onDisconnect. In the implementation of the onAnswer() method, you can connect to an OpenTok session, publish a stream to the session, and enable code to subscribe to streams created in the session. In the implementation of the onDisconnect() method, you can disconnect from the OpenTok sesssion (and stop publishing and subscribing to streams).
You can use service like Google Firebase to implement push notifications for the app. You can set up notifications to know when your app is in the background or closed. This way, your app can receive a VoIP call while the app is in the closed state.

When using ConnectionService, use the AudioDeviceManager.getAudioFocusManager() method and implement methods of the returned AudioFocusManager instance to delegate audio focus control to your app. These are defined in the OpenTok Android SDK:

private AudioDeviceManager audioDeviceManager;
private AudioFocusManager audioFocusManager;

public void setupAudioFocusManager(Context context) {
  audioDeviceManager = new AudioDeviceManager(context);
  audioFocusManager = audioDeviceManager.getAudioFocusManager();
  audioFocusManager.setRequestAudioFocus(false);
}

public void notifyAudioFocusIsActive() {
  audioFocusManager.audioFocusActivated();
}

public void notifyAudioFocusIsInactive() {
  audioFocusManager.audioFocusDeactivated();
}

When delegating audio focus to the app, the SDK stops its automatic audio routing. Instead, this routing logic is handled by ConnectionService, which notifies the app about available audio devices through the Connection's CallEndpoint and CallAudioState APIs. Your app must implement support for audio device enumeration and selection logic.

This delegation ensures proper audio routing and coordination with the Android Telecom system.

See the sample VOIP app in the opentok-android-sdk-samples repo. It shows how to implement the ConnectionService class to create a VoIP app that uses the OpenTok Android SDK.

Setting up foreground services

Foreground services let you asynchronously perform operations that are noticeable to the user. Foreground services show a status bar notification, to make users aware that your app is performing a task in the foreground and is consuming system resources. Notice that the ConnectionService can be used as a Foreground service. Examples of use cases that use foreground services include:

Keep capturing and sending audio to peers even when the user opens a different app.
Allow a user to share their screen while switching between apps.
Allow users to turn off the screen while still listening to a video call.

Foreground Services Types

Android 10 introduced the android:foregroundServiceType attribute within the element. The idea of it is to explicitly specify what kind of work the service does.

Android 14 makes specifying the foreground service type mandatory. This is to ensure the correct usage of foreground services and consistency across device manufacturers.

The currently supported types are:

camera (required in Android 11) — When accessing the camera from the background, such as video calling apps
connectedDevice — When interacting with external device, such as Bluetooth fitness device
dataSync — When uploading or downloading data, will be deprecated and alternatives like DownloadManager, BackupManager, or WorkManager should be used instead
health (new in Android 14) — For fitness apps such as exercise trackers
location (required in Android 10) — When location is required, such as navigation
mediaPlayback — When continuing audio or video playback from the background, like Spotify or Netflix
mediaProjection — When projecting content to external devices or screens
microphone (required in Android 11) — When accessing the microphone from the background, such as calling apps
phoneCall — When continuing an ongoing call
remoteMessaging (new in Android 14) — when transferring text messages from one device to another
shortService — When a service to quickly finish critical work that can’t be interrupted (limited to running for about 3 minutes)
specialUse — When other types don’t cover your use case
systemExempted — Reserved for system apps

Declare foreground service type

The first step in supporting Android 14 is to update your service declaration in the AndroidManifest file and specify the correct foreground service type.

If your service requires multiple types, you can combine them using the | operator like this:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" ...>
    <service
        android:name=".MyForegroundService"
        android:foregroundServiceType="microphone|camera"
        android:exported="false">
    </service>
</manifest>

If you try to start a foreground service without declaring its type in the manifest, the system will throw a MissingForegroundServiceTypeException upon calling startForeground().

Request specific foreground service permissions

From Android 9 (API 28) onwards, apps had to request the FOREGROUND_SERVICE permission in the app manifest, which was granted automatically by the system.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE"/>

Starting from Android 14 (API 34), apps need to additionally request specific permissions depending on the type of the foreground service. So, if your service keeps accessing the microphone in the background, you need to specify FOREGROUND_SERVICE_MICROPHONE. The permission is automatically granted by the system.

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE"/>

If your service requires multiple types, you have to declare this permission for each type.

If you forget to declare either of the two permissions, you will receive a SecurityException with the exact reason.

Launch a foreground service

Depending on the API level used, start the service as in the following:

Intent serviceIntent = new Intent(this, MyForegroundService.class);
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { // Android 8.0 (API 26) and above
    startForegroundService(serviceIntent);
} else { // Android 7.0 (API 24, 25)
    startService(serviceIntent);
}

The code snippet launches a service. However, the service is not yet running in the foreground. Inside the service itself, you need to call startForeground() to promote the service to a foreground service. If you are using AndroidX, you need to call ServiceCompat.startForeground().

Provide details of your use case on Google Play Console

After you upload the new version of the app that targets Android 14 and uses a foreground service type to the Google Play Console, you will see a prompt in your console to provide additional details about your usage.

As Google wants to make sure that apps are using foreground services appropriately, you will need to submit a new declaration on the App content page (Policy -> App content).

For each foreground service type you declare, you’ll need to do the following:

Describe the app functionality that is using the foreground service type.
Describe the user impact if the task is deferred or interrupted by the system.
Include a link to a video demonstrating each foreground service feature. The video should demonstrate the steps the user needs to take in your app to trigger the feature.
Choose your specific use case for each foreground service type. You can choose from a pre-set list of use cases listed here or enter it manually.

Sample app and more information

See the Basic-Video-Chat-With-ForegroundServices-Java sample in the opentok-android-sdk-samples repo.

Read more in the Android Foreground Services Overview documentation.

More information

For more information, see: