For Developers‎ > ‎

Using requestAutocomplete()

The requestAutocomplete method and associated events are an extension of the HTMLFormElement API. Currently implemented as an experiment in Chrome, this new method is planned as a standard browser feature. It improves upon current standard autocomplete behavior by providing an homogeneous UI that short-cuts form presentation and greatly streamlines a purchase or other form flow.

View the working demo

Using requestAutocomplete also provides for success and failure event handling, so you can both validate the form and handle errors. You can also use feature detection for graceful degradation on browsers that do not yet support the feature.

Particularly for mobile applications, this solves the problem of working with long or even multi-page forms. It improves the purchase checkout flow and reduces drop-off with a secure and concise payment submission UI. For merchants, this results in improved conversion rates, sorely needed in mobile purchase scenarios.

requestAutocomplete is not yet standardized, but it’s been proposed to the WhatWG to be included in the WhatWG HTML spec. The Chrome team has been working with WhatWG and other browser vendors to make payments across the web simpler for consumers. 

Contents



Background

Autocomplete or autofill has been a feature of most browsers for many years and the autocomplete attribute is part of the W3C Forms 2 (HTML5) specification. Early browsers like IE5 stored the name, value, and domain of the form elements and values, and reproduced a list of supplied values each time the user visited the page with the form. Eventually, most browsers dropped consideration of the domain which allowed the values of the form elements to be shared across multiple web sites.

The autocomplete attribute applies to the text, password, select, textarea, date-related, time-related, numeric, email, and uri controls at both the form and form element level. It has two values, on and off. The value at the form element level takes precedence over the value at the form level. See the <form> documentation for more information.

Also, Chrome performs various heuristics on form elements to determine the appropriate values to fill in. These are based on user behavior and compared to users in the aggregate. With Chrome Sync enabled, the user can share autocomplete values across browser/device instances.

User interface

The user invokes requestAutocomplete by clicking on an element like a “Checkout” button.


and this is what it looks like on desktop


The form summary displays in a drop-down element. This may be a Payment Details summary with the name, address, phone, credit card number, and so on.


and this is what it looks like on desktop


User clicks Submit. The form summary disappears. Typically an order review page or similar displays:

Order summary

The user clicks Place Order and achieves consumer satisfaction.

Implementation

Assume a shopping cart scenario with a Checkout as Guest button.

<!-- This is a guest checkout button on a shopping cart -->
<
button id="guestcheckout">Checkout as Guest</button>
  1. In your page, embed a hidden form with appropriate autocomplete attributes.

The design described here uses a hidden form. But you could make the form visible.

You can place the form anywhere in the DOM as it is hidden. Use form and input names from your existing checkout flow. See Fields populated, below.

<form id="payment" hidden action="..." method="...">
  <
input autocomplete="cc-name" name="myname">
  <
input autocomplete="cc-number" name="ccnumber">
  <
input autocomplete="cc-exp" name="ccexp">
 
<input autocomplete="cc-csc" name="cccvc">
  <
input autocomplete="billing street-address" name="billaddress">
 
<input autocomplete="billing locality" name="billtown">
  <
input autocomplete="billing region" name="billstate">
  <
input autocomplete="billing postal-code" name="billzip">
</
form>

  1. Call requestAutocomplete on the payment form. Use an anonymous function to keep things tidy.

requestAutocomplete is a method of the HTMLFormElement. It causes the browser to display the form summary described in Implementation, above, and must be initiated by a user action such as a click or key press.

(function(){

  // find relevant elements
  var form = document.
getElementById('payment');
  var button = document.getElementById('guestcheckout');

  // detect support and quit early, allowing default behavior
  if (!("requestAutocomplete" in
form)) return;

  button.addEventListener('click', function(){
     form.requestAutocomplete();
  });

  // see details on event handling below
  form.addEventListener('autocomplete', function(){
    // successful rAc
    // Call your client-side form validation logic here, if you have any.
    form.submit();  // trigger submit
  });

  form.addEventListener('autocompleteerror', function(){
    // event.reason is one of "cancel", "invalid" or "disabled".
    // handle error...
  });


})();

For best results, with the completion of every requestAutocomplete call, use a page transition to indicate form submission success and navigate to the next relevant step in your checkout flow. Do not request autocomplete data, then ask for subsequent form data farther down the same page.

  1. Listen for the autocomplete and autocompleteerror events.

The autocomplete event indicates that the form is filled with the user’s information.

form.addEventListener('autocomplete', function(){
  // successful rAc

  // If necessary, call client-side logic to transform the rAc() expected values that
  // are compatible with your backend.
  form.submit();  // trigger submit
});

The autocompleteerror event indicates a problem with the form submission, usually caused by the user cancelling out of the form. However, you may want to handle cancellation, error, or feature-disabled reasons for the event.

form.addEventListener('autocompleteerror', function(event){
  // event.reason is one of
"cancel", "invalid" or "disabled".
  // handle error...
});

See autocompleteerror, below for more information about handling error conditions (reasons).
  1. Handle the POST on the back end as if the user had submitted the form as usual.

Fields populated

Of the available autocomplete attributes, there is a strict whitelist of fields that requestAutocomplete will populate:

  1. Contact:        name, tel, email
  2. Shipping:        street-address, address-line1, address-line2, locality, region, country, postal-code
  3. Billing:        street-address, address-line1, address-line2, locality, region, country, postal-code
  4. Payment:        cc-name, cc-number, cc-exp, cc-csc, cc-type

Fields not populated, like promo codes, shipping options, membership numbers (e.g. frequent flyer number) and so forth, the user should populate manually in a separate page such as the order review step.

The following lists each attribute, expected value, recommended tags, and any notes about how the attribute is validated in Chrome.

name

Expected value

String

Recommended tags

 <input type="text" autocomplete="name" name="name">

Chrome validation

None.
Note: Chrome's implementation uses heuristics to populate the name field; therefore, using  tokenized name fields for name is not recommended.

tel

Expected value

String

Recommended tags

<input type="tel" autocomplete="tel" name="phone">

Use autocomplete attribute value tokens to specify how you'd like to handle international numbers:

<input type="tel" autocomplete="tel" name="phone"> (includes country code)

<input type="text" autocomplete="tel-country-code" name="phone-cc"> 

<input type="tel" autocomplete="tel-national"  name="phone-num">

Chrome validation

Chrome will apply the value sanitization algorithm for <input type=tel> values (line feed and trailing whitespace stripping).  There may be parens, dashes, periods or a + symbol within the string. Chrome validates incoming international phone numbers with libphonenumber.

email

Expected value

String

Recommended tags

<input type="email" autocomplete="email" name="email">

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=email> fields when setting the value: "Strip line breaks from the value, then strip leading and trailing whitespace from the value."

Chrome will accept new addresses that validate against the valid definition in the HTML spec.

street-address

Expected value

String

Recommended tags

<input type="text" autocomplete="street-address" name="one-line-address"> (address-line1 and address-line2 on one line, separated by comma)

Or…

<input type="text" autocomplete="address-line1" name="address-primary">

<input type="text" autocomplete="address-line2" name="address-secondary">

Chrome validation

Chrome's initial implementation does not support address-line3. 

locality

Expected value

String (city, town, etc.)

Recommended tags

<input type="text" autocomplete="locality" name="city">

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=text> fields when setting the value.

postal-code

Expected value

String

Recommended tags

<input type="text" autocomplete="postal-code" name="zip">

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=text> fields when setting the value.

region

Expected value

String - U.S. state codes of 2 characters; international to be supported soon.

Recommended tags

<input type="text" autocomplete="region" name="state">

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=text> fields when setting the value.

country

Expected value

String

Recommended tags

<select autocomplete="country"><option value="NL">Netherlands</option>...</select>

Values should follow ISO 3166-1 2-character or 3-character values. If an <input type="text"> is provided, Chrome will provide full country name, localized.

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=text> fields when setting the value.

cc-number

Expected value

Number with no dashes. Length can vary from 12 to 19 numbers.

Recommended tags

<input type="text" autocomplete="cc-number" name="card_number">

Chrome validation

Chrome performs a Luhn check  on  credit card data entered into chrome://settings/autofillEditCreditCard. Chrome does not enforce length limits, though based on card type it may provide more specific validation.

cc-exp

Expected value

Date, not in the past;  you can expect a valid non-expired date.

Recommended tags

Use two <select> tags:

<select autocomplete="cc-exp-month"><select autocomplete="cc-exp-year">

If you'd like to use a single text input instead, use <input type="month" autocomplete="cc-exp">

Chrome will set a value like 2014-07 to it.  If you use <input type=text> we will use heuristics to guess if your field prefers 2014-07, 07/2014 or 07/14.

Chrome validation

Chrome performs a Luhn check  on  credit card data entered into chrome://settings/autofillEditCreditCard. Chrome does not enforce length limits, though based on card type it may provide more specific validation.  

cc-type

Expected value

String

Recommended tags

Do not use an element. The card type can be inferred based on the number, so it's likely best to do that on the backend.

However, Chrome will provide it if requested. If a <select> is provided, Chrome will attempt to set the value using heuristics to set the correct type. If <input type=text> is used, one of these field values (see IDS_AUTOFILL_CC_AMEX) will be provided. Do not use radio buttons, as they cannot be well supported by this feature.

Chrome validation

Error handling: If the card type is not found in <select> element's options, the value will not be set and server-side validation will need to identify that missing value. It may mean an invalid card type (e.g. Discover) has been used. (All temporary cards provided via Google Wallet will be Mastercard, see User experience considerations, below).

Chrome infers the card type when a user adds a new card but does not explicitly request it.

cc-csc

Expected value

Number, 3 - 4 digits.

Recommended tags

<input type="number" autocomplete="cc-csc" name="card_csc">

Chrome validation

Chrome will apply the value sanitization algorithm written for <input type=number> fields when setting the value.

cc-name

Expected value

String

Recommended tags

<input type="text" autocomplete="cc-name" name="card_name">

Chrome validation

None.

Note: Chrome's implementation does not support tokenized name fields for cc-name.

Chrome will apply the value sanitization algorithm written for <input type=text> fields when setting the value.

Other form attribute support

Other attributes on the form elements will be treated as follows.

autocomplete

Setting this attribute to off in combination with requestAutocomplete is not recommended.

  1. If set to off on the <form>, Chrome fires autocompleteerror on the form object asynchronously when requestAutocomplete is called.  
  2. If set on an <input> that input will be ignored and autocompleteerror will not fire.

maxlength

Obeyed. values will be truncated if they exceed the maxlength.

disabled

Any disabled inputs will not allow their values to be set by requestAutocomplete. 

readonly

Any readonly inputs will not allow their values to be set by requestAutocomplete.

hidden

hidden inputs work fine with requestAutocomplete. Hidden attributes on the form itself work fine as well. Indeed, it is recommended that you hide the actual form. See Implementation, above.

pattern

May conflict with requestAutocomplete behavior.

For example, a telephone input may be set with a custom pattern to identify well-formed US phone numbers:

<input autocomplete="tel" type="tel" name="cust-telephone"
               pattern="([2-9][0-8][0-9])\W*([2-9][0-9]{2})\W*([0-9]{4})">

However this will fail with telephone numbers formatted without parens and will also fail with any international numbers that include the country code.

See Handling conflicting attributes, below.

required

May conflict with requestAutocomplete behavior.

For example, an input may have the required attribute on it, but it is not successfully filled out by requestAutocomplete.

See Handling conflicting attributes, below.

Handling conflicting attributes

The attributes listed in Fields populated are what requestAutocomplete expects from the form. Your markup should not use fields that do not support requestAutocomplete.

Presently, Chrome does not handle conflicting attributes. But in a future release when an attribute set on a form element is in conflict with requestAutocomplete, the following should occur:

  1. requestAutocomplete applies a new, empty value to the field.
  2. a change event fires on the changed field.
  3. The constraint validation steps are executed.

The tooltips that would normally be displayed are not shown if the form itself is hidden.

  1. The invalid event will fire on the input element where this fails.
  2. The autocompleteerror event will fire on the form element (identifying this is a validation error).
  3. You can then loop through the elem.validity object to see why the value is deemed invalid, and present suggestions to the user.

Events

The following events fire on the form object.

autocomplete

Fires when all input values are set and any custom validity is satisfied.

autocompleteerror

Fires when an input value is in error. Includes a reason property with the possible values:

  1. invalid: (not currently implemented) custom validity attributes conflict with values provided by requestAutocomplete.

See Handling conflicting attributes, above.

  1. cancel: user aborted the dialog.
  2. disabled: disabled by browser preference or disabled attribute. Alternatively, fires if requestAutocomplete is called not via a user gesture like click or keypress.

One route out of this error condition would be to serve up the actual form and proceed with autocomplete via the legacy workflow, as when the feature is not supported and you need to provide graceful degradation.

See the requestAutocomplete draft spec for more detail.

You may also construct a synthetic AutocompleteErrorEvent object for testing.

change

Fires as each input value is set.

invalid

(Not currently implemented.) Fires if an input value does not satisfy the constraint validation API.

Code examples & demo

Check out (pun intended) this very realistic demo site  to see a working demonstration of requestAutocomplete. (Note the platform support and requirements, below.) 

If you want to see all of the form fields on the checkout page, view the source.

Video of demo site (by Robert Glastra):



Google I/O presentation

Google I/O 2013 featured a presentation about requestAutocomplete and how to effectively put it to use:

Google I/O 2013 - Standardizing Payments on the Web: Introducing requestAutocomplete()

Presenters: Chromium engineers Dan Beam, Evan Stade 

Ever try buying something on the mobile web? Combine a mess of form fields and a soft keyboard and it's more frustrating than it needs to be. How many customers don't buy things from you because doing so is just too much work? requestAutocomplete() is an aspiring web standard that will allow users to bypass pages of form fields with an imperative API for requesting details the browser knows. In this session we'll highlight how to enhance your site with requestAutocomplete(), how to quickly implement the feature, and what to consider when optimizing the UX of your ecommerce experience.

Platform support and requirements

requestAutocomplete is supported currently in Chrome Canary and Dev for Windows and Chrome OS. Support for Mac OS, Linux, and Android is coming soon.

You must browse to about:flags and enable Interactive Autocomplete to use the feature.

Security considerations

requestAutocomplete requires the host page to be served with SSL if any of the cc-* fields are in the form. If the page is not securely served, an ugly yellow warning banner will be placed along the top of the dialog. This warning is there for testing purposes and to alert you to the security problem, but your implementation should not expose the warning to users. Be sure you are using SSL for any forms that use the cc-* fields.

If you're doing the comprehensive implementation (with a hidden form) on a non-SSL page, you will need to host the form and checkout/trigger button in an SSL iframe.

However, note that the URL bar may not have a lock icon or "https" in this case (though the form submission will be secure). To rectify this, consider serving the host page in SSL or delaying the requestAutocomplete behavior until the user has reached a secure page.

If the top level page is in HTTP and the requestAutocomplete call is from an iframe (served in SSL), the user will get a "This is coming from https://<site>" message to clarify that it's coming from a different origin. To avoid this message, host the parent page in SSL as well.

Usability testing

The following actions are recommended for tracking the effectiveness of the new user flow and identifying opportunities for optimization:

  1. If possible, execute an A/B test of standard flow against the new checkout flow.
  2. Isolate the A/B audience to just Chrome users. You get this for free with feature detection as shown in the implementation example.
  3. Consider the following key performance indicators:
  1. average order value (AOV)
  2. conversion rate
  3. cart confirmation drop-off rate.
  1. Capture the autocompleteerror event to identify when users do not complete the UI for submitting the user info.

FAQ

Q: How can I get more help?

A: Visit https://groups.google.com/a/chromium.org/forum/#!forum/requestautocomplete and join requestautocomplete@chromium.org.  This is a public forum for developers to discuss Chrome’s implementation of requestAutocomplete and ask questions.

Q: Where can I see the list of known issues?

A: https://code.google.com/p/chromium/issues/list?can=2&q=Cr%3DUI-Browser-Autofill-Interactive

Q: This seems rough. Why did you turn this on?

A: Chrome Canary and Dev channels are where we can experiment with features currently under development. We want site owners to be able to easily explore the feature and give us feedback.  Given the small API surface turning this on early gives us a good way to do that.

Q: What browsers support requestAutocomplete?

A: Currently Chrome Canary and (soon) Dev channels on Windows and Chrome OS.  We’ve been discussing the feature on standards lists and with other browser vendors. Our goal is to see it adopted as a standard and implemented by most browsers.

Q: Will you support Android? iOS? etc?

A: If Chrome works on a platform, we want to support rAc there.  Windows and Chrome OS are the most complete at the moment.  Other platforms are in progress.

Q: How should I handle a user canceling the requestAutocomplete flow?

A: We recommend doing nothing. When a user presses cancel, we will dismiss the dialog and the user will be taken back to your checkout page. 

Q: Why are there references to Google Wallet in the UI?

A: The Chrome implementation of requestAutocomplete provides users the option to opt-in to Google Wallet for additional security and convenience features. With Google Wallet, users may access their payment information from any device, and the users’ saved credit or debit card information is never shared with merchants. If a user is opted-in to Wallet, to complete a merchant transaction we pass along a Google Wallet virtual card.

Q: What is a Google Wallet virtual card?

A: To protect our users’ privacy and security, Chrome does not share a Google Wallet user's full credit or debit card information with merchants. Instead, a Google Wallet virtual card is generated and used to complete purchases. Payment is authorized against the Google Wallet virtual card, and then Google charges the user's credit or debit card for the same amount.  See http://support.google.com/wallet/bin/answer.py?hl=en&answer=2740044 for more info.

Q: Does the Google Wallet virtual card have to be handled differently than traditional credit cards?

A: No, you can use this card number exactly as you would any credit card supplied directly by the user.

Q: Do I, as a developer, need to worry if a user is opted-in to Google Wallet or not?

A: No, you will receive a fully functional credit card number regardless of whether or not your user is opted-in to Google Wallet.

Q: I just tried to charge money using requestAutocomplete in Wallet mode and the charge was declined.  What gives?

A: The current implementation points to a test server by default.  The cards that the test server issues can’t be charged.  Once the production server is ready we’ll announce it on requestautocomplete@chromium.org along with instructions for switching between real and test servers.

Comments