Premiers pas avec l'API Ambient

L'API Ambient permet à votre application de connecter des appareils Ambient au compte Google Photos d'un utilisateur et d'afficher les photos sélectionnées.

Flux de l'API Ambient

Voici comment l'API Ambient fonctionne pour connecter un appareil, puis récupérer et afficher des éléments multimédias:

  1. Rechercher un appareil existant (recommandé): avant de créer un appareil, nous vous recommandons de vérifier s'il existe déjà un appareil pour l'utilisateur actuel. Votre application doit maintenir un mappage entre votre utilisateur interne et le deviceId fourni par Google pour tous les appareils qu'il crée via votre application. Si un deviceId est trouvé pour l'utilisateur, vous pouvez procéder à l'actualisation de son jeton d'autorisation (si nécessaire).

  2. Lancer l'autorisation OAuth 2.0 (et éventuellement créer un appareil): commencez le flux OAuth 2.0 pour les applications TV et d'appareils à entrée limitée en demandant un code d'autorisation.

  3. Créer un appareil: votre application crée un appareil dans le compte Google Photos d'un utilisateur en appelant CreateDevice et en fournissant un UUID v4 valide.

    Une fois l'appareil créé, l'API renvoie un objet AmbientDevice contenant un deviceId attribué par Google. Il est essentiel que votre application stocke cette deviceId et l'associe à vos utilisateurs.

  4. Afficher le settingsUri: un objet AmbientDevice inclut un settingsUri. Présentez cet URI à l'utilisateur, généralement sous la forme d'un code QR, qu'il peut scanner à l'aide de son appareil mobile. Cet URI redirige l'utilisateur vers l'application Google Photos, où il peut configurer les sources multimédias (albums, par exemple) qu'il souhaite afficher sur son appareil en mode Veille.

  5. Interroger mediaSourcesSet: votre application doit appeler régulièrement la méthode GetDevice, en fournissant deviceId, pour vérifier l'état de l'appareil ambiant. Surveillez le champ mediaSourcesSet dans la réponse AmbientDevice. Il est initialement défini sur "false".

    Une fois que l'utilisateur a sélectionné les sources multimédias dans l'application Google Photos, ce champ est défini sur "true".

    La réponse AmbientDevice inclut un pollingConfig avec un pollInterval que vous devez utiliser comme référence pour votre fréquence d'interrogation.

  6. Récupérer des éléments multimédias: lorsque mediaSourcesSet renvoie la valeur "true", votre application peut commencer à extraire les éléments multimédias sélectionnés par l'utilisateur.

    Appelez la méthode ListMediaItems en fournissant deviceId. L'API renvoie un ListMediaItemsResponse contenant une liste d'objets AmbientMediaItem. Chaque AmbientMediaItem inclut des informations telles qu'un id, un createTime et un objet MediaFile avec des métadonnées supplémentaires. MediaFile contient un baseUrl que vous pouvez utiliser pour extraire les octets réels d'un élément multimédia. Pour en savoir plus sur les autres paramètres baseUrl, consultez le guide Lister et récupérer des éléments multimédias.

  7. Affichage d'éléments multimédias: utilisez baseUrl à partir de MediaFile pour télécharger et afficher le contenu multimédia sur l'appareil en mode Veille.

Considérations importantes à prendre en compte

Limite et gestion des appareils:

  • Limites d'appareils: n'oubliez pas que votre application est limitée à 100 appareils par utilisateur.
  • Activité et jetons de l'appareil: vous devrez gérer le cycle de vie des appareils et des jetons d'autorisation utilisateur. Tenez compte de la durée pendant laquelle les appareils restent actifs et de la manière dont vous gérerez les actualisations ou les réautorisations de jetons si un appareil devient inactif ou si le jeton expire.

Pour en savoir plus, consultez le guide Créer et gérer des appareils.

Utiliser des éléments multimédias:

  • Utilisation d'un élément multimédia: découvrez comment récupérer et gérer correctement le contenu de l'élément multimédia à l'aide de baseUrl, y compris toute authentification ou tout paramètre nécessaire.
  • Gestion des erreurs: implémentez une gestion des erreurs robuste pour les appels d'API, y compris des scénarios tels que NOT_FOUND pour les appareils, FAILED_PRECONDITION si les sources multimédias ne sont pas définies et RESOURCE_EXHAUSTED si les limites de l'appareil sont atteintes.

Pour en savoir plus, consultez le guide Lister et récupérer des éléments multimédias.

Étapes suivantes