Configurer votre application pour l'API Ambient

Pour commencer à utiliser l'API Ambient, configurez votre projet en activant l'API dans la console d'API Google et en configurant un ID client OAuth 2.0. L'API Ambient utilise OAuth 2.0 pour les applications TV et d'appareils à entrée limitée.

Votre application interagit avec l'API Ambient au nom d'un utilisateur de l'API Ambient. L'utilisateur autorise ces requêtes d'API à l'aide du protocole OAuth 2.0.

L'ID client OAuth 2.0 permet aux utilisateurs de votre application de se connecter, de s'authentifier et donc d'utiliser l'API Ambient. Les API Ambient ne sont pas compatibles avec les comptes de service. Pour utiliser ces API, les utilisateurs doivent être connectés à un compte Google valide.

Configurer votre application

Activez d'abord l'API, puis demandez un ID client OAuth 2.0.

Activer l'API

Avant de pouvoir utiliser l'API Ambient, vous devez l'activer dans votre projet.

  1. Accédez à la console Google APIs.
  2. Dans la barre de menu, sélectionnez un projet ou créez-en un.
  3. Pour ouvrir l'une des API Google Photos, dans le menu de navigation, sélectionnez API et services > Bibliothèque.
  4. Recherchez "API Ambient". Sélectionnez l'API Ambient, puis cliquez sur Activer.

Demander un ID client OAuth 2.0

Pour demander un ID client OAuth et le configurer pour votre application, procédez comme suit : L'API Ambient utilise OAuth 2.0 pour les applications TV et d'appareils à entrée limitée.

  1. Accédez à la console Google APIs, puis sélectionnez votre projet.
  2. Dans le menu, sélectionnez API et services > Identifiants.

  3. Sur la page Identifiants, cliquez sur Créer des identifiants > ID client OAuth.

  4. Sélectionnez le type d'application. Dans cet exemple, le type d'application est Téléviseurs et périphériques à saisie limitée.

  5. Attribuez un nom à votre client OAuth 2.0, puis cliquez sur Créer.

  6. Dans la boîte de dialogue du client OAuth qui s'affiche, copiez les éléments suivants:

    • ID client
    • Code secret du client

Votre application peut accéder aux API Google activées à l'aide de ces valeurs.

Avant de pouvoir lancer une application publique qui accède à l'API Ambient, votre application doit être examinée par Google. Un message "Application non validée" s'affiche à l'écran lorsque vous testez votre application, jusqu'à ce qu'elle soit validée.

Une fois votre application configurée, vous pouvez commencer. Vous pouvez consulter les ressources suivantes ou en savoir plus sur le flux d'authentification simplifié pour l'API Ambient.

Modifier votre ID client

Les ressources créées via l'une des API Google Photos ne peuvent être consultées ni modifiées qu'à l'aide de l'ID client d'origine utilisé pour les créer. Par exemple, si vous créez un session dans l'API Picker avec un ID client spécifique et que vous modifiez cet ID client ultérieurement dans votre application, votre application perdra l'accès à toutes les ressources API créées avec l'ID client précédent.

Planifiez soigneusement et choisissez le bon type d'ID client pour l'API Photos que vous utilisez. Ne modifiez votre ID client que si cela est absolument nécessaire pour éviter les problèmes d'accès.

Flux d'authentification simplifié pour l'API Ambient

Le flux d'authentification standard de l'API Ambient nécessite que vos utilisateurs scannent deux codes QR:

  • Une première fois pour se connecter à son compte Google (s'il n'est pas déjà connecté).
  • Un deuxième qui permet d'associer l'appareil Ambient nouvellement créé à son compte Google Photos, dans lequel il peut sélectionner les éléments multimédias à afficher.

Le flux simplifié vous permet de fournir un seul code QR à vos utilisateurs en transmettant le paramètre state supplémentaire avec votre appel d'authentification initial.

Lorsque vous demandez des codes d'appareil et d'utilisateur dans le cadre d'OAuth pour les appareils à entrée limitée, incluez le paramètre state supplémentaire avec votre requête. Ajoutez ce qui suit au paramètre state:

Paramètres
requestId

string

Obligatoire. Identifiant unique fourni par le client pour cette requête. Cela permet de limiter la duplication de ressources en cas de défaillance du réseau.

Cet ID doit avoir le format d'une chaîne UUID (version 4) et respecter les exigences suivantes:

  • Ne doit pas contenir d'informations d'identification sensibles sur l'utilisateur.
  • Doit contenir 32 caractères hexadécimaux divisés en cinq groupes séparés par des tirets, au format "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (ou 8-4-4-4-12).
displayName

string

Facultatif. Nom à afficher défini par l'utilisateur pour cet appareil.

Les utilisateurs pourront le voir dans les paramètres de l'application Google Photos, mais ne pourront le modifier que via cette API.

Les noms à afficher valides doivent comporter entre 1 et 100 caractères (inclus).

Par exemple, consultez le bloc de code suivant:

    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"
            })
        })
    });

Si la réponse est positive, elle inclut un user_code et un verification_url, que vous montrez à l'utilisateur (le plus souvent sous forme de code QR) afin qu'il puisse y accéder sur un autre appareil. En incluant le paramètre state, lorsque vous appelez ultérieurement createDevice avec l'API Ambient, vous pouvez ignorer la présentation de settingsUri dans un deuxième code QR, car la dernière étape du flux OAuth redirige automatiquement vers cet emplacement.

Pour en savoir plus, consultez une explication plus détaillée. Vous pouvez également consulter le code de notre application exemple pour voir comment utiliser le paramètre state dans le cadre d'OAuth pour les appareils à entrée limitée avec l'API Ambient.

Informations sur le flux d'authentification simplifié

Pour comprendre pleinement le flux OAuth simplifié pour l'API Ambient, il est utile de comprendre à la fois le flux OAuth 2.0 pour les applications TV et d'appareils à entrée limitée, ainsi que le flux standard de l'API Ambient. Voici la procédure à suivre pour chaque flux.

OAuth 2.0 pour les applications TV et d'appareils à entrée limitée :

  1. Votre application envoie une requête au serveur d'autorisation de Google qui identifie les champs d'application auxquels votre application demandera l'autorisation d'accéder.
  2. Le serveur répond avec plusieurs informations utilisées dans les étapes suivantes, telles qu'un code d'appareil et un code utilisateur.
  3. Vous affichez des informations que l'utilisateur peut saisir sur un autre appareil pour autoriser votre application.
  4. Votre application commence à interroger le serveur d'autorisation de Google pour déterminer si l'utilisateur a autorisé votre application.
  5. L'utilisateur passe à un appareil doté de fonctionnalités de saisie plus riches, lance un navigateur Web, accède à l'URL affichée à l'étape 3 et saisit un code également affiché à l'étape 3. L'utilisateur peut alors accorder (ou refuser) l'accès à votre application.
  6. La prochaine réponse à votre requête de sondage contient les jetons dont votre application a besoin pour autoriser les requêtes au nom de l'utilisateur. (Si l'utilisateur a refusé l'accès à votre application, la réponse ne contient pas de jetons.)

Flux de l'API Ambient:

  1. Recherchez un jeton OAuth existant, puis actualisez-le ou demandez-en un nouveau.
  2. Après avoir obtenu un jeton OAuth, créez un appareil.
  3. Affichez settingsUri à l'utilisateur et commencez à interroger l'appareil jusqu'à ce que mediaSourcesSet renvoie la valeur "true".
  4. L'utilisateur accède à settingsUri et sélectionne les photos qu'il souhaite partager avec votre application.
  5. Une fois que mediaSourcesSet renvoie "true", récupérez la liste des mediaItems.
  6. Vous pouvez maintenant lancer votre diaporama ou toute autre expérience ambiante.

Les deux flux incluent une étape au cours de laquelle vous affichez une URL à l'utilisateur, qui y accède sur son appareil d'entrée plus riche. En incluant le paramètre state dans votre appel OAuth initial, vous pouvez éviter d'afficher la deuxième URL.

Cela fonctionne, car la dernière étape du flux OAuth 2.0 pour les applications de télévision et d'appareils à entrée limitée redirige normalement votre utilisateur vers une page indiquant "Vous pouvez maintenant retourner à votre appareil". En incluant le paramètre d'état, la dernière étape du flux tentera désormais de vous rediriger vers settingsUri. Votre application recevra toujours un jeton OAuth. Vous devez utiliser ce jeton pour appeler createDevice à l'aide du même requestId. Une fois qu'un appareil avec le même ID a été créé, le flux OAuth initial redirige votre utilisateur vers la bonne page sur l'appareil enrichi dans l'application Photos.

Gardez à l'esprit les points suivants:

  • Il est toujours conseillé d'afficher settingsUri en cas de problème d'authentification.
  • Vous pouvez toujours utiliser settingsUri dans d'autres cas, par exemple lorsqu'un utilisateur souhaite modifier sa sélection de photos.