Added in API level 36

AppFunctionManager

class AppFunctionManager
kotlin.Any
   ↳ android.app.appfunctions.AppFunctionManager

Provides access to App Functions.

See android.app.appfunctions for a comprehensive overview of App Functions.

Summary

Constants
static Int

The default state of the app function.
static Int

The app function is disabled.
static Int

The app function is enabled.
Public methods
Unit

Executes the app function.
Unit

Retrieves the registered app functions for the specified activities.
Unit

Retrieves the runtime state of the specified app functions.
Unit
isAppFunctionEnabled(functionIdentifier: String, targetPackage: String, executor: Executor, callback: OutcomeReceiver<Boolean!, Exception!>)

Retrieves whether an app function is enabled (allows execution).
Unit
isAppFunctionEnabled(functionIdentifier: String, executor: Executor, callback: OutcomeReceiver<Boolean!, Exception!>)

Retrieves whether an app function owned by the calling package is enabled (allows execution).
AppFunctionObservation
observeAppFunctions(executor: Executor, appFunctionObserver: AppFunctionObserver)

Registers an observer to monitor changes to app functions within packages that the caller can query.
AppFunctionRegistration
registerAppFunction(functionIdentifier: String, executor: Executor, appFunction: AppFunction)

Registers a runtime implementation for an app function, that can be executed using executeAppFunction.
AppFunctionRegistration

Registers several AppFunction implementations at once, sharing a single lifecycle.
Unit

Searches app function AppFunctionMetadatas.
Unit
setAppFunctionEnabled(functionIdentifier: String, newEnabledState: Int, executor: Executor, callback: OutcomeReceiver<Void!, Exception!>)

Sets the enabled state of the app function owned by the calling package.

Constants

APP_FUNCTION_STATE_DEFAULT

Added in API level 36
static val APP_FUNCTION_STATE_DEFAULT: Int

The default state of the app function.

To reset the enabled state to the default value, call setAppFunctionEnabled with this value.

Value: 0

APP_FUNCTION_STATE_DISABLED

Added in API level 36
static val APP_FUNCTION_STATE_DISABLED: Int

The app function is disabled.

To disable an app function, call setAppFunctionEnabled with this value.

Value: 2

APP_FUNCTION_STATE_ENABLED

Added in API level 36
static val APP_FUNCTION_STATE_ENABLED: Int

The app function is enabled.

To enable an app function, call setAppFunctionEnabled with this value.

Value: 1

Public methods

executeAppFunction

Added in API level 36
fun executeAppFunction(
    request: ExecuteAppFunctionRequest, 
    executor: Executor, 
    cancellationSignal: CancellationSignal, 
    callback: OutcomeReceiver<ExecuteAppFunctionResponse!, AppFunctionException!>
): Unit

Executes the app function.

Applications can execute functions they define. To execute functions defined in another component, the caller must have the Manifest.permission.EXECUTE_APP_FUNCTIONS or android.Manifest.permission#EXECUTE_APP_FUNCTIONS_SYSTEM permissions.

A function can only be executed while its AppFunctionState.isEnabled is true.

See AppFunctionException for possible failures.

Parameters
request ExecuteAppFunctionRequest: the request to execute the app function.
This value cannot be null.
executor Executor: the executor to run the callback.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
cancellationSignal CancellationSignal: the cancellation signal to cancel the execution.
This value cannot be null.
callback OutcomeReceiver<ExecuteAppFunctionResponse!, AppFunctionException!>: the callback to receive the function execution result or error.
This value cannot be null.

getAppFunctionActivityStates

Added in API level 37
fun getAppFunctionActivityStates(
    activityIds: MutableSet<AppFunctionActivityId!>, 
    executor: Executor, 
    callback: OutcomeReceiver<MutableList<AppFunctionActivityState!>!, Exception!>
): Unit

Retrieves the registered app functions for the specified activities.

Each AppFunctionActivityState contains the set of registered AppFunctionNames associated with a requested AppFunctionActivityId.

Functions that do not exist or are not visible to the calling application will be silently omitted from the result. Requested activities that have no registered functions will be omitted from the result.

See AppFunctionActivityId for potential usages, including conversion from android.service.voice.VoiceInteractionSession.ActivityId.

This method follows the same permission rules as searchAppFunctions.

See getAppFunctionStates for retrieving the runtime state of app functions based on their names.

See searchAppFunctions on how to retrieve the AppFunctionMetadata of app functions.

See observeAppFunctions for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
activityIds MutableSet<AppFunctionActivityId!>: The set of activity IDs to retrieve function states for.
This value cannot be null.
executor Executor: The executor to run the callback.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<MutableList<AppFunctionActivityState!>!, Exception!>: The callback to receive the list of activity states.
This value cannot be null.

getAppFunctionStates

Added in API level 37
fun getAppFunctionStates(
    appFunctionNames: MutableList<AppFunctionName!>, 
    executor: Executor, 
    callback: OutcomeReceiver<MutableList<AppFunctionState!>!, Exception!>
): Unit

Retrieves the runtime state of the specified app functions.

This includes runtime-changing properties such as whether the functions are currently enabled or disabled. Functions that do not exist or are not visible to the calling application will be silently omitted from the result list.

This method follows the same permission rules as searchAppFunctions.

See getAppFunctionActivityStates for retrieving the states of app functions associated with a specific activity.

See searchAppFunctions on how to retrieve the AppFunctionMetadata of app functions.

See observeAppFunctions for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
appFunctionNames MutableList<AppFunctionName!>: The names of the app functions to request the state for.
This value cannot be null.
executor Executor: The executor to run the callback.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<MutableList<AppFunctionState!>!, Exception!>: The callback to receive the function state result.
This value cannot be null.

isAppFunctionEnabled

Added in API level 36
fun isAppFunctionEnabled(
    functionIdentifier: String, 
    targetPackage: String, 
    executor: Executor, 
    callback: OutcomeReceiver<Boolean!, Exception!>
): Unit

Retrieves whether an app function is enabled (allows execution).

This is equivalent to calling getAppFunctionStates and checking the AppFunctionState.isEnabled property of the result. Consider using getAppFunctionStates to get the full state of the app function.

If the operation fails, the callback's OutcomeReceiver.onError is called with errors:

Parameters
functionIdentifier String: the identifier of the app function to check (unique within the target package).
This value cannot be null.
targetPackage String: the package name of the app function's owner.
This value cannot be null.
executor Executor: the executor to run the request.
This value cannot be null.
callback OutcomeReceiver<Boolean!, Exception!>: the callback to receive the function enabled check result.
This value cannot be null.

isAppFunctionEnabled

Added in API level 36
fun isAppFunctionEnabled(
    functionIdentifier: String, 
    executor: Executor, 
    callback: OutcomeReceiver<Boolean!, Exception!>
): Unit

Retrieves whether an app function owned by the calling package is enabled (allows execution).

Same as isAppFunctionEnabled(String,String,Executor,OutcomeReceiver) but only for checking functions owned by the calling package.

This is equivalent to calling getAppFunctionStates and checking the AppFunctionState.isEnabled property of the result. Consider using getAppFunctionStates to get the full state of the app function.

Parameters
functionIdentifier String: the identifier of the app function to check (unique within the target package).
This value cannot be null.
executor Executor: the executor to run the request.
This value cannot be null.
callback OutcomeReceiver<Boolean!, Exception!>: the callback to receive the function enabled check result.
This value cannot be null.

observeAppFunctions

Added in API level 37
fun observeAppFunctions(
    executor: Executor, 
    appFunctionObserver: AppFunctionObserver
): AppFunctionObservation

Registers an observer to monitor changes to app functions within packages that the caller can query.

The caller should retain a reference to the returned AppFunctionObservation, and call AppFunctionObservation.cancel when observation is no longer required.

The callback is only triggered by changes after its registration. Any changes that occur before the registration are not reported.

An example usage flow is:

  1. Call observeAppFunctions, to start monitoring app function changes, using the AppFunctionObserver.
  2. Call searchAppFunctions and getAppFunctionStates to get the initial list of app functions and their states.
  3. In AppFunctionObserver.onAppFunctionMetadataChanged, call searchAppFunctions with a AppFunctionSearchSpec that matches the changed packages to get the updated metadata.
  4. In AppFunctionObserver.onAppFunctionStatesChanged, call getAppFunctionStates with the list of AppFunctionNames that matches the changed functions to get the updated states.

    Note that this is guaranteed to trigger after AppFunctionObserver.onAppFunctionMetadataChanged for new functions or functions that also changed states, so there's no need to call getAppFunctionStates in AppFunctionObserver.onAppFunctionMetadataChanged.

Parameters
executor Executor: the executor to run the AppFunctionObserver callbacks.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
appFunctionObserver AppFunctionObserver: the observer to receive updates to registered app functions.
This value cannot be null.
Return
AppFunctionObservation An AppFunctionObservation used to cancel this observation.
This value cannot be null.

registerAppFunction

Added in API level 37
fun registerAppFunction(
    functionIdentifier: String, 
    executor: Executor, 
    appFunction: AppFunction
): AppFunctionRegistration

Registers a runtime implementation for an app function, that can be executed using executeAppFunction.

executeAppFunction targeting an app function provided by this method will trigger the android.app.appfunctions.AppFunction#onExecute method of the provided implementation, as long as the process registering it is not frozen, and the Context registering it is not destroyed (at which point the registration will be removed).

You must declare the app function in your AndroidManifest.xml using an application-level <property> named android.app.appfunctions. See AppFunctionMetadata for details on the XML schema (your_app_functions.xml in the example below).

Example manifest declaration: 

<code>&lt;application ...&gt;
    &lt;property
        android:name="android.app.appfunctions.v2"
        android:value="your_app_functions.xml" /&gt;
    ...
  &lt;/application&gt;
  </code>

Function implementations can only be registered from android.app.Activity or android.app.Service contexts. If registering from an android.app.Activity, strongly consider AppFunctionMetadata.SCOPE_ACTIVITY for your function definition.

The functionIdentifier must correspond to an app function declared in your app's application-level XML assets. If the identifier is not found, this method will throw an IllegalArgumentException. Attempting to register a duplicate function based on the rules of AppFunctionMetadata.getScope will throw an IllegalStateException.

To register multiple functions at once, consider using registerAppFunctions as a more efficient alternative.

The system holds a strong reference to the provided AppFunction implementation as long as it is registered. To prevent memory leaks and ensure the system is aware that the function is no longer available, you must explicitly call AppFunctionRegistration.unregister when the function is no longer relevant (e.g., in android.app.Activity#onStop or before android.app.Service#stopForeground).

Parameters
functionIdentifier String: The unique identifier for the function, which must match an entry in the app's XML resource declarations.
This value cannot be null.
executor Executor: The Executor on which the function will be invoked.
This value cannot be null.
appFunction AppFunction: The AppFunction implementation to be executed when the function is triggered.
This value cannot be null.
Return
AppFunctionRegistration A AppFunctionRegistration object that can be used to unregister the function.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the provided functionIdentifier is not declared in the app's application-level XML resources or if an activity-scoped function is registered from a non-Activity context.
java.lang.IllegalStateException if a duplicate function is already registered (see AppFunctionMetadata.getScope), or if not called from android.app.Activity or android.app.Service contexts.

registerAppFunctions

Added in API level 37
fun registerAppFunctions(requests: MutableList<RegisterAppFunctionRequest!>): AppFunctionRegistration

Registers several AppFunction implementations at once, sharing a single lifecycle.

This is a more efficient alternative to calling registerAppFunction multiple times.

Behavior and Lifecycle

Each function registered through this method follows the same execution and lifecycle rules as those registered with registerAppFunction.

Batch Operation and Atomicity

The registration is atomic: either all functions in the provided list are registered successfully, or none are. If any function in the list fails validation (e.g., its is already registered or not declared in the manifest), this method will throw an exception, and no functions from the batch will be registered. Each function in the request follows the scoping rules declared in the app's XML resources.

A single AppFunctionRegistration object is returned, which can be used to unregister the entire batch of functions with one call.

Parameters
requests MutableList<RegisterAppFunctionRequest!>: A list of RegisterAppFunctionRequest objects, each specifying a function to be registered.
This value cannot be null.
Return
AppFunctionRegistration A single AppFunctionRegistration object that can be used to unregister all the functions in the batch with one call.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if any RegisterAppFunctionRequest.getFunctionIdentifier is not declared in the app's application-level XML assets or the requests list is empty.
java.lang.IllegalStateException if any function in the requests list is already registered by this app.

searchAppFunctions

Added in API level 37
fun searchAppFunctions(
    searchSpec: AppFunctionSearchSpec, 
    executor: Executor, 
    callback: OutcomeReceiver<MutableList<AppFunctionMetadata!>!, Exception!>
): Unit

Searches app function AppFunctionMetadatas.

Note that the state is not guaranteed to be the latest, as metadata can change between request and execute times when apps are updated.

The calling app can search for:

  • Functions in its own package (no permission required).
  • When holding the Manifest.permission.EXECUTE_APP_FUNCTIONS or android.Manifest.permission#DISCOVER_APP_FUNCTIONS or android.Manifest.permission#EXECUTE_APP_FUNCTIONS_SYSTEM permission - functions in other packages that it is allowed to query via android.content.pm.PackageManager#canPackageQuery.

See getAppFunctionStates and getAppFunctionActivityStates on how to retrieve the runtime state of app functions.

See observeAppFunctions for observing changes to app functions' AppFunctionMetadata and AppFunctionStates.

Parameters
searchSpec AppFunctionSearchSpec: The spec of app functions to search for.
This value cannot be null.
executor Executor: The executor to run the callback.
This value cannot be null.
Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.
callback OutcomeReceiver<MutableList<AppFunctionMetadata!>!, Exception!>: The callback to receive the search results.
This value cannot be null.

setAppFunctionEnabled

Added in API level 36
fun setAppFunctionEnabled(
    functionIdentifier: String, 
    newEnabledState: Int, 
    executor: Executor, 
    callback: OutcomeReceiver<Void!, Exception!>
): Unit

Sets the enabled state of the app function owned by the calling package.

Important: This method only applies to functions backed by an AppFunctionService. It cannot be used to modify the state of functions registered at runtime. For runtime-registered app functions, use registerAppFunction to register them and AppFunctionRegistration.unregister to unregister them instead.

Parameters
functionIdentifier String: the identifier of the app function to enable (unique within the calling package).
This value cannot be null.
newEnabledState Int: the new state of the app function.
Value is one of the following:
executor Executor: the executor to run the callback.
This value cannot be null.
callback OutcomeReceiver<Void!, Exception!>: the callback to receive the result of the function enablement. Can return IllegalArgumentException if the function is not found or the caller does not have access to it.
This value cannot be null.
Exceptions
java.lang.IllegalArgumentException if the function is runtime-registered.