Get Started with the Ambient API

The Ambient API enables your application to connect ambient devices to a user's Google Photos account and display their selected photos.

The Ambient API Flow

Here's a breakdown of how the Ambient API works to connect a device and then retrieve and display media items:

  1. Check for existing device (recommended): Before creating a new device, it's recommended to check if a device for the current user already exists. Your application should maintain a mapping between your internal user and the Google-provided deviceId for any devices they create through your app. If a deviceId is found for the user, you can proceed to refreshing their authorization token (if needed).

  2. Initiate OAuth 2.0 authorization (and optionally create device): Begin the OAuth 2.0 for TV and Limited Input Devices flow by requesting an authorization code.

  3. Create a new device: Your app creates a device in a user's Google Photos account by calling CreateDevice and providing a valid v4 UUID.

    Upon successful device creation, the API will return an AmbientDevice object containing a Google-assigned deviceId. It is crucial for your application to store this deviceId and associated it with your users.

  4. Display the settingsUri: an AmbientDevice object includes a settingsUri. Present this URI to the user, typically as a QR code, which the user can scan using their mobile device. This URI directs the user to the Google Photos app where they can configure the media sources (e.g., albums) they want to display on their ambient device.

  5. Poll for mediaSourcesSet: Your application should periodically call the GetDevice method, providing the deviceId, to check the status of the ambient device. Monitor the mediaSourcesSet field in the AmbientDevice response. It will initially be false.

    Once the user has successfully selected media sources in the Google Photos app, this field will change to true.

    The AmbientDevice response includes a pollingConfig with a pollInterval that you should use as a guideline for your polling frequency.

  6. Retrieve media items: When mediaSourcesSet returns true, your application can begin fetching the media items selected by the user.

    Call the ListMediaItems method, providing the deviceId. The API will return a ListMediaItemsResponse containing a list of AmbientMediaItem objects. Each AmbientMediaItem includes details like an id, createTime, and a MediaFile object with additional metadata. The MediaFile contains a baseUrl which you can use to fetch the actual bytes of a media item. Review the guide to List and retrieve media items for details on additional baseUrl parameters.

  7. Display Media Items: Use the baseUrl from the MediaFile to download and display the media content on the ambient device.

Important Considerations

Device limit and management:

  • Device limits: Be aware of the limit of 100 devices per user of your application.
  • Device activity and tokens: You'll need to manage the lifecycle of devices and user authorization tokens. Consider how long devices remain active and how you'll handle token refreshes or re-authorization if a device becomes inactive or the token expires.

The guide to Create and manage devices has additional details.

Working with media items:

  • Media item usage: Understand how to properly fetch and handle the media item content using the baseUrl, including any necessary authentication or parameters.
  • Error handling: Implement robust error handling for API calls, including scenarios like NOT_FOUND for devices, FAILED_PRECONDITION if media sources are not set, and RESOURCE_EXHAUSTED if device limits are reached.

The guide to List and retrieve media items has additional details.

Next Steps