Premiers pas

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Présentation

Ce document vous présente un exemple complet d'utilisation de l'API Embed. Une fois l'opération terminée, vous aurez une application qui ressemble à ceci.

Capture d'écran d'un exemple abordé dans ce guide
Capture d'écran de l'exemple décrit dans ce guide

Créer un tableau de bord simple

Vous pouvez exécuter l'exemple d'application sur votre serveur en suivant ces deux étapes simples:

  1. Créer un ID client
  2. Copier et coller le code

Une fois que cette application est opérationnelle, la section suivante explique comment tous les éléments s'assemblent.

Créer un ID client

L'API Embed gère presque tout le processus d'autorisation en fournissant un composant de connexion en un clic qui utilise le flux OAuth 2.0, bien connu de tous. Pour que ce bouton fonctionne sur votre page, vous devez disposer d'un ID client.

Si vous n'avez jamais créé d'ID client, vous pouvez le faire en suivant ces instructions.

Pendant que vous suivez les instructions, il est important de ne pas omettre ces deux étapes critiques:

  • Activer l'API Analytics
  • Définir les bonnes origines

Les origines déterminent les domaines autorisés à utiliser ce code pour autoriser les utilisateurs. Cela empêche les autres utilisateurs de copier votre code et de l'exécuter sur leur site.

Par exemple, si votre site Web est hébergé sur le domaine example.com, veillez à définir l'origine suivante pour votre ID client http://example.com. Si vous souhaitez tester votre code localement, vous devez également ajouter l'origine de votre serveur local, par exemple : http://localhost:8080.

Copier et coller le code

Une fois que vous disposez de votre ID client avec les origines définies, vous pouvez créer la version de démonstration. Copiez le code suivant et collez-le dans un fichier HTML sur votre serveur, en saisissant votre ID client où il apparaît: "Insérer votre ID client ici".

<!DOCTYPE html>
<html>
<head>
  <title>Embed API Demo</title>
</head>
<body>

<!-- Step 1: Create the containing elements. -->

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

<!-- Step 2: Load the library. -->

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<script>
gapi.analytics.ready(function() {

  // Step 3: Authorize the user.

  var CLIENT_ID = 'Insert your client ID here';

  gapi.analytics.auth.authorize({
    container: 'auth-button',
    clientid: CLIENT_ID,
  });

  // Step 4: Create the view selector.

  var viewSelector = new gapi.analytics.ViewSelector({
    container: 'view-selector'
  });

  // Step 5: Create the timeline chart.

  var timeline = new gapi.analytics.googleCharts.DataChart({
    reportType: 'ga',
    query: {
      'dimensions': 'ga:date',
      'metrics': 'ga:sessions',
      'start-date': '30daysAgo',
      'end-date': 'yesterday',
    },
    chart: {
      type: 'LINE',
      container: 'timeline'
    }
  });

  // Step 6: Hook up the components to work together.

  gapi.analytics.auth.on('success', function(response) {
    viewSelector.execute();
  });

  viewSelector.on('change', function(ids) {
    var newIds = {
      query: {
        ids: ids
      }
    }
    timeline.set(newIds).execute();
  });
});
</script>
</body>
</html>

Tutoriel de code

Cette section vous explique pas à pas ce qui se passe dans le code fourni pour l'exemple d'application. Une fois que vous comprenez son fonctionnement, vous devriez pouvoir créer les vôtres.

Étape 1: Créez les conteneurs du composant

La plupart des composants de l'API Embed affichent un élément visuellement sur votre page. Pour contrôler l'emplacement de ces composants, vous pouvez créer des conteneurs. Dans l'exemple d'application, nous avons un bouton d'authentification, un sélecteur de vue et un graphique. Chacun de ces composants est affiché dans les éléments HTML suivants:

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

Lorsque vous créez un composant, vous lui indiquez le conteneur à utiliser avec son attribut d'ID, comme vous le verrez dans les exemples suivants.

Étape 2: Chargez la bibliothèque

L'API Embed peut être chargée avec l'extrait de code suivant.

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

Une fois la bibliothèque entièrement chargée, tous les rappels transmis à gapi.analytics.ready sont appelés.

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

Étape 3: Autorisez l'utilisateur

L'API Embed gère pour presque tout le processus d'autorisation en fournissant un composant de connexion en un clic qui utilise le flux OAuth 2.0 habituel. Pour que ce bouton fonctionne sur votre page, vous devez transmettre une référence de conteneur et votre ID client.

gapi.analytics.auth.authorize({
  container: 'auth-button',
  clientid: CLIENT_ID,
});

Un bouton est alors généré à l'intérieur de l'élément avec l'identifiant "&-39;auth-button'" qui se charge du flux d'autorisation à votre place.

Étape 4: Créez le sélecteur de vue

Le composant de sélecteur de vue permet d'obtenir les identifiants d'une vue spécifique et d'exécuter un rapport la concernant.

Pour créer un sélecteur de vue, il vous suffit de disposer de la référence de conteneur que vous avez créée à l'étape 1.

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

Le composant de sélecteur de vue est alors créé, mais il ne s'affiche pas encore sur la page. Pour ce faire, vous devez appeler execute(), qui est géré à l'étape 6.

Étape 5: Créez le graphique chronologique

L'API Embed fournit un composant de graphique qui est à la fois un graphique Google et un objet de rapport. Cela simplifie considérablement le processus d'affichage des données, car l'objet de graphique exécute vos rapports en arrière-plan et se met automatiquement à jour avec les résultats.

Pour créer un composant de graphique, vous devez spécifier les paramètres de requête de l'API ainsi que les options du graphique. Les options du graphique font référence à l'ID du conteneur que vous avez créé à l'étape 1.

var timeline = new gapi.analytics.googleCharts.DataChart({
  reportType: 'ga',
  query: {
    'dimensions': 'ga:date',
    'metrics': 'ga:sessions',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
  },
  chart: {
    type: 'LINE',
    container: 'timeline'
  }
});

Comme pour le sélecteur de vue, vous créez ainsi le composant de graphique. Toutefois, pour l'afficher sur la page, vous devez appeler execute(), comme expliqué à l'étape suivante.

Étape 6: Associez les composants pour qu'ils fonctionnent ensemble

Les composants d'API Embed génèrent des événements lorsque divers événements se produisent, tels que l'autorisation réussie, la sélection d'une nouvelle vue ou l'affichage complet d'un graphique.

L'exemple d'application de ce guide attend d'afficher le sélecteur de vue jusqu'à ce qu'il se produise une fois qu'une autorisation a été effectuée et met à jour le graphique de la chronologie chaque fois qu'une nouvelle vue est sélectionnée dans le sélecteur.

gapi.analytics.auth.on('success', function(response) {
  viewSelector.execute();
});

viewSelector.on('change', function(ids) {
  var newIds = {
    query: {
      ids: ids
    }
  }
  timeline.set(newIds).execute();
});

Pour obtenir la liste complète des événements émis par les différents composants, consultez la documentation de référence de l'API.

Next Steps

Ce guide vous a montré comment créer une visualisation de base à l'aide de l'API Embed. Si vous souhaitez en savoir plus, consultez la documentation de référence de l'API pour en savoir plus sur ce qui est possible.