AppFunctionManager

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

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
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:

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:

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:

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.