Configure your app for the Ambient API

  • The Ambient API requires users to sign in with a valid Google Account and uses OAuth 2.0 for authentication, specifically OAuth 2.0 for TV and Limited-Input Device Applications.

  • To start, enable the Ambient API in the Google API Console and then request an OAuth 2.0 client ID, selecting "TVs and Limited Input devices" as the application type.

  • Including the state parameter with requestId and displayName during the initial OAuth device code request streamlines the authentication flow by eliminating the need to display a second QR code for settingsUri.

  • Changing the client ID after resources have been created can result in the loss of access to those resources, so choosing and managing the correct client ID is crucial.

  • The complete authentication involves requesting a device code and user code, displaying them to the user, and later polling for access tokens; the user will need a device with a rich input to authorize the app.

To start using the Ambient API, configure your project by enabling the api in the Google API Console and setting up an OAuth 2.0 client ID. The Ambient API uses OAuth 2.0 for TV and Limited-Input Device Applications.

Your application interacts with the Ambient API on behalf of a the Ambient API user. The user authorizes these API requests using the OAuth 2.0 protocol.

The OAuth 2.0 client ID allows your application users to sign in, authenticate, and thereby use the Ambient API. The Ambient API don't support service accounts; to use these APIs, users must be signed in to a valid Google Account.

Configure your app

First enable the API, then request an OAuth 2.0 client ID.

Enable the API

Before you can use the Ambient API, you must enable it in your project.

  1. Go to the Google API Console.
  2. From the menu bar, select a project or create a new project.
  3. To open one of the Google Photos APIs, from the Navigation menu, select APIs & Services > Library.
  4. Search for "Ambient API". Select the Ambient API and click Enable.

Request an OAuth 2.0 client ID

Follow these steps to request an OAuth client ID and configure it for your application. The Ambient API uses OAuth 2.0 for TV and Limited-Input Device Applications.

  1. Go to the Google API Console and select your project.
  2. From the menu, select APIs & Services > Credentials.

  3. On the Credentials page, click Create Credentials > OAuth client ID.

  4. Select your Application type. In this example, the application type is TVs and Limited Input devices.

  5. Provide a name for your OAuth 2.0 client and click Create.

  6. From the resulting OAuth client dialog, copy the following:

    • Client ID
    • Client secret

Your app can access the enabled Google APIs using these values.

Before you can launch a public application that accesses the Ambient API, your app must be reviewed by Google. An "Unverified app" message appears on the screen when you test your application, until it is verified.

After you've configured your app you're ready to get started. You can explore the following resources, or read on about the streamlined authentication flow for the Ambient API.

Changing your client ID

Resources created through any of the Google Photos APIs can only be accessed or modified using the original client ID used to create them. For example, if you create a session in the Picker API with a specific client ID and later change that client ID in your app, your app will lose access to any API resources created with the previous client ID.

Plan carefully and choose the correct client ID type for the Photos API you are using. Only change your client ID if absolutely necessary to avoid access issues.

Streamlined authentication flow for the Ambient API

The standard Ambient API authentication flow requires your users to scan 2 QR codes:

  • A 1st to sign in to their Google Account (if they are not signed in already).
  • A 2nd that links to the newly created Ambient device in their Google Photos account where they can select media items to display.

The streamlined flow lets you provide a single QR code to your users by passing the additional state parameter with your initial authentication call.

When requesting device and user codes as part of OAuth for limited input devices, include the additional state parameter with your request. Add the following to the state parameter:

Parameters
requestId

string

Required. A client-provided unique identifier for this request. This is used to mitigate resource duplication in the event of a network failure.

This ID must have the format of a UUID (version 4) string and follow these requirements:

  • Must not contain any sensitive identifying information about the user.
  • Must contain 32 hexadecimal characters divided into five groups separated by hyphens, in the format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (or 8-4-4-4-12).
displayName

string

Optional. A user-defined display name for this device.

This will be visible to users from the Google Photos app settings but only editable through this API.

Valid display names must have between 1 and 100 characters (inclusive).

For example, see the following code block:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

A successful response will include a user_code and a verification_url, which you show to the user (most likely as a QR code) so they can navigate there on a separate device. By including the state parameter, when you later call createDevice with the Ambient API, you can skip presenting the settingsUri in a second QR code, as the last step in the OAuth flow will automatically redirect to this location.

For complete details we've included a more thorough explanation. You can also review the code in our sample app, for an example of using the state parameter as part of OAuth for limited input devices with the Ambient API.

Details about the streamlined authentication flow

To fully understand the streamlined OAuth flow for the Ambient API, it helps to understand both the OAuth 2.0 for TV and Limited-Input Device Applications flow as well as the standard Ambient API flow. Here are the steps for each flow.

OAuth 2.0 for TV and Limited-Input Device Applications:

  1. Your application sends a request to Google's authorization server that identifies the scopes that your application will request permission to access.
  2. The server responds with several pieces of information used in subsequent steps, such as a device code and a user code.
  3. You display information that the user can enter on a separate device to authorize your app.
  4. Your application starts polling Google's authorization server to determine whether the user has authorized your app.
  5. The user switches to a device with richer input capabilities, launches a web browser, navigates to the URL displayed in step 3 and enters a code that is also displayed in step 3. The user can then grant (or deny) access to your application.
  6. The next response to your polling request contains the tokens your app needs to authorize requests on the user's behalf. (If the user refused access to your application, the response does not contain tokens.)

Ambient API flow:

  1. Check for an existing OAuth token, and either refresh the token or request a new one.
  2. After obtaining an OAuth token, create a new device.
  3. Display the settingsUri to the user, and begin to poll the device until mediaSourcesSet returns true.
  4. The user navigates to the settingsUri and selects the photos they want to share with your application.
  5. Once mediaSourcesSet returns true, retrieve the list of mediaItems.
  6. Now you can begin your slideshow or other ambient experience.

Both flows include a step where you display a URL to your user, and your user navigates there on their richer input device. By including the state parameter in your initial OAuth call, you can avoid the second URL you have to display.

This works because the last step of the OAuth 2.0 for TV and Limited-Input Device Applications flow normally redirects your user to a page that says "You can now return to your device." By including the state parameter, the last step of the flow will now try to redirect you to the settingsUri. Your app will still receive an OAuth token. You should use this token to call createDevice using the same requestId. Once a device with the same ID has been created, the initial OAuth flow will successfully redirect your user to the correct page on the rich device within the Photos app.

Remember the following points:

  • It's still a good idea to display the settingsUri in case there are any issues with authentication.
  • You can still use the settingsUri in other cases, such as when a user wants to update their photo selection.