Create and manage devices

Page Summary

• This webpage is currently under development and will provide a comprehensive guide in the future.

• A sample application is available, demonstrating device creation and data handling through the createDevice function.

• Reference documentation on devices is accessible for review, offering detailed information.

This guide covers how to create, manage, and delete devices. Proper device management helps create a smooth user experience and efficient use of the Ambient API.

Create Devices

After a user has successfully authenticated using the OAuth 2.0 for TV and Limited-Input Device Applications flow, create a device in their Google Photos account.

When your app successfully creates a device using the devices.create method, the Ambient API returns an AmbientDevice object that includes a Google-generated id. Securely store this id and associate it with your users.

Important: Save the id. If you don't save the Google-generated id, you won't be able to retrieve or manage a device later. This can lead to orphaned devices in your users' Google Photos accounts, which can't be accessed or cleaned up by your application.

Streamlined Device Creation with OAuth

The Ambient API offers a streamlined OAuth flow that can create a device simultaneously with user authentication. By passing the additional state parameter in your initial OAuth request, you can link the device creation process directly to the user's sign-in flow, simplifying the user experience by reducing the number of QR codes they need to scan.

For more details and an example, see the Streamlined authentication flow for the Ambient API guide.

Device Limits

Your application can create up to 100 devices per user. If this limit is exceeded, the API returns a RESOURCE_EXHAUSTED error.

Manage Devices

Once a device is created and linked to a user's Google Photos account, you might need to manage its lifecycle.

Retrieve Devices

To retrieve information about a specific device, use the devices.get method with its unique id. This is useful for checking the device's status, such as whether mediaSourcesSet is true.

Update Devices

You can update certain properties of an existing device, such as its display name, using the devices.patch method. This allows users to personalize their devices and makes them easier to identify within Google Photos.

Note: A good practice is to offer the user the opportunity to name their device before creating it. This makes it much easier for the user to recognize their device when picking media items in their Google Photos account.

Delete Devices

Implement a strategy for deleting devices for proper cleanup and user control. You can delete a device using the devices.delete method.

Consider the following scenarios for deleting devices:

• User disconnection: If a user disconnects your application from their Google Photos account, you should delete the corresponding device.
• Orphaned Devices: If you lose track of a id but still have the requestId that was used during creation, you can use the requestId with devices.delete to remove an orphaned device. This helps prevent accidental duplicates and keeps the user's account clean.

Important Considerations and Best Practices

• Device lifecycle and user authorization: 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 its token expires.
• Error Handling: Implement robust error handling for all device-related API calls. Be prepared for scenarios like:
  • NOT_FOUND: If a device doesn't exist or isn't owned by the user.
  • RESOURCE_EXHAUSTED: If you exceed the device limit.
  • ALREADY_EXISTS: If you try to create a device with a requestId that already exists.

Next Steps

• Sample Application: Our sample application includes an example of creating a device and working with the response data. Check out the createDevice function for more info.
• Reference Documentation: Review the comprehensive reference docs on devices for detailed information on all available methods, request and response parameters, and error codes.
• List and retrieve media items: Once you've created and managed your devices, learn how to list and retrieve media items to display on them.