TrustedWebActivityService

Kotlin |Java

abstract class TrustedWebActivityService : Service

kotlin.Any
↳	android.content.Context
	↳	android.content.ContextWrapper
		↳	android.app.Service
			↳	androidx.browser.trusted.TrustedWebActivityService

The TrustedWebActivityService lives in a client app and serves requests from a Trusted Web Activity provider. At present it only serves requests to do with notifications.

When the provider receives a notification from a scope that is associated with a Trusted Web Activity client app, it will attempt to connect to a TrustedWebActivityService and forward calls. This allows the client app to display the notifications itself, meaning it is attributable to the client app and is managed by notification permissions of the client app, not the provider.

TrustedWebActivityService is usable as it is, by adding the following to your AndroidManifest:

<code>&lt;service
      android:name="androidx.browser.trusted.TrustedWebActivityService"
      android:enabled="true"
      android:exported="true"&gt;
 
      &lt;meta-data android:name="android.support.customtabs.trusted.SMALL_ICON"
          android:resource="@drawable/ic_notification_icon" /&gt;
 
      &lt;intent-filter&gt;
          &lt;action android:name="android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE"/&gt;
          &lt;category android:name="android.intent.category.DEFAULT"/&gt;
      &lt;/intent-filter&gt;
  &lt;/service&gt;
  </code>

The SMALL_ICON resource should point to a drawable to be used for the notification's small icon.

Alternatively for greater customization, TrustedWebActivityService can be extended and overridden. In this case the manifest entry should be updated to point to the extending class.

As this is an AIDL Service, calls may come in from different Binder threads, so overriding implementations need to be thread safe [1].

For security, the TrustedWebActivityService will check that whatever connects to it matches the Token stored in the TokenStore returned by getTokenStore. This is because we don't want to allow any app on the users device to connect to this Service be able to make it display notifications. [1]: https://developer.android.com/guide/components/aidl.html

Summary

Constants
static String	ACTION_TRUSTED_WEB_ACTIVITY_SERVICE An Intent Action used by the provider to find the TrustedWebActivityService or subclass.
static String	KEY_SMALL_ICON_BITMAP The key to use to store a Bitmap to return from the onGetSmallIconBitmap() method.
static String	KEY_SUCCESS The key to use to store a boolean in the returns bundle of onExtraCommand method, to indicate whether the command is executed successfully.
static String	META_DATA_NAME_SMALL_ICON The Android Manifest meta-data name to specify a small icon id to use.
static Int	SMALL_ICON_NOT_SET Used as a return value of onGetSmallIconId when the icon is not provided.

Public constructors
<init>() The TrustedWebActivityService lives in a client app and serves requests from a Trusted Web Activity provider.

Public methods
abstract TokenStore	getTokenStore() Returns a TokenStore that is used to determine whether the connecting package is allowed to connect to this service.
open Boolean	onAreNotificationsEnabled(@NonNull channelName: String) Checks whether notifications are enabled.
IBinder?	onBind(@Nullable intent: Intent?)
open Unit	onCancelNotification(@NonNull platformTag: String, platformId: Int) Cancels a notification.
open Unit	onCreate() Called by the system when the service is first created.
open Bundle?	onExtraCommand(@NonNull commandName: String, @NonNull args: Bundle, @Nullable callbackRemote: TrustedWebActivityCallbackRemote?) Contains a free form command from the browser.
open Bundle	onGetSmallIconBitmap() Returns a Bundle containing a bitmap to be use as the small icon for any notifications.
open Int	onGetSmallIconId() Returns the Android resource id of a drawable to be used for the small icon of the notification.
open Boolean	onNotifyNotificationWithChannel(@NonNull platformTag: String, platformId: Int, @NonNull notification: Notification, @NonNull channelName: String) Displays a notification.
Boolean	onUnbind(@Nullable intent: Intent?)

Constants

ACTION_TRUSTED_WEB_ACTIVITY_SERVICE

static val ACTION_TRUSTED_WEB_ACTIVITY_SERVICE: String

An Intent Action used by the provider to find the TrustedWebActivityService or subclass.

Value: "android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE"

KEY_SMALL_ICON_BITMAP

static val KEY_SMALL_ICON_BITMAP: String

The key to use to store a Bitmap to return from the onGetSmallIconBitmap() method.

Value: "android.support.customtabs.trusted.SMALL_ICON_BITMAP"

KEY_SUCCESS

static val KEY_SUCCESS: String

The key to use to store a boolean in the returns bundle of onExtraCommand method, to indicate whether the command is executed successfully.

Value: "androidx.browser.trusted.SUCCESS"

META_DATA_NAME_SMALL_ICON

static val META_DATA_NAME_SMALL_ICON: String

The Android Manifest meta-data name to specify a small icon id to use.

Value: "android.support.customtabs.trusted.SMALL_ICON"

SMALL_ICON_NOT_SET

static val SMALL_ICON_NOT_SET: Int

Used as a return value of onGetSmallIconId when the icon is not provided.

Value: -1

Public constructors

<init>

TrustedWebActivityService()

The TrustedWebActivityService lives in a client app and serves requests from a Trusted Web Activity provider. At present it only serves requests to do with notifications.

When the provider receives a notification from a scope that is associated with a Trusted Web Activity client app, it will attempt to connect to a TrustedWebActivityService and forward calls. This allows the client app to display the notifications itself, meaning it is attributable to the client app and is managed by notification permissions of the client app, not the provider.

TrustedWebActivityService is usable as it is, by adding the following to your AndroidManifest:

<code>&lt;service
      android:name="androidx.browser.trusted.TrustedWebActivityService"
      android:enabled="true"
      android:exported="true"&gt;
 
      &lt;meta-data android:name="android.support.customtabs.trusted.SMALL_ICON"
          android:resource="@drawable/ic_notification_icon" /&gt;
 
      &lt;intent-filter&gt;
          &lt;action android:name="android.support.customtabs.trusted.TRUSTED_WEB_ACTIVITY_SERVICE"/&gt;
          &lt;category android:name="android.intent.category.DEFAULT"/&gt;
      &lt;/intent-filter&gt;
  &lt;/service&gt;
  </code>

The SMALL_ICON resource should point to a drawable to be used for the notification's small icon.

Alternatively for greater customization, TrustedWebActivityService can be extended and overridden. In this case the manifest entry should be updated to point to the extending class.

As this is an AIDL Service, calls may come in from different Binder threads, so overriding implementations need to be thread safe [1].

For security, the TrustedWebActivityService will check that whatever connects to it matches the Token stored in the TokenStore returned by getTokenStore. This is because we don't want to allow any app on the users device to connect to this Service be able to make it display notifications. [1]: https://developer.android.com/guide/components/aidl.html

Public methods

getTokenStore

@BinderThread @NonNull abstract fun getTokenStore(): TokenStore

Returns a TokenStore that is used to determine whether the connecting package is allowed to connect to this service.

Return
TokenStore	An TokenStore containing the verified provider.

onAreNotificationsEnabled

@BinderThread open fun onAreNotificationsEnabled(@NonNull channelName: String): Boolean

Checks whether notifications are enabled.

Parameters
channelName	String: The name of the notification channel to be used on Android O+.

Return
Boolean	Whether notifications are enabled.

onBind

@Nullable @MainThread fun onBind(@Nullable intent: Intent?): IBinder?

onCancelNotification

@BinderThread open fun onCancelNotification(
    @NonNull platformTag: String, 
    platformId: Int
): Unit

Cancels a notification.

Parameters
platformTag	String: The notification tag, see NotificationManager#cancel(String, int).
platformId	Int: The notification id, see NotificationManager#cancel(String, int).

onCreate

@CallSuper @MainThread open fun onCreate(): Unit

Called by the system when the service is first created. Do not call this method directly. Overrides must call super.onCreate().

onExtraCommand

@BinderThread @Nullable open fun onExtraCommand(
    @NonNull commandName: String, 
    @NonNull args: Bundle, 
    @Nullable callbackRemote: TrustedWebActivityCallbackRemote?
): Bundle?

Contains a free form command from the browser. The client and browser will need to agree on an additional API to use in advanced. This call can be used for testing or experimental purposes. A return value of null will be used to signify that the client does not know how to handle the request. As optional best practices, KEY_SUCCESS could be use to identify that command was *successfully* handled. For example, when returning a message with result:

<code>
          Bundle result = new Bundle();
          result.putString("message", message);
          if (success)
              result.putBoolean(KEY_SUCCESS, true);
          return result;
      </code>

On the caller side:

<code>
          Bundle result = service.extraCommand(commandName, args);
          if (result.getBoolean(service.KEY_SUCCESS)) {
              // Command was successfully handled
          }
      </code>

Parameters
commandName	String: Name of the command to execute.
args	Bundle: Arguments to the command.
callbackRemote	TrustedWebActivityCallbackRemote?: Contains the callback that passed with the command.

Return
Bundle?	The result Bundle or null.

onGetSmallIconBitmap

@BinderThread @NonNull open fun onGetSmallIconBitmap(): Bundle

Returns a Bundle containing a bitmap to be use as the small icon for any notifications.

Return
Bundle	A Bundle that may contain a Bitmap contained with key KEY_SMALL_ICON_BITMAP. The bundle may be empty if the client app does not provide a small icon.

onGetSmallIconId

@BinderThread open fun onGetSmallIconId(): Int

Returns the Android resource id of a drawable to be used for the small icon of the notification. This is called by the provider as it is constructing the notification so a complete notification can be passed to the client. Default behaviour looks for meta-data with the name META_DATA_NAME_SMALL_ICON in service section of the manifest.

Return
Int	A resource id for the small icon, or SMALL_ICON_NOT_SET if not found.

onNotifyNotificationWithChannel

@BinderThread open fun onNotifyNotificationWithChannel(
    @NonNull platformTag: String, 
    platformId: Int, 
    @NonNull notification: Notification, 
    @NonNull channelName: String
): Boolean

Displays a notification.

Parameters
platformTag	String: The notification tag, see NotificationManager#notify(String, int, Notification).
platformId	Int: The notification id, see NotificationManager#notify(String, int, Notification).
notification	Notification: The notification to be displayed, constructed by the provider.
channelName	String: The name of the notification channel that the notification should be displayed on. This method gets or creates a channel from the name and modifies the notification to use that channel.

Return
Boolean	Whether the notification was successfully displayed (the channel/app may be blocked by the user).

onUnbind

@MainThread fun onUnbind(@Nullable intent: Intent?): Boolean