Premiers pas avec l'API Ambient

L'API Ambient permet à votre application de connecter des appareils ambiants 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. Recherchez un appareil existant (recommandé) : avant de créer un appareil, il est recommandé de vérifier si un appareil pour l'utilisateur actuel existe déjà. 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 ce deviceId et l'associe à vos utilisateurs.

  4. Affichez 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 ambiant.

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

    Une fois que l'utilisateur a sélectionné des sources multimédias dans l'application Google Photos, ce champ passe à "true".

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

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

    Appelez la méthode ListMediaItems en fournissant deviceId. L'API renverra un ListMediaItemsResponse contenant une liste d'objets AmbientMediaItem. Chaque AmbientMediaItem inclut des détails tels 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 récupérer 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. Afficher des éléments multimédias : utilisez baseUrl à partir de MediaFile pour télécharger et afficher le contenu multimédia sur l'appareil ambiant.

Considérations importantes à prendre en compte

Limite et gestion des appareils :

  • Limites d'appareils : tenez compte de la limite de 100 appareils par utilisateur de votre application.
  • Activité et jetons de l'appareil : vous devrez gérer le cycle de vie des appareils et des jetons d'autorisation des utilisateurs. Réfléchissez à la durée pendant laquelle les appareils restent actifs et à la façon dont vous gérerez l'actualisation ou la réautorisation des 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 des éléments multimédias : découvrez comment récupérer et gérer correctement le contenu des éléments multimédias à l'aide de baseUrl, y compris les paramètres ou l'authentification nécessaires.
  • Gestion des erreurs : implémentez une gestion des erreurs robuste pour les appels d'API, y compris pour 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 d'appareils sont atteintes.

Le guide Lister et récupérer des éléments multimédias contient des informations supplémentaires, y compris sur le filtrage et le règlement relatif au contenu.

Étapes suivantes