Skip to content

Most visited

Recently visited

navigation

AutofillService

public abstract class AutofillService
extends Service

java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ android.service.autofill.AutofillService


An AutofillService is a service used to automatically fill the contents of the screen on behalf of a given user - for more information about autofill, read Autofill Framework.

An AutofillService is only bound to the Android System for autofill purposes if:

  1. It requires the android.permission.BIND_AUTOFILL_SERVICE permission in its manifest.
  2. The user explicitly enables it using Android Settings (the ACTION_REQUEST_SET_AUTOFILL_SERVICE intent can be used to launch such Settings screen).

Basic usage

The basic autofill process is defined by the workflow below:

  1. User focus an editable View.
  2. View calls notifyViewEntered(android.view.View).
  3. A ViewStructure representing all views in the screen is created.
  4. The Android System binds to the service and calls onConnected().
  5. The service receives the view structure through the onFillRequest(FillRequest, CancellationSignal, FillCallback).
  6. The service replies through onSuccess(FillResponse).
  7. The Android System calls onDisconnected() and unbinds from the AutofillService.
  8. The Android System displays an UI affordance with the options sent by the service.
  9. The user picks an option.
  10. The proper views are autofilled.

This workflow was designed to minimize the time the Android System is bound to the service; for each call, it: binds to service, waits for the reply, and unbinds right away. Furthermore, those calls are considered stateless: if the service needs to keep state between calls, it must do its own state management (keeping in mind that the service's process might be killed by the Android System when unbound; for example, if the device is running low in memory).

Typically, the onFillRequest(FillRequest, CancellationSignal, FillCallback) will:

  1. Parse the view structure looking for autofillable views (for example, using getAutofillHints().
  2. Match the autofillable views with the user's data.
  3. Create a Dataset for each set of user's data that match those fields.
  4. Fill the dataset(s) with the proper AutofillIds and AutofillValues.
  5. Add the dataset(s) to the FillResponse passed to onSuccess(FillResponse).

For example, for a login screen with username and password views where the user only has one account in the service, the response could be:

 new FillResponse.Builder()
     .addDataset(new Dataset.Builder()
         .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer"))
         .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer"))
         .build())
     .build();
 

But if the user had 2 accounts instead, the response could be:

 new FillResponse.Builder()
     .addDataset(new Dataset.Builder()
         .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer"))
         .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer"))
         .build())
     .addDataset(new Dataset.Builder()
         .setValue(id1, AutofillValue.forText("flanders"), createPresentation("flanders"))
         .setValue(id2, AutofillValue.forText("OkelyDokelyDo"), createPresentation("password for flanders"))
         .build())
     .build();
 

If the service does not find any autofillable view in the view structure, it should pass null to onSuccess(FillResponse); if the service encountered an error processing the request, it should call onFailure(CharSequence). For performance reasons, it's paramount that the service calls either onSuccess(FillResponse) or onFailure(CharSequence) for each onFillRequest(FillRequest, CancellationSignal, FillCallback) received - if it doesn't, the request will eventually time out and be discarded by the Android System.

Saving user data

If the service is also interested on saving the data filled by the user, it must set a SaveInfo object in the FillResponse. See SaveInfo for more details and examples.

User authentication

The service can provide an extra degree of security by requiring the user to authenticate before an app can be autofilled. The authentication is typically required in 2 scenarios:

When using authentication, it is recommended to encrypt only the sensitive data and leave labels unencrypted, so they can be used on presentation views. For example, if the user has a home and a work address, the Home and Work labels should be stored unencrypted (since they don't have any sensitive data) while the address data per se could be stored in an encrypted storage. Then when the user chooses the Home dataset, the platform starts the authentication flow, and the service can decrypt the sensitive data.

The authentication mechanism can also be used in scenarios where the service needs multiple steps to determine the datasets that can fill a screen. For example, when autofilling a financial app where the user has accounts for multiple banks, the workflow could be:

  1. The first FillResponse contains datasets with the credentials for the financial app, plus a "fake" dataset whose presentation says "Tap here for banking apps credentials".
  2. When the user selects the fake dataset, the service displays a dialog with available banking apps.
  3. When the user select a banking app, the service replies with a new FillResponse containing the datasets for that bank.

Another example of multiple-steps dataset selection is when the service stores the user credentials in "vaults": the first response would contain fake datasets with the vault names, and the subsequent response would contain the app credentials stored in that vault.

Data partitioning

The autofillable views in a screen should be grouped in logical groups called "partitions". Typical partitions are:

  • Credentials (username/email address, password).
  • Address (street, city, state, zip code, etc).
  • Payment info (credit card number, expiration date, and verification code).

For security reasons, when a screen has more than one partition, it's paramount that the contents of a dataset do not spawn multiple partitions, specially when one of the partitions contains data that is not specific to the application being autofilled. For example, a dataset should not contain fields for username, password, and credit card information. The reason for this rule is that a malicious app could draft a view structure where the credit card fields are not visible, so when the user selects a dataset from the username UI, the credit card info is released to the application without the user knowledge. Similarly, it's recommended to always protect a dataset that contains sensitive information by requiring dataset authentication (see setAuthentication(android.content.IntentSender)), and to include info about the "primary" field of the partition in the custom presentation for "secondary" fields — that would prevent a malicious app from getting the "primary" fields without the user realizing they're being released (for example, a malicious app could have fields for a credit card number, verification code, and expiration date crafted in a way that just the latter is visible; by explicitly indicating the expiration date is related to a given credit card number, the service would be providing a visual clue for the users to check what would be released upon selecting that field).

When the service detects that a screen has multiple partitions, it should return a FillResponse with just the datasets for the partition that originated the request (i.e., the partition that has the AssistStructure.ViewNode whose isFocused() returns true); then if the user selects a field from a different partition, the Android System will make another onFillRequest(FillRequest, CancellationSignal, FillCallback) call for that partition, and so on.

Notice that when the user autofill a partition with the data provided by the service and the user did not change these fields, the autofilled value is sent back to the service in the subsequent calls (and can be obtained by calling getAutofillValue()). This is useful in the cases where the service must create datasets for a partition based on the choice made in a previous partition. For example, the 1st response for a screen that have credentials and address partitions could be:

 new FillResponse.Builder()
     .addDataset(new Dataset.Builder() // partition 1 (credentials)
         .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer"))
         .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer"))
         .build())
     .addDataset(new Dataset.Builder() // partition 1 (credentials)
         .setValue(id1, AutofillValue.forText("flanders"), createPresentation("flanders"))
         .setValue(id2, AutofillValue.forText("OkelyDokelyDo"), createPresentation("password for flanders"))
         .build())
     .setSaveInfo(new SaveInfo.Builder(SaveInfo.SAVE_DATA_TYPE_PASSWORD,
         new AutofillId[] { id1, id2 })
             .build())
     .build();
 

Then if the user selected flanders, the service would get a new onFillRequest(FillRequest, CancellationSignal, FillCallback) call, with the values of the fields id1 and id2 prepopulated, so the service could then fetch the address for the Flanders account and return the following FillResponse for the address partition:

 new FillResponse.Builder()
     .addDataset(new Dataset.Builder() // partition 2 (address)
         .setValue(id3, AutofillValue.forText("744 Evergreen Terrace"), createPresentation("744 Evergreen Terrace")) // street
         .setValue(id4, AutofillValue.forText("Springfield"), createPresentation("Springfield")) // city
         .build())
     .setSaveInfo(new SaveInfo.Builder(SaveInfo.SAVE_DATA_TYPE_PASSWORD | SaveInfo.SAVE_DATA_TYPE_ADDRESS,
         new AutofillId[] { id1, id2 }) // username and password
              .setOptionalIds(new AutofillId[] { id3, id4 }) // state and zipcode
             .build())
     .build();
 

When the service returns multiple FillResponse, the last one overrides the previous; that's why the SaveInfo in the 2nd request above has the info for both partitions.

Package verification

When autofilling app-specific data (like username and password), the service must verify the authenticity of the request by obtaining all signing certificates of the app being autofilled, and only fulfilling the request when they match the values that were obtained when the data was first saved — such verification is necessary to avoid phishing attempts by apps that were sideloaded in the device with the same package name of another app. Here's an example on how to achieve that by hashing the signing certificates:

 private String getCertificatesHash(String packageName) throws Exception {
   PackageManager pm = mContext.getPackageManager();
   PackageInfo info = pm.getPackageInfo(packageName, PackageManager.GET_SIGNATURES);
   ArrayList hashes = new ArrayList<>(info.signatures.length);
   for (Signature sig : info.signatures) {
     byte[] cert = sig.toByteArray();
     MessageDigest md = MessageDigest.getInstance("SHA-256");
     md.update(cert);
     hashes.add(toHexString(md.digest()));
   }
   Collections.sort(hashes);
   StringBuilder hash = new StringBuilder();
   for (int i = 0; i < hashes.size(); i++) {
     hash.append(hashes.get(i));
   }
   return hash.toString();
 }
 

If the service did not store the signing certificates data the first time the data was saved — for example, because the data was created by a previous version of the app that did not use the Autofill Framework — the service should warn the user that the authenticity of the app cannot be confirmed (see an example on how to show such warning in the Web security section below), and if the user agrees, then the service could save the data from the signing ceriticates for future use.

Ignoring views

If the service find views that cannot be autofilled (for example, a text field representing the response to a Captcha challenge), it should mark those views as ignored by calling setIgnoredIds(AutofillId) so the system does not trigger a new onFillRequest(FillRequest, CancellationSignal, FillCallback) when these views are focused.

Web security

When handling autofill requests that represent web pages (typically view structures whose root's getClassName() is a WebView), the service should take the following steps to verify if the structure can be autofilled with the data associated with the app requesting it:

  1. Use the getWebDomain() to get the source of the document.
  2. Get the canonical domain using the Public Suffix List (see example below).
  3. Use Digital Asset Links to obtain the package name and certificate fingerprint of the package corresponding to the canonical domain.
  4. Make sure the certificate fingerprint matches the value returned by Package Manager (see "Package verification" section above).

Here's an example on how to get the canonical domain using Guava:

 private static String getCanonicalDomain(String domain) {
   InternetDomainName idn = InternetDomainName.from(domain);
   while (idn != null && !idn.isTopPrivateDomain()) {
     idn = idn.parent();
   }
   return idn == null ? null : idn.toString();
 }
 

If the association between the web domain and app package cannot be verified through the steps above, but the service thinks that it is appropriate to fill persisted credentials that are stored for the web domain, the service should warn the user about the potential data leakage first, and ask for the user to confirm. For example, the service could:

  1. Create a dataset that requires authentication to unlock.
  2. Include the web domain in the custom presentation for the dataset value.
  3. When the user selects that dataset, show a disclaimer dialog explaining that the app is requesting credentials for a web domain, but the service could not verify if the app owns that domain. If the user agrees, then the service can unlock the dataset.
  4. Similarly, when adding a SaveInfo object for the request, the service should include the above disclaimer in the setDescription(CharSequence).

This same procedure could also be used when the autofillable data is contained inside an IFRAME, in which case the WebView generates a new autofill context when a node inside the IFRAME is focused, with the root node containing the IFRAME's src attribute on getWebDomain(). A typical and legitimate use case for this scenario is a financial app that allows the user to login on different bank accounts. For example, a financial app my_financial_app could use a WebView that loads contents from banklogin.my_financial_app.com, which contains an IFRAME node whose src attribute is login.some_bank.com. When fulfilling that request, the service could add an authenticated dataset whose presentation displays "Username for some_bank.com" and "Password for some_bank.com". Then when the user taps one of these options, the service shows the disclaimer dialog explaining that selecting that option would release the login.some_bank.com credentials to the my_financial_app; if the user agrees, then the service returns an unlocked dataset with the some_bank.com credentials.

Note: The autofill service could also whitelist well-known browser apps and skip the verifications above, as long as the service can verify the authenticity of the browser app by checking its signing certificate.

Saving when data is split in multiple screens

Apps often split the user data in multiple screens in the same activity, specially in activities used to create a new user account. For example, the first screen asks for a username, and if the username is available, it moves to a second screen, which asks for a password.

It's tricky to handle save for autofill in these situations, because the autofill service must wait until the user enters both fields before the autofill save UI can be shown. But it can be done by following the steps below:

  1. In the first fill request, the service adds a client state bundle in the response, containing the autofill ids of the partial fields present in the screen.
  2. In the second fill request, the service retrieves the client state bundle, gets the autofill ids set in the previous request from the client state, and adds these ids and the FLAG_SAVE_ON_ALL_VIEWS_INVISIBLE to the SaveInfo used in the second response.
  3. In the save request, the service uses the proper fill contexts to get the value of each field (there is one fill context per fill request).

For example, in an app that uses 2 steps for the username and password fields, the workflow would be:

  // On first fill request
  AutofillId usernameId = // parse from AssistStructure;
  Bundle clientState = new Bundle();
  clientState.putParcelable("usernameId", usernameId);
  fillCallback.onSuccess(
    new FillResponse.Builder()
        .setClientState(clientState)
        .setSaveInfo(new SaveInfo
             .Builder(SaveInfo.SAVE_DATA_TYPE_USERNAME, new AutofillId[] {usernameId})
             .build())
        .build());

  // On second fill request
  Bundle clientState = fillRequest.getClientState();
  AutofillId usernameId = clientState.getParcelable("usernameId");
  AutofillId passwordId = // parse from AssistStructure
  clientState.putParcelable("passwordId", passwordId);
  fillCallback.onSuccess(
    new FillResponse.Builder()
        .setClientState(clientState)
        .setSaveInfo(new SaveInfo
             .Builder(SaveInfo.SAVE_DATA_TYPE_USERNAME | SaveInfo.SAVE_DATA_TYPE_PASSWORD,
                      new AutofillId[] {usernameId, passwordId})
             .setFlags(SaveInfo.FLAG_SAVE_ON_ALL_VIEWS_INVISIBLE)
             .build())
        .build());

  // On save request
  Bundle clientState = saveRequest.getClientState();
  AutofillId usernameId = clientState.getParcelable("usernameId");
  AutofillId passwordId = clientState.getParcelable("passwordId");
  List fillContexts = saveRequest.getFillContexts();

  FillContext usernameContext = fillContexts.get(0);
  ViewNode usernameNode = findNodeByAutofillId(usernameContext.getStructure(), usernameId);
  AutofillValue username = usernameNode.getAutofillValue().getTextValue().toString();

  FillContext passwordContext = fillContexts.get(1);
  ViewNode passwordNode = findNodeByAutofillId(passwordContext.getStructure(), passwordId);
  AutofillValue password = passwordNode.getAutofillValue().getTextValue().toString();

  save(username, password);

 

Summary

Constants

String SERVICE_INTERFACE

The Intent that must be declared as handled by the service.

String SERVICE_META_DATA

Name under which a AutoFillService component publishes information about itself.

Inherited constants

From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2

Public constructors

AutofillService()

Public methods

final FillEventHistory getFillEventHistory()

Gets the events that happened after the last onFillRequest(FillRequest, android.os.CancellationSignal, FillCallback) call.

final IBinder onBind(Intent intent)

Return the communication channel to the service.

void onConnected()

Called when the Android system connects to service.

void onCreate()

Called by the system when the service is first created.

void onDisconnected()

Called when the Android system disconnects from the service.

abstract void onFillRequest(FillRequest request, CancellationSignal cancellationSignal, FillCallback callback)

Called by the Android system do decide if a screen can be autofilled by the service.

abstract void onSaveRequest(SaveRequest request, SaveCallback callback)

Called when the user requests the service to save the contents of a screen.

Inherited methods

From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks2
From interface android.content.ComponentCallbacks

Constants

SERVICE_INTERFACE

added in API level 26
String SERVICE_INTERFACE

The Intent that must be declared as handled by the service. To be supported, the service must also require the BIND_AUTOFILL_SERVICE permission so that other applications can not abuse it.

Constant Value: "android.service.autofill.AutofillService"

SERVICE_META_DATA

added in API level 26
String SERVICE_META_DATA

Name under which a AutoFillService component publishes information about itself. This meta-data should reference an XML resource containing a <autofill-service> tag. This is a a sample XML file configuring an AutoFillService:

 <autofill-service
     android:settingsActivity="foo.bar.SettingsActivity"
     . . .
 />

Constant Value: "android.autofill"

Public constructors

AutofillService

added in API level 26
AutofillService ()

Public methods

getFillEventHistory

added in API level 26
FillEventHistory getFillEventHistory ()

Gets the events that happened after the last onFillRequest(FillRequest, android.os.CancellationSignal, FillCallback) call.

This method is typically used to keep track of previous user actions to optimize further requests. For example, the service might return email addresses in alphabetical order by default, but change that order based on the address the user picked on previous requests.

The history is not persisted over reboots, and it's cleared every time the service replies to a onFillRequest(FillRequest, CancellationSignal, FillCallback) by calling onSuccess(FillResponse) or onFailure(CharSequence) (if the service doesn't call any of these methods, the history will clear out after some pre-defined time). Hence, the service should call getFillEventHistory() before finishing the FillCallback.

Returns
FillEventHistory The history or null if there are no events.

onBind

added in API level 26
IBinder onBind (Intent intent)

Return the communication channel to the service. May return null if clients can not bind to the service. The returned IBinder is usually for a complex interface that has been described using aidl.

Note that unlike other application components, calls on to the IBinder interface returned here may not happen on the main thread of the process. More information about the main thread can be found in Processes and Threads.

Parameters
intent Intent: The Intent that was used to bind to this service, as given to Context.bindService. Note that any extras that were included with the Intent at that point will not be seen here.

Returns
IBinder Return an IBinder through which clients can call on to the service.

onConnected

added in API level 26
void onConnected ()

Called when the Android system connects to service.

You should generally do initialization here rather than in onCreate().

onCreate

added in API level 26
void onCreate ()

Called by the system when the service is first created. Do not call this method directly.

If you override this method you must call through to the superclass implementation.

onDisconnected

added in API level 26
void onDisconnected ()

Called when the Android system disconnects from the service.

At this point this service may no longer be an active AutofillService.

onFillRequest

added in API level 26
void onFillRequest (FillRequest request, 
                CancellationSignal cancellationSignal, 
                FillCallback callback)

Called by the Android system do decide if a screen can be autofilled by the service.

Service must call one of the FillCallback methods (like onSuccess(FillResponse) or onFailure(CharSequence)) to notify the result of the request.

Parameters
request FillRequest: the request to handle. See FillResponse for examples of multiple-sections requests.

This value must never be null.

cancellationSignal CancellationSignal: signal for observing cancellation requests. The system will use this to notify you that the fill result is no longer needed and you should stop handling this fill request in order to save resources.

This value must never be null.

callback FillCallback: object used to notify the result of the request.

This value must never be null.

onSaveRequest

added in API level 26
void onSaveRequest (SaveRequest request, 
                SaveCallback callback)

Called when the user requests the service to save the contents of a screen.

Service must call one of the SaveCallback methods (like onSuccess() or onFailure(CharSequence)) to notify the Android System of the result of the request.

If the service could not handle the request right away—for example, because it must launch an activity asking the user to authenticate first or because the network is down—the service could keep the request and reuse it later, but the service must call onSuccess() right away.

Note: To retrieve the actual value of fields input by the user, the service should call getAutofillValue(); if it calls getText() or other methods, there is no guarantee such method will return the most recent value of the field.

Parameters
request SaveRequest: the request to handle. See FillResponse for examples of multiple-sections requests.

This value must never be null.

callback SaveCallback: object used to notify the result of the request.

This value must never be null.

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Follow Google Developers on WeChat

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)