# AppFunctionSignature

Artifact: [androidx.appfunctions:appfunctions](https://developer.android.com/jetpack/androidx/releases/appfunctions) [View Source](https://cs.android.com/search?q=file:androidx/appfunctions/AppFunctionSignature.kt+class:androidx.appfunctions.AppFunctionSignature) Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

*** ** * ** ***


```
@ExperimentalAppFunctionsApi
@Retention(value = AnnotationRetention.BINARY)
@Target(allowedTargets = [AnnotationTarget.CLASS])
public annotation AppFunctionSignature
```

<br />

*** ** * ** ***

Marks a functional interface as an AppFunction signature for runtime registration using `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#handleAppFunction(kotlin.String,androidx.appfunctions.SuspendingAppFunction)` or `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#handleAppFunctions(kotlin.collections.List)`.

Interfaces annotated with `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature` allow the AppFunction compiler to generate metadata XML files and adapters that bridge the gap between platform requests and your Kotlin implementation.

## Usage Example: Step-by-Step Registration

### Step 1: Define the Signature

```
@AppFunctionSignature(
    scope = AppFunctionMetadata.SCOPE_ACTIVITY,
    appFunctionXmlFileName = "cart_functions",
    isDescribedByKDoc = true,
)
fun interface AddCurrentItemToCart {
    /** Adds the item currently shown on screen to the cart. Returns the new cart size. */
    suspend fun addToCart(quantity: Int): Int
}
```

### Step 2: Declare in AndroidManifest

Add a property tag in the `<application>` section. The value must include the `.xml` extension and match `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature#appFunctionXmlFileName()`.

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

### Step 3: Register the Implementation

Retrieve the adapter via `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#getHandleAppFunctionRequestAdapter(java.lang.Class)` and register your logic using `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#handleAppFunction(kotlin.String,androidx.appfunctions.SuspendingAppFunction)`:

```
val addToCartAppFunctionAdapter =
    appFunctionManager.getHandleAppFunctionRequestAdapter<AddCurrentItemToCart>()

coroutineScope.launch {
    appFunctionManager.handleAppFunction(
        addToCartAppFunctionAdapter.adapt { quantity ->
            val newCartSize = cart.addItem(quantity)
            newCartSize
        }
    )
}
```

## Best Practices

- **Adapter Caching:** Because `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#getHandleAppFunctionRequestAdapter(java.lang.Class)` uses reflection under the hood to instantiate the adapter, we recommend loading it in advance to avoid runtime latency.

- **Lifecycle Scope:** Since `handleAppFunction` is a suspending function, registration remains active only while its coroutine is running. We recommend using a scope that is alive between `onResume` and `onPause` (such as `Lifecycle.State.RESUMED`), or if registering within a composable, using a Compose side-effect (such as `LaunchedEffect` combined with `repeatOnLifecycle`).

## Generated Content

The AppFunction compiler processes classes marked with this annotation to generate two key artifacts:

- **An AppFunction XML file:** The compiler generates an XML file named after the `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature#appFunctionXmlFileName()` parameter. This file is placed in the application's `assets` directory and describes the AppFunctions exposed by this entry point:

```
<appfunctions>
     <appfunction>
         <id>com.example.AddCurrentItemToCart#addToCart</id>
         <scope>activity</scope>
         <parameters>...</parameters>
         <response>...</response>
     </appfunction>
 </appfunctions>
```

- **A concrete adapter class:** The compiler generates an implementation of `https://developer.android.com/reference/androidx/appfunctions/HandleAppFunctionRequestAdapter` in the same package as your annotated interface. This adapter maps the function string identifier to your interface call and handles request/response data conversions:

```
appFunctionManager.getHandleAppFunctionRequestAdapter<AddCurrentItemToCart>()
// Returns:
object : HandleAppFunctionRequestAdapter<AddCurrentItemToCart> {
    override val functionId: String = "com.example.AddCurrentItemToCart#addToCart"

    override fun adapt(implementation: AddCurrentItemToCart): HandleAppFunctionRequest =
        HandleAppFunctionRequest(functionId) { request: ExecuteAppFunctionRequest ->
            val quantity = request.functionParameters.getInt("quantity")
            val result = implementation.addToCart(quantity)
            val responseData =
                AppFunctionData.Builder("")
                    .setInt(
                        ExecuteAppFunctionResponse.Success.PROPERTY_RETURN_VALUE,
                        result,
                    )
                    .build()
            ExecuteAppFunctionResponse.Success(responseData)
        }
}
```

## Supported Types

See `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSerializable` for supported parameter and return types.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/appfunctions/HandleAppFunctionRequestAdapter` |   |
| `https://developer.android.com/reference/androidx/appfunctions/AppFunctionManager#getHandleAppFunctionRequestAdapter(java.lang.Class)` |   |

## Summary

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature#getAppFunctionXmlFileName()()` The name of the XML resource file containing the app function metadata definition represented by this signature. |
| `final int` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature#getScope()()` The scope of the app function. |
| `final boolean` | `https://developer.android.com/reference/androidx/appfunctions/AppFunctionSignature#isDescribedByKDoc()()` Whether to use the functional interface's abstract method KDoc as a function's description for the agent. |

## Public methods

### getAppFunctionXmlFileName

```
public final @NonNull String getAppFunctionXmlFileName()
```

The name of the XML resource file containing the app function metadata definition represented by this signature.

Multiple signatures can specify the same XML file name to group their metadata definitions into a single XML resource file.

### getScope

```
public final int getScope()
```

The scope of the app function.

The scope determines the function's lifecycle and uniqueness rules. Depending on the scope, there could be at most one or multiple functions registered in the system with the same `https://developer.android.com/reference/androidx/appfunctions/AppFunctionName`.

Possible values:

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#SCOPE_GLOBAL()`

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#SCOPE_ACTIVITY()`

### isDescribedByKDoc

Added in [1.0.0-rc01](https://developer.android.com/jetpack/androidx/releases/appfunctions#1.0.0-rc01)

```
public final boolean isDescribedByKDoc()
```

Whether to use the functional interface's abstract method KDoc as a function's description for the agent.

If set to `true`, the KDoc will be used to populate:

- The function's `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#description()` as the KDoc, excluding Kotlin's supported tags like `@param`, `@throws`.

- The function's parameters' `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionParameterMetadata#description()` from the KDoc's `@param` tags.

- The function's response's `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionResponseMetadata#description()` from the KDoc's `@return` tags.

Note: If an `https://developer.android.com/reference/androidx/appfunctions/AppFunctionInstruction` annotation is also present on the method, parameter, or return type, its value will take precedence and override the corresponding KDoc description.

Example:

```
@AppFunctionSignature(
    scope = AppFunctionMetadata.SCOPE_GLOBAL,
    appFunctionXmlFileName = "my_functions",
    isDescribedByKDoc = true
)
fun interface EnableCaptionsSignature {
    /**
     * Enables closed captions for media playback.
     *
     * @param language The language code for the captions (e.g., "en", "es").
     * @param showBackground Whether to display a dark background behind the caption text.
     * @return Whether the captions were successfully enabled.
*/
    suspend fun enableCaptions(language: String, showBackground: Boolean): Boolean
}
```

In this example:

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionMetadata#description()` will be: "Enables closed captions for media playback."

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionParameterMetadata#description()` for `language` will be: "The language code for the captions (e.g., "en", "es")."

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionParameterMetadata#description()` for `showBackground` will be: "Whether to display a dark background behind the caption text."

- `https://developer.android.com/reference/androidx/appfunctions/metadata/AppFunctionResponseMetadata#description()` will be: "Whether the captions were successfully enabled."