The beta test program for this API is currently closed. We are improving the API's cross-browser functionality and will provide updates here in the coming months.

Sign in users automatically with their saved credentials

Use the googleyolo.retrieve() method to request the user's sign-in credentials for your site. When credentials are successfully retrieved, you can use them to automatically sign in the user.

You should call googleyolo.retrieve() on any page that can provide a signed-in experience for your user, including the home page and any pages the user can reach from a search result or shared link.

If the user hasn't saved any credentials, no UI is presented, and you can provide your normal signed-out experience.

If the user has only one credential saved, the credential can be retrieved without user interaction, which makes completely automatic sign-in possible.

When multiple credentials are saved, the user can choose the one to use with a single tap.

Before you begin

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

Request saved credentials

When you load a page and the user is not signed in, retrieve any credentials the user has saved for your site by calling googleyolo.retrieve(), passing to it an object that specifies the request parameters.

For example, if you support both Google Sign-in and password based sign-in, make a credential request like the following:

const retrievePromise = googleyolo.retrieve({
  supportedAuthMethods: [
    "https://accounts.google.com",
    "googleyolo://id-and-password"
  ],
  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 sign-in methods and providers for which you want to request credentials. Include https://accounts.google.com to retrieve Google Account credentials and optionally googleyolo://id-and-password to retrieve password-based credentials when no Google Accounts are saved.

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.

context

A string that specifies the UI context of the request. Set this value to select the text to use in the account selector UI. You can specify the following contexts:

Context Prompt
signIn (default) Sign in to YOUR_SITE with Google
continue Use YOUR_SITE with Google

To provide a consistent user experience across sites, only these predefined strings are available.

If the user chooses to sign in with a different method, such as manually typing an email address and password, you can close the credentials selector by calling the googleyolo.cancelLastOperation() method:

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

Handle the credential request result

The googleyolo.retrieve() method returns a Promise that resolves when the request has completed. Attach a resolution function to the Promise to handle the credential if one was retrieved.

In general:

  • If an ID token was retrieved, pass it to your backend to sign in or sign up the user. See Sign In Using ID Tokens.
  • If a user ID and password pair was retrieved, use them to sign in the same way you would if the user had manually supplied them.

For example:

retrievePromise.then((credential) => {
  if (credential.password) {
    // An ID (usually email address) and password credential was retrieved.
    // Sign in to your backend using the password.
    signInWithEmailAndPassword(credential.id, credential.password);
  } else {
    // A Google Account is retrieved. Since Google supports ID token responses,
    // you can use the token to sign in instead of initiating the Google sign-in
    // flow.
    useGoogleIdTokenForAuth(credential.idToken);
  }
}, (error) => {
  // Credentials could not be retrieved. In general, if the user does not
  // need to be signed in to use the page, you can just fail silently; or,
  // you can also examine the error object to handle specific error cases.

  // If retrieval failed because there were no credentials available, and
  // signing in might be useful or is required to proceed from this page,
  // you can call `hint()` to prompt the user to select an account to sign
  // in or sign up with.
  if (error.type === 'noCredentialsAvailable') {
    googleyolo.hint(...).then(...);
  }
});

Handling sign-out

When a user signs out of your site, call googleyolo.disableAutoSignIn() to disable automatic sign-in for the remainder of the session. If you do not disable automatic sign-in, the user can end up in a "sign-in loop" in which they are immediately signed back in after trying to sign out.

disableAutoSignIn().then(() => {
  // Auto sign-in disabled.
});