AppFunctionManager

public final class AppFunctionManager

Provides access to interact with App Functions. This is a backward-compatible wrapper for the platform class android.app.appfunctions.AppFunctionManager.

Summary

Constants
static final int

The default state of the app function.
static final int

The app function is disabled.
static final int

The app function is enabled.

Public methods
final @NonNull ExecuteAppFunctionResponse
@RequiresPermission(value = "android.permission.EXECUTE_APP_FUNCTIONS", conditional = true)
executeAppFunction(@NonNull ExecuteAppFunctionRequest request)

Execute the app function.
final @NonNull List<@NonNull AppFunctionActivityState>
@RequiresApi(value = 37)
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
getAppFunctionActivityStates(
    @NonNull Set<@NonNull AppFunctionActivityId> activityIds
)

Retrieves the registered app functions for the specified activities.
final @NonNull List<@NonNull AppFunctionState>
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
getAppFunctionStates(
    @NonNull List<@NonNull AppFunctionName> appFunctionNames
)

Retrieves the runtime state of the specified app functions.
final @NonNull HandleAppFunctionRequestAdapter<@NonNull T>

Returns a HandleAppFunctionRequestAdapter for an interface annotated with AppFunctionSignature.
final @NonNull HandleAppFunctionRequestAdapter<@NonNull T>

Returns a HandleAppFunctionRequestAdapter for an interface annotated with AppFunctionSignature.
static final AppFunctionManager

Gets an instance of AppFunctionManager if the AppFunction feature is supported.
final @NonNull Void

Registers a runtime implementation of an app function bound to the calling coroutine's lifecycle.
final @NonNull Void
@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
handleAppFunction(
    @NonNull String functionIdentifier,
    @NonNull SuspendingAppFunction appFunction
)

Registers a runtime implementation of an app function bound to the calling coroutine's lifecycle.
final @NonNull Void

Registers multiple runtime implementations of app functions bound to the calling coroutine's lifecycle.
final @NonNull Flow<@NonNull ObserveAppFunctionsEvent>
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
observeAppFunctions()

Observes changes to app functions within packages the caller can query.
final @NonNull AppFunctionRegistration
@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
registerAppFunction(
    @NonNull String functionIdentifier,
    @NonNull Executor executor,
    @NonNull CallbackAppFunction appFunction
)

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

Registers several CallbackAppFunction implementations at once, sharing a single lifecycle.
final @NonNull List<@NonNull AppFunctionMetadata>
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
searchAppFunctions(@NonNull AppFunctionSearchSpec searchSpec)

Searches app function AppFunctionMetadatas.
final void
setAppFunctionEnabled(@NonNull String functionId, int newEnabledState)

Sets newEnabledState to an app function functionId owned by the calling package.

Constants

APP_FUNCTION_STATE_DEFAULT

public static final int APP_FUNCTION_STATE_DEFAULT

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

APP_FUNCTION_STATE_DISABLED

public static final int APP_FUNCTION_STATE_DISABLED

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

APP_FUNCTION_STATE_ENABLED

public static final int APP_FUNCTION_STATE_ENABLED

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

Public methods

executeAppFunction

@RequiresPermission(value = "android.permission.EXECUTE_APP_FUNCTIONS", conditional = true)
public final @NonNull ExecuteAppFunctionResponse executeAppFunction(@NonNull ExecuteAppFunctionRequest request)

Execute the app function.

This method matches the platform behavior defined in android.app.appfunctions.AppFunctionManager.executeAppFunction.

Parameters
@NonNull ExecuteAppFunctionRequest request

the app function details and the arguments.
Returns
@NonNull ExecuteAppFunctionResponse

the result of the attempt to execute the function.

getAppFunctionActivityStates

@RequiresApi(value = 37)
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
public final @NonNull List<@NonNull AppFunctionActivityState> getAppFunctionActivityStates(
    @NonNull Set<@NonNull AppFunctionActivityId> activityIds
)

Retrieves the registered app functions for the specified activities.

Each AppFunctionActivityState contains the set of registered AppFunctionNames associated with a requested android.app.appfunctions.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 android.app.appfunctions.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
@NonNull Set<@NonNull AppFunctionActivityId> activityIds

The set of activity IDs to retrieve function states for.
Returns
@NonNull List<@NonNull AppFunctionActivityState>

the AppFunctionActivityStates of the given android.app.appfunctions.AppFunctionActivityIds.
See also
getAppFunctionActivityId

getAppFunctionStates

@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
public final @NonNull List<@NonNull AppFunctionState> getAppFunctionStates(
    @NonNull List<@NonNull AppFunctionName> appFunctionNames
)

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 android.app.appfunctions.AppFunctionManager.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
@NonNull List<@NonNull AppFunctionName> appFunctionNames

The names of the app functions to request the state for.
Returns
@NonNull List<@NonNull AppFunctionState>

the AppFunctionStates of the specified app functions.

getHandleAppFunctionRequestAdapter

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull HandleAppFunctionRequestAdapter<@NonNull T> <T extends Object> getHandleAppFunctionRequestAdapter()

Returns a HandleAppFunctionRequestAdapter for an interface annotated with AppFunctionSignature.

Retrieves a generated HandleAppFunctionRequestAdapter that bridges ExecuteAppFunctionRequest and ExecuteAppFunctionResponse with the strongly-typed signature of the interface T. Because the method uses reflection under the hood to instantiate the adapter, we recommend loading it in advance to avoid runtime latency.

This adapter allows wrapping a concrete implementation of the interface into a HandleAppFunctionRequest. The resulting request can then be registered using handleAppFunction or handleAppFunctions.

Parameters
<T extends Object>

The interface annotated with AppFunctionSignature.
Returns
@NonNull HandleAppFunctionRequestAdapter<@NonNull T>

The HandleAppFunctionRequestAdapter for the interface T.
Throws
IllegalArgumentException

if the adapter class for T cannot be found or instantiated.
See also
getHandleAppFunctionRequestAdapter

(Class)

getHandleAppFunctionRequestAdapter

Added in 1.0.0-alpha12
@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull HandleAppFunctionRequestAdapter<@NonNull T> <T extends Object> getHandleAppFunctionRequestAdapter(
    @NonNull Class<@NonNull T> interfaceClass
)

Returns a HandleAppFunctionRequestAdapter for an interface annotated with AppFunctionSignature.

Retrieves a generated HandleAppFunctionRequestAdapter that bridges ExecuteAppFunctionRequest and ExecuteAppFunctionResponse with the strongly-typed signature of the passed interface. Because the method uses reflection under the hood to instantiate the adapter, we recommend loading it in advance to avoid runtime latency.

This adapter allows wrapping a concrete implementation of the passed interface into a HandleAppFunctionRequest. The resulting request can then be registered using handleAppFunction or handleAppFunctions.

Parameters
@NonNull Class<@NonNull T> interfaceClass

The interface class annotated with AppFunctionSignature.
Returns
@NonNull HandleAppFunctionRequestAdapter<@NonNull T>

The HandleAppFunctionRequestAdapter for the interfaceClass.
Throws
IllegalArgumentException

if the adapter class for interfaceClass cannot be found or instantiated.

getInstance

Added in 1.0.0-alpha12
public static final AppFunctionManager getInstance(@NonNull Context context)

Gets an instance of AppFunctionManager if the AppFunction feature is supported.

The AppFunction feature is supported if the calling user is not a profile and either of the following conditions is met:

  • SDK version is 36 or higher.

  • SDK version is 34 or higher, and the device implements the App Function extension ibrary.

Returns
AppFunctionManager

an instance of AppFunctionManager if the AppFunction feature is supported or null.

handleAppFunction

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull Void handleAppFunction(@NonNull HandleAppFunctionRequest request)

Registers a runtime implementation of an app function bound to the calling coroutine's lifecycle.

This method suspends and keeps the function registered until the calling coroutine scope is cancelled. Under the hood, it delegates the registration to registerAppFunction and ensures it is unregistered when the coroutine is cancelled.

For a callback-based API that does not require a coroutine scope, see registerAppFunction.

Parameters
@NonNull HandleAppFunctionRequest request

The request containing the function identifier and implementation.

handleAppFunction

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull Void handleAppFunction(
    @NonNull String functionIdentifier,
    @NonNull SuspendingAppFunction appFunction
)

Registers a runtime implementation of an app function bound to the calling coroutine's lifecycle.

This method suspends and keeps the function registered until the calling coroutine scope is cancelled. Under the hood, it delegates the registration to registerAppFunction and ensures it is unregistered when the coroutine is cancelled.

For a callback-based API that does not require a coroutine scope, see registerAppFunction.

Parameters
@NonNull String functionIdentifier

The unique identifier of the app function.
@NonNull SuspendingAppFunction appFunction

The implementation of the app function to handle execution requests.

handleAppFunctions

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull Void handleAppFunctions(
    @NonNull List<@NonNull HandleAppFunctionRequest> requests
)

Registers multiple runtime implementations of app functions bound to the calling coroutine's lifecycle.

This method suspends and keeps the functions registered until the calling coroutine scope is cancelled. Under the hood, it delegates the registration to registerAppFunctions and ensures they are unregistered when the coroutine is cancelled.

For a callback-based API that does not require a coroutine scope, see registerAppFunctions.

Parameters
@NonNull List<@NonNull HandleAppFunctionRequest> requests

The list of requests containing the function identifiers and implementations.

observeAppFunctions

Added in 1.0.0-alpha12
@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
public final @NonNull Flow<@NonNull ObserveAppFunctionsEvent> observeAppFunctions()

Observes changes to app functions within packages the caller can query.

The returned flow only emits changes that occur after collection starts. Any changes before collection are not reported.

An example usage flow is:

  1. Start collecting from the Flow to monitor app function changes.

  2. Call searchAppFunctions and getAppFunctionStates to get the initial list of app functions and their states.

  3. When receiving ObserveAppFunctionsEvent.MetadataChanged, call searchAppFunctions with a AppFunctionSearchSpec that matches the changed packages to get the updated metadata.

  4. When receiving ObserveAppFunctionsEvent.StatesChanged, call getAppFunctionStates with the list of androidx.appfunctions.metadata.AppFunctionNames matching the changed functions to get the updated states. Note that this is guaranteed to trigger after ObserveAppFunctionsEvent.MetadataChanged for new functions or functions that also changed states. There is no need to call getAppFunctionStates when receiving ObserveAppFunctionsEvent.MetadataChanged.

Returns
@NonNull Flow<@NonNull ObserveAppFunctionsEvent>

a Flow emitting ObserveAppFunctionsEvents representing metadata or state changes

registerAppFunction

Added in 1.0.0-alpha12
@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull AppFunctionRegistration registerAppFunction(
    @NonNull String functionIdentifier,
    @NonNull Executor executor,
    @NonNull CallbackAppFunction appFunction
)

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 CallbackAppFunction.onExecuteAppFunction method of the provided implementation, as long as the process registering it is not frozen, and the android.content.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 androidx.appfunctions.metadata.AppFunctionMetadata for details on the XML schema (your_app_functions.xml in the example below).

Example manifest declaration:

<application ...>
  <property
      android:name="android.app.appfunctions"
      android:value="your_app_functions.xml" />
  ...
</application>

Function implementations can only be registered from android.app.Activity or android.app.Service contexts. If registering from an android.app.Activity, strongly consider androidx.appfunctions.metadata.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 androidx.appfunctions.metadata.AppFunctionMetadata.scope 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 CallbackAppFunction 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
@NonNull String functionIdentifier

The unique identifier for the function, which must match an entry in the app's XML resource declarations.
@NonNull Executor executor

The Executor on which the function will be invoked and the incoming ExecuteAppFunctionRequest will be validated (verifying that the incoming platform request aligns with the declared androidx.appfunctions.metadata.AppFunctionMetadata).
@NonNull CallbackAppFunction appFunction

The CallbackAppFunction implementation to be executed when the function is triggered.
Returns
@NonNull AppFunctionRegistration

A AppFunctionRegistration object that can be used to unregister the function.
Throws
IllegalStateException

if a duplicate function is already registered (see androidx.appfunctions.metadata.AppFunctionMetadata.scope) for the same scope, or if not called from android.app.Activity or android.app.Service contexts.
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.

registerAppFunctions

Added in 1.0.0-alpha12
@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
public final @NonNull AppFunctionRegistration registerAppFunctions(
    @NonNull List<@NonNull RegisterAppFunctionRequest> requests
)

Registers several CallbackAppFunction 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., it 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
@NonNull List<@NonNull RegisterAppFunctionRequest> requests

A list of RegisterAppFunctionRequest objects, each specifying a function to be registered.
Returns
@NonNull AppFunctionRegistration

A single AppFunctionRegistration object that can be used to unregister all the functions in the batch with one call.
Throws
IllegalStateException

if any function in the requests list is already registered by this app.
IllegalArgumentException

if any RegisterAppFunctionRequest.functionIdentifier is not declared in the app's application-level XML assets or the requests list is empty.

searchAppFunctions

@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
public final @NonNull List<@NonNull AppFunctionMetadata> searchAppFunctions(@NonNull AppFunctionSearchSpec searchSpec)

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:

Parameters
@NonNull AppFunctionSearchSpec searchSpec

The spec of app functions to search for.

setAppFunctionEnabled

Added in 1.0.0-alpha12
public final void setAppFunctionEnabled(@NonNull String functionId, int newEnabledState)

Sets newEnabledState to an app function functionId owned by the calling package.

This method matches the platform behavior defined in android.app.appfunctions.AppFunctionManager.setAppFunctionEnabled.

Parameters
@NonNull String functionId

The identifier of the app function.
int newEnabledState

The new state of the app function.
Throws
IllegalArgumentException

If the functionId is not available.