Use of this API requires review and approval. Submit the review request form to begin the process.

Sign up users with one tap using hint credentials

When you can't retrieve credentials to automatically sign in the user, you can use the googleyolo.hint() method to allow the user to sign in or sign up with one tap.

The googleyolo.hint() method presents the user a UI from which they can choose from a list of Google Accounts active in their browser. After the user chooses an account, the googleyolo.hint() method returns (via a Promise) a credential object that contains an ID token, which you can send to your backend to securely sign in or sign up the user.

You should call googleyolo.hint() from any page where signing in might be useful, or is required to proceed. For example:

  • Any existing sign-in or user registration pages
  • Pages with user-customizable content
  • Pages with content behind a paywall
  • Search results for which the user might want to receive future alerts

Before you begin

Complete the steps in Get started with automatic sign-in and one-tap sign-up.

Request sign-in hints

When you load a page where signing in might be useful, or is required to proceed, and the user is not signed in, first attempt to sign in the user with a credential returned by the googleyolo.retrieve() method. If no credentials were available to be retrieved (that is, if error.type === 'noCredentialsAvailable'), prompt the user to select an account to proceed with by calling googleyolo.hint(), passing it an object that specifies the request parameters.

The googleyolo.hint() method takes the same parameters as the googleyolo.retrieve() method, but you can only specify Google as an auth method and ID token provider.

For example, you might make a hint request like the following example:

const hintPromise = googleyolo.hint({
  supportedAuthMethods: [
    "https://accounts.google.com"
  ],
  supportedIdTokenProviders: [
    {
      uri: "https://accounts.google.com",
      clientId: "YOUR_GOOGLE_CLIENT_ID"
    }
  ]
});

You can specify the following parameters in the configuration object:

Smart Lock request parameters
supportedAuthMethods

A list of string identifiers that specify the providers for which you want to request credentials. Only Google is currently supported.

supportedIdTokenProviders

A list of objects that specify the auth providers from which you want to request ID tokens. When available, you can use ID tokens to streamline your sign-in and sign-up experiences. See ID token sign-in.

Currently, only Google is supported and must be configured using this field. Be sure to include your web client ID and that your site's domain is an authorized origin for the client ID.

If the user chooses to sign up with a different method, such as manually filling a sign-up form, you can close the credentials selector by calling the googleyolo.cancelLastOperation() method:

googleyolo.cancelLastOperation().then(() => {
  // Credential selector closed.
});

Handle the hint request result

The googleyolo.hint() method returns a Promise that resolves when the request has completed. Attach a resolution function to the Promise to handle the credential hint if one was retrieved. This function should pass the ID token from the credential to your backend.

For example:

hintPromise.then((credential) => {
  if (credential.idToken) {
    // Send the token to your auth backend.
    useGoogleIdTokenForAuth(credential.idToken);
  }
}, (error) => {
  switch (error.type) {
    case "userCanceled":
      // The user closed the hint selector. Depending on the desired UX,
      // request manual sign up or do nothing.
      break;
    case "noCredentialsAvailable":
      // No hint available for the session. Depending on the desired UX,
      // request manual sign up or do nothing.
      break;
    case "requestFailed":
      // The request failed, most likely because of a timeout.
      // You can retry another time if necessary.
      break;
    case "operationCanceled":
      // The operation was programmatically canceled, do nothing.
      break;
    case "illegalConcurrentRequest":
      // Another operation is pending, this one was aborted.
      break;
    case "initializationError":
      // Failed to initialize. Refer to error.message for debugging.
      break;
    case "configurationError":
      // Configuration error. Refer to error.message for debugging.
      break;
    default:
      // Unknown error, do nothing.
  }
});

On your auth backend, use the ID token to sign in or sign up the user. See Sign In Using ID Tokens.