Dataset.Builder


public static final class Dataset.Builder
extends Object

java.lang.Object
   ↳ android.service.autofill.Dataset.Builder


A builder for Dataset objects. You must provide at least one value for a field or set an authentication intent.

Summary

Public constructors

Builder(RemoteViews presentation)

This constructor is deprecated. Use Builder(android.service.autofill.Presentations) instead.

Builder(Presentations presentations)

Creates a new builder.

Builder()

Creates a new builder for a dataset where each field will be visualized independently.

Public methods

Dataset build()

Creates a new Dataset instance.

Dataset.Builder setAuthentication(IntentSender authentication)

Triggers a custom UI before before autofilling the screen with the contents of this dataset.

Dataset.Builder setField(AutofillId id, Field field)

Sets the value of a field.

Dataset.Builder setField(String hint, Field field)

Adds a field to this Dataset with a specific type.

Dataset.Builder setFieldForAllHints(Field field)

Adds a field to this Dataset that is relevant to all applicable hints.

Dataset.Builder setId(String id)

Sets the id for the dataset so its usage can be tracked.

Dataset.Builder setInlinePresentation(InlinePresentation inlinePresentation, InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33. Use Builder(android.service.autofill.Presentations) instead.

Dataset.Builder setInlinePresentation(InlinePresentation inlinePresentation)

This method was deprecated in API level 33. Use Builder(android.service.autofill.Presentations) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, Pattern filter)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, Pattern filter, RemoteViews presentation, InlinePresentation inlinePresentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, RemoteViews presentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, Pattern filter, RemoteViews presentation, InlinePresentation inlinePresentation, InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, RemoteViews presentation, InlinePresentation inlinePresentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, RemoteViews presentation, InlinePresentation inlinePresentation, InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Dataset.Builder setValue(AutofillId id, AutofillValue value, Pattern filter, RemoteViews presentation)

This method was deprecated in API level 33. Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Inherited methods

Public constructors

Builder

Added in API level 26
public Builder (RemoteViews presentation)

This constructor is deprecated.
Use Builder(android.service.autofill.Presentations) instead.

Creates a new builder.

Parameters
presentation RemoteViews: The presentation used to visualize this dataset. This value cannot be null.

Builder

Added in API level 33
public Builder (Presentations presentations)

Creates a new builder.

Parameters
presentations Presentations: The presentations used to visualize this dataset. This value cannot be null.

Builder

Added in API level 26
public Builder ()

Creates a new builder for a dataset where each field will be visualized independently.

When using this constructor, a presentation must be provided for each field through setField(android.view.autofill.AutofillId, android.service.autofill.Field).

Public methods

build

Added in API level 26
public Dataset build ()

Creates a new Dataset instance.

You should not interact with this builder once this method is called.

Returns
Dataset The built dataset. This value cannot be null.

Throws
IllegalStateException if no field was set (through setField(android.view.autofill.AutofillId, android.service.autofill.Field)), or if build() was already called.

setAuthentication

Added in API level 26
public Dataset.Builder setAuthentication (IntentSender authentication)

Triggers a custom UI before before autofilling the screen with the contents of this dataset.

Note: Although the name of this method suggests that it should be used just for authentication flow, it can be used for other advanced flows; see AutofillService for examples.

This method is called when you need to provide an authentication UI for the data set. For example, when a data set contains credit card information (such as number, expiration date, and verification code), you can display UI asking for the verification code before filing in the data. Even if the data set is completely populated the system will launch the specified authentication intent and will need your approval to fill it in. Since the data set is "locked" until the user authenticates it, typically this data set name is masked (for example, "VISA....1234"). Typically you would want to store the data set labels non-encrypted and the actual sensitive data encrypted and not in memory. This allows showing the labels in the UI while involving the user if one of the items with these labels is chosen. Note that if you use sensitive data as a label, for example an email address, then it should also be encrypted.

When a user triggers autofill, the system launches the provided intent whose extras will have the screen content, and your client state. Once you complete your authentication flow you should set the activity result to Activity.RESULT_OK and provide the fully populated dataset or a fully-populated response by setting it to the AutofillManager.EXTRA_AUTHENTICATION_RESULT extra. If you provide a dataset in the result, it will replace the authenticated dataset and will be immediately filled in. An exception to this behavior is if the original dataset represents a pinned inline suggestion (i.e. any of the field in the dataset has a pinned inline presentation, see InlinePresentation#isPinned()), then the original dataset will not be replaced, so that it can be triggered as a pending intent again. If you provide a response, it will replace the current response and the UI will be refreshed. For example, if you provided credit card information without the CVV for the data set in the response then the returned data set should contain the CVV entry.

Note: Do not make the provided pending intent immutable by using PendingIntent.FLAG_IMMUTABLE as the platform needs to fill in the authentication arguments.

Parameters
authentication IntentSender: Intent to an activity with your authentication flow. This value may be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

See also:

setField

Added in API level 33
public Dataset.Builder setField (AutofillId id, 
                Field field)

Sets the value of a field. Before Android 13, this information could be provided using several overloaded setValue(...) methods. This method replaces those with a Builder pattern. For example, in the old workflow, the app sets a field would be:

  Dataset.Builder dataset = new Dataset.Builder();
  if (filter != null) {
      if (presentation != null) {
          if (inlinePresentation != null) {
              dataset.setValue(id, value, filter, presentation, inlinePresentation)
          } else {
              dataset.setValue(id, value, filter, presentation);
          }
      } else {
          dataset.setValue(id, value, filter);
      }
  } else {
      if (presentation != null) {
          if (inlinePresentation != null) {
              dataset.setValue(id, value, presentation, inlinePresentation)
          } else {
              dataset.setValue(id, value, presentation);
          }
      } else {
          dataset.setValue(id, value);
      }
  }
  

The new workflow would be:

 Field.Builder fieldBuilder = new Field.Builder();
 if (value != null) {
     fieldBuilder.setValue(value);
 }
 if (filter != null) {
     fieldBuilder.setFilter(filter);
 }
 Presentations.Builder presentationsBuilder = new Presentations.Builder();
 if (presentation != null) {
     presentationsBuilder.setMenuPresentation(presentation);
 }
 if (inlinePresentation != null) {
     presentationsBuilder.setInlinePresentation(inlinePresentation);
 }
 if (dialogPresentation != null) {
     presentationsBuilder.setDialogPresentation(dialogPresentation);
 }
 fieldBuilder.setPresentations(presentationsBuilder.build());
 dataset.setField(id, fieldBuilder.build());
 

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

field Field: the fill information about the field. This value may be null.

Returns
Dataset.Builder this builder.

Throws
IllegalStateException if build() was already called.

See also:

setField

Added in API level 34
public Dataset.Builder setField (String hint, 
                Field field)

Adds a field to this Dataset with a specific type. This is used to send back Field information when Autofilling with platform detections is on. Platform detections are on when receiving a populated list from FillRequest#getHints(). Populate every field/type known for this user for this app. For example, if getHints() contains "username" and "password", a new Dataset should be created that calls this method twice, one for the username, then another for the password (assuming the only one credential pair is found for the user). If a user has two credential pairs, then two Datasets should be created, and so on.

Parameters
hint String: An autofill hint returned from FillRequest.getHints(). This value cannot be null.

field Field: the fill information about the field. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called or this builder also contains AutofillId information

setFieldForAllHints

Added in API level 34
public Dataset.Builder setFieldForAllHints (Field field)

Adds a field to this Dataset that is relevant to all applicable hints. This is used to provide field information when autofill with platform detections is enabled. Platform detections are on when receiving a populated list from FillRequest#getHints().

Parameters
field Field: the fill information about the field. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called or this builder also contains AutofillId information

setId

Added in API level 26
public Dataset.Builder setId (String id)

Sets the id for the dataset so its usage can be tracked.

Dataset usage can be tracked for 2 purposes:

Parameters
id String: id for this dataset or null to unset.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setInlinePresentation

Added in API level 31
Deprecated in API level 33
public Dataset.Builder setInlinePresentation (InlinePresentation inlinePresentation, 
                InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33.
Use Builder(android.service.autofill.Presentations) instead.

Visualizes this dataset as inline suggestions.

Parameters
inlinePresentation InlinePresentation: the InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions this should not be null.

inlineTooltipPresentation InlinePresentation: the InlinePresentation used to show the tooltip for the inlinePresentation. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setInlinePresentation

Added in API level 30
Deprecated in API level 33
public Dataset.Builder setInlinePresentation (InlinePresentation inlinePresentation)

This method was deprecated in API level 33.
Use Builder(android.service.autofill.Presentations) instead.

Sets the InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions this should not be null.

Parameters
inlinePresentation InlinePresentation: This value cannot be null.

Returns
Dataset.Builder this builder.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 28
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                Pattern filter)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field using an explicit filter.

This method is typically used when the dataset requires authentication and the service does not know its value but wants to hide the dataset after the user enters a minimum number of characters. For example, if the dataset represents a credit card number and the service does not want to show the "Tap to authenticate" message until the user tapped 4 digits, in which case the filter would be Pattern.compile("\\d.{4,}").

Note: If the dataset requires authentication but the service knows its text value it's easier to filter by calling setValue(android.view.autofill.AutofillId, android.view.autofill.AutofillValue) and use the value to filter.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

filter Pattern: regex used to determine if the dataset should be shown in the autofill UI; when null, it disables filtering on that dataset (this is the recommended approach when value is not null and field contains sensitive data such as passwords).

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if the builder was constructed without a presentation or build() was already called.

setValue

Added in API level 30
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                Pattern filter, 
                RemoteViews presentation, 
                InlinePresentation inlinePresentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it and a explicit filter, and an InlinePresentation to visualize it as an inline suggestion.

This method is typically used when the dataset requires authentication and the service does not know its value but wants to hide the dataset after the user enters a minimum number of characters. For example, if the dataset represents a credit card number and the service does not want to show the "Tap to authenticate" message until the user tapped 4 digits, in which case the filter would be Pattern.compile("\\d.{4,}").

Note: If the dataset requires authentication but the service knows its text value it's easier to filter by calling setValue(android.view.autofill.AutofillId, android.view.autofill.AutofillValue, android.widget.RemoteViews) and using the value to filter.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

filter Pattern: regex used to determine if the dataset should be shown in the autofill UI; when null, it disables filtering on that dataset (this is the recommended approach when value is not null and field contains sensitive data such as passwords).

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

inlinePresentation InlinePresentation: The InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions, this should not be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 26
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                RemoteViews presentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it.

Note: On Android Build.VERSION_CODES.P and higher, datasets that require authentication can be also be filtered by passing a text value as the value parameter.

Theme does not work with RemoteViews layout. Avoid hardcoded text color or background color: Autofill on different platforms may have different themes.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 26
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field. Note: Prior to Android Build.VERSION_CODES.P, this method would throw an IllegalStateException if this builder was constructed without a presentation. Android Build.VERSION_CODES.P and higher removed this restriction because datasets used as an authentication result do not need a presentation. But if you don't set the presentation in the constructor in a dataset that is meant to be shown to the user, the autofill UI for this field will not be displayed.

Note: On Android Build.VERSION_CODES.P and higher, datasets that require authentication can be also be filtered by passing a text value as the value parameter.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 31
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                Pattern filter, 
                RemoteViews presentation, 
                InlinePresentation inlinePresentation, 
                InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it and a explicit filter, and an InlinePresentation to visualize it as an inline suggestion.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

filter Pattern: regex used to determine if the dataset should be shown in the autofill UI; when null, it disables filtering on that dataset (this is the recommended approach when value is not null and field contains sensitive data such as passwords).

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

inlinePresentation InlinePresentation: The InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions, this should not be null.

inlineTooltipPresentation InlinePresentation: The InlinePresentation used to show the tooltip for the inlinePresentation. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 30
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                RemoteViews presentation, 
                InlinePresentation inlinePresentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it and an InlinePresentation to visualize it as an inline suggestion.

Note: If the dataset requires authentication but the service knows its text value it's easier to filter by calling setValue(android.view.autofill.AutofillId, android.view.autofill.AutofillValue, android.widget.RemoteViews) and using the value to filter.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

inlinePresentation InlinePresentation: The InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions, this should not be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 31
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                RemoteViews presentation, 
                InlinePresentation inlinePresentation, 
                InlinePresentation inlineTooltipPresentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it and an InlinePresentation to visualize it as an inline suggestion.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

inlinePresentation InlinePresentation: The InlinePresentation used to visualize this dataset as inline suggestions. If the dataset supports inline suggestions, this should not be null.

inlineTooltipPresentation InlinePresentation: The InlinePresentation used to show the tooltip for the inlinePresentation. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.

setValue

Added in API level 28
Deprecated in API level 33
public Dataset.Builder setValue (AutofillId id, 
                AutofillValue value, 
                Pattern filter, 
                RemoteViews presentation)

This method was deprecated in API level 33.
Use setField(android.view.autofill.AutofillId, android.service.autofill.Field) instead.

Sets the value of a field, using a custom presentation to visualize it and a explicit filter.

This method is typically used when the dataset requires authentication and the service does not know its value but wants to hide the dataset after the user enters a minimum number of characters. For example, if the dataset represents a credit card number and the service does not want to show the "Tap to authenticate" message until the user tapped 4 digits, in which case the filter would be Pattern.compile("\\d.{4,}").

Note: If the dataset requires authentication but the service knows its text value it's easier to filter by calling setValue(android.view.autofill.AutofillId, android.view.autofill.AutofillValue, android.widget.RemoteViews) and using the value to filter.

Parameters
id AutofillId: id returned by AssistStructure.ViewNode.getAutofillId(). This value cannot be null.

value AutofillValue: the value to be autofilled. Pass null if you do not have the value but the target view is a logical part of the dataset. For example, if the dataset needs authentication and you have no access to the value.

filter Pattern: regex used to determine if the dataset should be shown in the autofill UI; when null, it disables filtering on that dataset (this is the recommended approach when value is not null and field contains sensitive data such as passwords).

presentation RemoteViews: the presentation used to visualize this field. This value cannot be null.

Returns
Dataset.Builder this builder. This value cannot be null.

Throws
IllegalStateException if build() was already called.