AppFunctionManager

const 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.

const val APP_FUNCTION_STATE_DISABLED: Int

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

const val APP_FUNCTION_STATE_ENABLED: Int

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

fun getInstance(context: Context): AppFunctionManager?

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.

@RequiresPermission(value = "android.permission.EXECUTE_APP_FUNCTIONS", conditional = true)
suspend fun executeAppFunction(request: ExecuteAppFunctionRequest): ExecuteAppFunctionResponse

Execute the app function.

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

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

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.

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

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
inline fun <T : Any> getHandleAppFunctionRequestAdapter(): HandleAppFunctionRequestAdapter<T>

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
fun <T : Any> getHandleAppFunctionRequestAdapter(interfaceClass: Class<T>): HandleAppFunctionRequestAdapter<T>

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
suspend fun handleAppFunction(request: HandleAppFunctionRequest): Nothing

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
suspend fun handleAppFunction(
    functionIdentifier: String,
    appFunction: SuspendingAppFunction
): Nothing

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
suspend fun handleAppFunctions(requests: List<HandleAppFunctionRequest>): Nothing

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.

@RequiresPermission(anyOf = ["android.permission.EXECUTE_APP_FUNCTIONS", "android.permission.DISCOVER_APP_FUNCTIONS", "android.permission.EXECUTE_APP_FUNCTIONS_SYSTEM"], conditional = true)
fun observeAppFunctions(): Flow<ObserveAppFunctionsEvent>

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.

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
fun registerAppFunction(
    functionIdentifier: String,
    executor: Executor,
    appFunction: CallbackAppFunction
): 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 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).

@RequiresApi(value = 37)
@ExperimentalAppFunctionsApi
fun registerAppFunctions(requests: List<RegisterAppFunctionRequest>): AppFunctionRegistration

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.

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

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).

• Functions in other packages that it is allowed to query via android.content.pm.PackageManager.canPackageQuery when holding the android.Manifest.permission.EXECUTE_APP_FUNCTIONS permission.

• Functions in other packages that it is allowed to query via android.content.pm.PackageManager.canPackageQuery when holding either the android.Manifest.permission.EXECUTE_APP_FUNCTIONS_SYSTEM or android.Manifest.permission.DISCOVER_APP_FUNCTIONS permission on Build.VERSION_CODES.CINNAMON_BUN and above.

suspend fun setAppFunctionEnabled(functionId: String, newEnabledState: Int): Unit

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.