RemoteActivityHelper

class RemoteActivityHelper

Support for opening android intents on other devices.

The following example opens play store for the given app on another device:

val remoteActivityHelper = RemoteActivityHelper(context, executor)

val result = remoteActivityHelper.startRemoteActivity(
    Intent(Intent.ACTION_VIEW)
        .setData(
            Uri.parse("http://play.google.com/store/apps/details?id=com.example.myapp"))
        .addCategory(Intent.CATEGORY_BROWSABLE),
    nodeId)

startRemoteActivity returns a ListenableFuture, which is completed after the intent has been sent or failed if there was an issue with sending the intent.

nodeId is the opaque string that represents a node in the Android Wear network. For the given device, it can obtained by NodeClient.getLocalNode() and the list of nodes to which this device is currently connected can be obtained by NodeClient.getConnectedNodes(). More information about this can be found here.

Summary

Nested types

Constants
const String
const Int

Result code passed to ResultReceiver.send when a remote intent failed to send.
const Int

Result code passed to ResultReceiver.send when a remote intent was sent successfully.
const Int

Indicates that remote activity is available.
const Int

Indicates that remote activity is temporarily unavailable.
const Int

The remote auth's availability is unknown.
const Int

The remote activity's availability is unknown.

Public companion functions
Intent?

Returns the android.content.Intent extra specifying remote intent.
String?

Returns the String extra specifying node ID of remote intent.

Public constructors
RemoteActivityHelper(context: Context, executor: Executor)

Public functions
ListenableFuture<Void>
startRemoteActivity(targetIntent: Intent, targetNodeId: String?)

Start an activity on another device.

Public properties
Flow<Int>

Status of whether RemoteActivityHelper can startRemoteActivity, if known.

Constants

ACTION_REMOTE_INTENT

const val ACTION_REMOTE_INTENT: String

RESULT_FAILED

const val RESULT_FAILED = 1: Int

Result code passed to ResultReceiver.send when a remote intent failed to send.

RESULT_OK

const val RESULT_OK = 0: Int

Result code passed to ResultReceiver.send when a remote intent was sent successfully.

STATUS_AVAILABLE

const val STATUS_AVAILABLE = 3: Int

Indicates that remote activity is available.

There is a connected device capable to handle the remote interaction.

STATUS_TEMPORARILY_UNAVAILABLE

const val STATUS_TEMPORARILY_UNAVAILABLE = 2: Int

Indicates that remote activity is temporarily unavailable.

There is a known paired device, but it is not currently connected or reachable to handle the remote interaction.

STATUS_UNAVAILABLE

const val STATUS_UNAVAILABLE = 1: Int

The remote auth's availability is unknown.

On older devices, STATUS_UNKNOWN is returned as we can not determine the availability states. To preserve compatibility with existing devices behavior, try startRemoteActivity and handle error codes accordingly.

STATUS_UNKNOWN

const val STATUS_UNKNOWN = 0: Int

The remote activity's availability is unknown.

Public companion functions

getTargetIntent

Added in 1.0.0
fun getTargetIntent(intent: Intent): Intent?

Returns the android.content.Intent extra specifying remote intent.

Parameters
intent: Intent

The intent holding configuration.
Returns
Intent?

The remote intent, or null if none was set.

getTargetNodeId

Added in 1.0.0
fun getTargetNodeId(intent: Intent): String?

Returns the String extra specifying node ID of remote intent.

Parameters
intent: Intent

The intent holding configuration.
Returns
String?

The node id, or null if none was set.

Public constructors

RemoteActivityHelper

Added in 1.0.0
RemoteActivityHelper(
    context: Context,
    executor: Executor = Executors.newSingleThreadExecutor()
)
Parameters
context: Context

The Context of the application for sending the intent.
executor: Executor = Executors.newSingleThreadExecutor()

Executor used for getting data to be passed in remote intent. If not specified, default will be Executors.newSingleThreadExecutor().

Public functions

startRemoteActivity

Added in 1.0.0
fun startRemoteActivity(targetIntent: Intent, targetNodeId: String? = null): ListenableFuture<Void>

Start an activity on another device. This api currently supports sending intents with action set to android.content.Intent.ACTION_VIEW, a data uri populated using android.content.Intent.setData, and with the category android.content.Intent.CATEGORY_BROWSABLE present. If the current device is a watch, the activity will start on the companion phone device. Otherwise, the activity will start on all connected watch devices.

Parameters
targetIntent: Intent

The intent to open on the remote device. Action must be set to android.content.Intent.ACTION_VIEW, a data uri must be populated using android.content.Intent.setData, and the category android.content.Intent.CATEGORY_BROWSABLE must be present.
targetNodeId: String? = null

Wear OS node id for the device where the activity should be started. If null, and the current device is a watch, the activity will start on the companion phone device. Otherwise, the activity will start on all connected watch devices.
Returns
ListenableFuture<Void>

The ListenableFuture which resolves if starting activity was successful or throws Exception if any errors happens. If there's a problem with starting remote activity, RemoteIntentException will be thrown.

Public properties

availabilityStatus

Added in 1.1.0
val availabilityStatus: Flow<Int>

Status of whether RemoteActivityHelper can startRemoteActivity, if known.

In scenarios of restricted connection or temporary disconnection with a paired device, startRemoteActivity will not be available. Please check availabilityStatus before calling startRemoteActivity to provide better experience for the user.

Wear devices start to support determining the availability status from Wear Sdk WEAR_TIRAMISU_4. On older wear devices, it will always return STATUS_UNKNOWN. On phone devices, it will always return STATUS_UNKNOWN.

import androidx.wear.remote.interactions.RemoteActivityHelper

remoteActivityHelper.availabilityStatus.collect {
    status -> when (status) {
        RemoteActivityHelper.STATUS_UNAVAILABLE ->
            TODO("Hide or present alternative flow as remote flow is not available.")
        RemoteActivityHelper.STATUS_TEMPORARILY_UNAVAILABLE ->
            TODO("Present education to user to connect devices or bring to proximity.")
        RemoteActivityHelper.STATUS_AVAILABLE, RemoteActivityHelper.STATUS_UNKNOWN ->
            // Present normal remote device flow when we don't know (old devices)
            // or when we know it is available.
            remoteActivityHelper.startRemoteActivity(remoteIntent)
    } }
Returns
Flow<Int>

a Flow with a stream of status updates that could be one of STATUS_UNKNOWN, STATUS_UNAVAILABLE, STATUS_TEMPORARILY_UNAVAILABLE, STATUS_AVAILABLE.