Added in API level 36

Summary: Constants | Methods | Inherited Methods

AppFunctionManager

Kotlin |Java

public final class AppFunctionManager
extends Object

java.lang.Object
↳	android.app.appfunctions.AppFunctionManager

Provides access to App Functions. App Functions is currently a beta/experimental preview feature.

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 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(ExecuteAppFunctionRequest, Executor, CancellationSignal, OutcomeReceiver) with the request to execute the app function. Callers need the android.permission.EXECUTE_APP_FUNCTIONS 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(ExecuteAppFunctionRequest, Executor, CancellationSignal, OutcomeReceiver) with the functionIdentifier of the chosen function.

Summary

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

Public methods
`void`	`executeAppFunction(ExecuteAppFunctionRequest request, Executor executor, CancellationSignal cancellationSignal, OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback)` Executes the app function.
`void`	`isAppFunctionEnabled(String functionIdentifier, Executor executor, OutcomeReceiver<Boolean, Exception> callback)` Returns a boolean through a callback, indicating whether the app function is enabled.
`void`	`isAppFunctionEnabled(String functionIdentifier, String targetPackage, Executor executor, OutcomeReceiver<Boolean, Exception> callback)` Returns a boolean through a callback, indicating whether the app function is enabled.
`void`	`setAppFunctionEnabled(String functionIdentifier, int newEnabledState, Executor executor, OutcomeReceiver<Void, Exception> callback)` Sets the enabled state of the app function owned by the calling package.

Inherited methods

From class


        
          java.lang.Object

`Object`	`clone()` Creates and returns a copy of this object.
`boolean`	`equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void`	`finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>`	`getClass()` Returns the runtime class of this `Object`.
`int`	`hashCode()` Returns a hash code value for the object.
`final void`	`notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void`	`notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String`	`toString()` Returns a string representation of the object.
`final void`	`wait(long timeoutMillis, int nanos)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait(long timeoutMillis)` Causes the current thread to wait until it is awakened, typically by being notified or interrupted, or until a certain amount of real time has elapsed.
`final void`	`wait()` Causes the current thread to wait until it is awakened, typically by being notified or interrupted.

Constants

APP_FUNCTION_STATE_DEFAULT

Added in API level 36

public static final int APP_FUNCTION_STATE_DEFAULT

The default state of the app function. Call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this to reset enabled state to the default value.

Constant Value: 0 (0x00000000)

APP_FUNCTION_STATE_DISABLED

Added in API level 36

public static final int APP_FUNCTION_STATE_DISABLED

The app function is disabled. To disable an app function, call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this value.

Constant Value: 2 (0x00000002)

APP_FUNCTION_STATE_ENABLED

Added in API level 36

public static final int APP_FUNCTION_STATE_ENABLED

The app function is enabled. To enable an app function, call setAppFunctionEnabled(String, int, Executor, OutcomeReceiver) with this value.

Constant Value: 1 (0x00000001)

Public methods

executeAppFunction

Added in API level 36

public void executeAppFunction (ExecuteAppFunctionRequest request, 
                Executor executor, 
                CancellationSignal cancellationSignal, 
                OutcomeReceiver<ExecuteAppFunctionResponse, AppFunctionException> callback)

Executes the app function.

Note: Applications can execute functions they define. To execute functions defined in another component, apps would need to have the permission 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`: 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`, the execution result will contain `AppFunctionException.ERROR_DENIED`. If the caller only has `android.permission.EXECUTE_APP_FUNCTIONS`, 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 36

public void isAppFunctionEnabled (String functionIdentifier, 
                Executor executor, 
                OutcomeReceiver<Boolean, Exception> callback)

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`: the callback to receive the function enabled check result This value cannot be `null`.

isAppFunctionEnabled

Added in API level 36

public void isAppFunctionEnabled (String functionIdentifier, 
                String targetPackage, 
                Executor executor, 
                OutcomeReceiver<Boolean, Exception> callback)

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 the Manifest.permission.EXECUTE_APP_FUNCTIONS 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`: the callback to receive the function enabled check result This value cannot be `null`.

setAppFunctionEnabled

Added in API level 36

public void setAppFunctionEnabled (String functionIdentifier, 
                int newEnabledState, 
                Executor executor, 
                OutcomeReceiver<Void, Exception> callback)

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 `APP_FUNCTION_STATE_DEFAULT`, `APP_FUNCTION_STATE_ENABLED`, or `APP_FUNCTION_STATE_DISABLED`
`executor`	`Executor`: the executor to run the callback This value cannot be `null`.
`callback`	`OutcomeReceiver`: the callback to receive the result of the function enablement. The call was successful if no exception was thrown. This value cannot be `null`.