AppFunctionManager

Kotlin |Java

class AppFunctionManager

kotlin.Any
↳	android.app.appfunctions.AppFunctionManager

Provides access to app functions.

An app function is a piece of functionality that apps expose to the system for cross-app orchestration.

**Building App Functions:**

Most developers should build app functions through the AppFunctions SDK. This SDK library offers a more convenient and type-safe way to build app functions. The SDK provides predefined function schemas for common use cases and associated data classes for function parameters and return values. Apps only have to implement the provided interfaces. Internally, the SDK converts these data classes into ExecuteAppFunctionRequest.getParameters() and android.app.appfunctions.ExecuteAppFunctionResponse#getResultDocument().

**Discovering App Functions:**

When there is a package change or the device starts up, the metadata of available functions is indexed on-device by AppSearchManager. AppSearch stores the indexed information as an AppFunctionStaticMetadata document. This document contains the functionIdentifier and the schema information that the app function implements. This allows other apps and the app itself to discover these functions using the AppSearch search APIs. Visibility to this metadata document is based on the packages that have visibility to the app providing the app functions. AppFunction SDK provides a convenient way to achieve this and is the preferred method.

**Executing App Functions:**

To execute an app function, the caller app can retrieve the functionIdentifier from the AppFunctionStaticMetadata document and use it to build an ExecuteAppFunctionRequest. Then, invoke executeAppFunction with the request to execute the app function. Callers need the android.permission.EXECUTE_APP_FUNCTIONS or android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED permission to execute app functions from other apps. An app can always execute its own app functions and doesn't need these permissions. AppFunction SDK provides a convenient way to achieve this and is the preferred method.

**Example:**

An assistant app is trying to fulfill the user request "Save XYZ into my note". The assistant app should first list all available app functions as AppFunctionStaticMetadata documents from AppSearch. Then, it should identify an app function that implements the CreateNote schema. Finally, the assistant app can invoke executeAppFunction with the functionIdentifier of the chosen function.

Summary

Constants
static Int	`APP_FUNCTION_STATE_DEFAULT` The default state of the app function.
static Int	`APP_FUNCTION_STATE_DISABLED` The app function is disabled.
static Int	`APP_FUNCTION_STATE_ENABLED` The app function is enabled.

Public methods
Unit	`executeAppFunction(request: ExecuteAppFunctionRequest, executor: Executor, cancellationSignal: CancellationSignal, callback: OutcomeReceiver<ExecuteAppFunctionResponse!, AppFunctionException!>)` Executes the app function.
Unit	`isAppFunctionEnabled(functionIdentifier: String, targetPackage: String, executor: Executor, callback: OutcomeReceiver<Boolean!, Exception!>)` Returns a boolean through a callback, indicating whether the app function is enabled.
Unit	`isAppFunctionEnabled(functionIdentifier: String, executor: Executor, callback: OutcomeReceiver<Boolean!, Exception!>)` Returns a boolean through a callback, indicating whether the app function is enabled.
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 Baklava

static val APP_FUNCTION_STATE_DEFAULT: Int

The default state of the app function. Call setAppFunctionEnabled with this to reset enabled state to the default value.

Value: 0

APP_FUNCTION_STATE_DISABLED

Added in API level Baklava

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 Baklava

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 Baklava

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

Executes the app function.

Note: Applications can execute functions they define. To execute functions defined in another component, apps would need to have android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED or android.permission.EXECUTE_APP_FUNCTIONS.

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. If the calling app does not own the app function or does not have `android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED` or `android.permission.EXECUTE_APP_FUNCTIONS`, the execution result will contain `AppFunctionException.ERROR_DENIED`. If the caller only has `android.permission.EXECUTE_APP_FUNCTIONS` but the function requires `android.permission.EXECUTE_APP_FUNCTIONS_TRUSTED`, the execution result will contain `AppFunctionException.ERROR_DENIED` If the function requested for execution is disabled, then the execution result will contain `AppFunctionException.ERROR_DISABLED` If the cancellation signal is issued, the operation is cancelled and no response is returned to the caller. This value cannot be `null`.

isAppFunctionEnabled

Added in API level Baklava

fun isAppFunctionEnabled(
    functionIdentifier: String, 
    targetPackage: String, 
    executor: Executor, 
    callback: OutcomeReceiver<Boolean!, Exception!>
): Unit

Returns a boolean through a callback, indicating whether the app function is enabled.

This method can only check app functions owned by the caller, or those where the caller has visibility to the owner package and holds either the android.Manifest.permission#EXECUTE_APP_FUNCTIONS or android.Manifest.permission#EXECUTE_APP_FUNCTIONS_TRUSTED permission.

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

IllegalArgumentException, if the function is not found or the caller does not have access to it.

Parameters
`functionIdentifier`	String: the identifier of the app function to check (unique within the target package) and in most cases, these are automatically generated by the AppFunctions SDK 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 Baklava

fun isAppFunctionEnabled(
    functionIdentifier: String, 
    executor: Executor, 
    callback: OutcomeReceiver<Boolean!, Exception!>
): Unit

Returns a boolean through a callback, indicating whether the app function is enabled.

This method can only check app functions owned by the caller, unlike isAppFunctionEnabled(java.lang.String,java.lang.String,java.util.concurrent.Executor,android.os.OutcomeReceiver), which allows specifying a different target package.

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

IllegalArgumentException, if the function is not found or the caller does not have access to it.

Parameters
`functionIdentifier`	String: the identifier of the app function to check (unique within the target package) and in most cases, these are automatically generated by the AppFunctions SDK 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`.

setAppFunctionEnabled

Added in API level Baklava

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.

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

IllegalArgumentException, if the function is not found or the caller does not have access to it.

Parameters
`functionIdentifier`	String: the identifier of the app function to enable (unique within the calling package). In most cases, identifiers are automatically generated by the AppFunctions SDK This value cannot be `null`.
`newEnabledState`	Int: the new state of the app function Value is `android.app.appfunctions.AppFunctionManager#APP_FUNCTION_STATE_DEFAULT`, `android.app.appfunctions.AppFunctionManager#APP_FUNCTION_STATE_ENABLED`, or `android.app.appfunctions.AppFunctionManager#APP_FUNCTION_STATE_DISABLED`
`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. The call was successful if no exception was thrown. This value cannot be `null`.