Présentation
Ce document présente un exemple complet d'utilisation de l'API Embed. Une fois l'opération terminée, votre application se présente comme suit :
Création d'un tableau de bord simple
Vous pouvez exécuter l'exemple d'application sur votre serveur en suivant ces deux étapes simples:
- Créer un ID client
- Copiez et collez le code
Une fois cette application opérationnelle, la section suivante explique en détail comment tous les éléments s'imbriquent.
Créer un ID client
L'API Embed gère la quasi-totalité du processus d'autorisation à votre place en fournissant un composant de connexion en un clic qui utilise le flux OAuth 2.0 que vous connaissez. Pour que ce bouton fonctionne sur votre page, vous avez besoin d'un ID client.
Si vous n'avez jamais créé d'ID client, vous pouvez le faire en suivant ces instructions.
Lorsque vous suivez les instructions, il est important de ne pas négliger ces deux étapes essentielles:
- Activer l'API Analytics
- Définissez les bonnes origines
Les origines contrôlent les domaines autorisés à utiliser ce code pour autoriser des utilisateurs. Cela empêche d'autres personnes 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 en local, vous devez également ajouter l'origine de votre serveur local, par exemple : http://localhost:8080.
Copiez et collez le code
Une fois que vous disposez de votre ID client et des origines appropriées, vous pouvez créer la démonstration. Copiez et collez simplement le code suivant dans un fichier HTML sur votre serveur et connectez votre ID client à l'emplacement suivant: "Insérez 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 du code
Cette section vous guide pas à pas dans le code fourni pour l'exemple d'application. Une fois que vous avez compris comment cela fonctionne, vous devriez être en mesure de créer le vôtre.
Étape 1: Créer les conteneurs de composants
La plupart des composants de l'API Embed affichent un élément visuel sur votre page. Pour contrôler l'emplacement de ces composants, vous devez créer des conteneurs pour eux. L'exemple d'application comporte 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 quel conteneur utiliser à l'aide de son attribut "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 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 la quasi-totalité du processus d'autorisation à votre place en fournissant un composant de connexion en un clic qui utilise le flux OAuth 2.0 que vous connaissez. 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,
});
Cela générera un bouton à l'intérieur de l'élément avec l'ID "auth-button" qui s'occupera 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 particulière afin de pouvoir exécuter un rapport la concernant.
Pour créer un sélecteur de vue, vous n'avez besoin que de la référence de conteneur que vous avez créée à l'étape 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Cette action crée le composant de sélecteur de vue, mais ne l'affiche pas encore sur la page. Pour ce faire, vous devez appeler execute(), géré à l'étape 6.
Étape 5: Créez le graphique chronologique
L'API Embed vous fournit un composant de graphique à la fois sous forme de graphique Google et d'objet de rapport. Cela simplifie considérablement le processus d'affichage des données, car l'objet 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 de 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, cette opération crée le composant de graphique. Toutefois, pour l'afficher sur la page, vous devez appeler execute(), comme expliqué à l'étape suivante.
Étape 6: Raccorder les composants pour qu'ils fonctionnent ensemble
Les composants d'API Embed émettent des événements lorsque divers événements se produisent, tels qu'une autorisation réussie, la sélection d'une nouvelle vue ou un graphique en cours d'affichage complet.
L'exemple d'application de ce guide attend d'afficher le sélecteur de vue jusqu'à ce que l'autorisation ait eu lieu, puis met à jour le graphique chronologique 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 de tous les événements émis par les différents composants, consultez la documentation de référence de l'API.
Étapes suivantes
Ce guide vous a expliqué comment créer une visualisation de base avec l'API Embed. Pour en savoir plus, consultez la documentation de référence de l'API.