ProviderEventsManager
interface ProviderEventsManager
Provides APIs for credential providers to participate in provider events, such as same-device credential transfer.
This manager supports two primary roles for credential transfer:
-
Importing (Client Role): A provider can initiate a flow to import credentials by calling
importCredentials. This will display a UI allowing the user to select another provider to import from. -
Exporting (Source Role): A provider must first register its ability to export credentials by calling
registerExport. Once registered, it will appear in the UI when other providers initiate an import flow.
Summary
Public companion functions |
|
|---|---|
ProviderEventsManager |
Creates a |
Public functions |
|
|---|---|
open suspend ProviderImportCredentialsResponse |
importCredentials(context: Context, request: ImportCredentialsRequest)Initiates a flow to import credentials from another credential provider. |
Unit |
importCredentialsAsync(Initiates a flow to import credentials from another credential provider. |
open suspend RegisterExportResponse |
registerExport(request: RegisterExportRequest)Registers the calling credential provider as a source for exporting credentials. |
Unit |
registerExportAsync(Registers the calling credential provider as a source for exporting credentials. |
Public companion functions
create
fun create(context: Context): ProviderEventsManager
Creates a ProviderEventsManager based on the given context.
| Parameters | |
|---|---|
context: Context |
the context with which the ProviderEventsManager should be associated |
Public functions
importCredentials
open suspend fun importCredentials(context: Context, request: ImportCredentialsRequest): ProviderImportCredentialsResponse
Initiates a flow to import credentials from another credential provider.
This method launches a provider selector UI, allowing the user to choose a source provider from a list of those registered via registerExport. The request is then forwarded to the selected provider.
Under the hood, this API facilitates the transfer by creating a temporary file in the caller's cache directory. The framework handles the file I/O, permissions, and cleanup, providing a seamless transfer medium between the two providers.
| Parameters | |
|---|---|
context: Context |
the activity context required to launch the UI. |
request: ImportCredentialsRequest |
the request detailing the credentials to be imported. |
| Returns | |
|---|---|
ProviderImportCredentialsResponse |
a |
| Throws | |
|---|---|
androidx.credentials.providerevents.exception.ImportCredentialsException |
on failure, with a subclass indicating the error type. |
importCredentialsAsync
fun importCredentialsAsync(
context: Context,
request: ImportCredentialsRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: CredentialManagerCallback<ProviderImportCredentialsResponse, ImportCredentialsException>
): Unit
Initiates a flow to import credentials from another credential provider.
This method launches a provider selector UI, allowing the user to choose a source provider from a list of those registered via registerExport. The request is then forwarded to the selected provider.
Under the hood, this API facilitates the transfer by creating a temporary file in the caller's cache directory. The framework handles the file I/O, permissions, and cleanup, providing a seamless transfer medium between the two providers.
| Parameters | |
|---|---|
context: Context |
the activity context required to launch the UI. |
request: ImportCredentialsRequest |
request the request detailing the credentials to be imported. |
cancellationSignal: CancellationSignal? |
an optional signal that allows for cancelling this call |
executor: Executor |
the callback will take place on this executor |
callback: CredentialManagerCallback<ProviderImportCredentialsResponse, ImportCredentialsException> |
the callback invoked when the request succeeds or fails |
registerExport
open suspend fun registerExport(request: RegisterExportRequest): RegisterExportResponse
Registers the calling credential provider as a source for exporting credentials.
Once registered, the provider's ExportEntry will be displayed in the provider selector UI when another provider initiates an importCredentials flow.
In addition to calling this method, a provider that wishes to export credentials must declare an [Activity] in its manifest that can handle the transfer request. This activity must have an intent filter configured with the following:
- An intent action of "androidx.identitycredentials.action.IMPORT_CREDENTIALS"
- A data element with a "content" scheme
The framework will invoke this activity with an intent containing a content URI, which serves as the medium for transferring the credential data. The activity can retrieve the request from the intent by calling IntentHandler.retrieveProviderImportCredentialsRequest. In addition to the ImportCredentialsRequest, the ProviderImportCredentialsRequest contains a few security measures. The importer's CallingAppInfo is provided to verify the importer. The 'credId' is provided to validate the selected ExportEntry.
After the activity processes the request, the activity should return the ImportCredentialsResponse through the 'uri' of ProviderImportCredentialsRequest to successfully return the credentials or set an exception by calling IntentHandler.setImportCredentialsException.
| Parameters | |
|---|---|
request: RegisterExportRequest |
the request containing the provider data to register |
| Returns | |
|---|---|
RegisterExportResponse |
a |
| Throws | |
|---|---|
androidx.credentials.providerevents.exception.RegisterExportException |
if the registration fails. |
registerExportAsync
fun registerExportAsync(
request: RegisterExportRequest,
cancellationSignal: CancellationSignal?,
executor: Executor,
callback: CredentialManagerCallback<RegisterExportResponse, RegisterExportException>
): Unit
Registers the calling credential provider as a source for exporting credentials.
Once registered, the provider's ExportEntry will be displayed in the provider selector UI when another provider initiates an importCredentials flow.
In addition to calling this method, a provider that wishes to export credentials must declare an [Activity] in its manifest that can handle the transfer request. This activity must have an intent filter configured with the following:
- An intent action of "androidx.identitycredentials.action.IMPORT_CREDENTIALS"
- A data element with a "content" scheme
The framework will invoke this activity with an intent containing a content URI, which serves as the medium for transferring the credential data. The activity can retrieve the request from the intent by calling IntentHandler.retrieveProviderImportCredentialsRequest. In addition to the ImportCredentialsRequest, the ProviderImportCredentialsRequest contains a few security measures. The importer's CallingAppInfo is provided to verify the importer. The 'credId' is provided to validate the selected ExportEntry.
After the activity processes the request, the activity should return the ImportCredentialsResponse through the 'uri' of ProviderImportCredentialsRequest to successfully return the credentials or set an exception by calling IntentHandler.setImportCredentialsException.
| Parameters | |
|---|---|
request: RegisterExportRequest |
the request containing the provider data to register |
cancellationSignal: CancellationSignal? |
an optional signal that allows for cancelling this call |
executor: Executor |
the callback will take place on this executor |
callback: CredentialManagerCallback<RegisterExportResponse, RegisterExportException> |
the callback invoked when the request succeeds or fails |