Documentation de référence sur les composants intégrés

Ce document décrit les options, les méthodes, les propriétés et les événements de tous les composants intégrés de l'API Embed.

auth, authentification, authentifier

gapi.analytics.auth

Le composant auth est un singleton qui peut être utilisé pour autoriser un utilisateur.

Méthodes
authorize(options:Object)	Renvoie:  gapi.analytics.auth Affiche un bouton de connexion à Google Analytics dans le conteneur spécifié, permettant à l'utilisateur de se connecter avec son compte Google.
isAuthorized()	Renvoie:  boolean Renvoie true si l'utilisateur a obtenu l'autorisation, et false dans le cas contraire.
signOut()	Renvoie:  gapi.analytics.auth Déconnexion de l'utilisateur actuel. Déclenche également l'événement signOut.
getAuthResponse()	Renvoie:  Object Récupère les données d'authentification renvoyées par la requête d'autorisation d'origine. L'objet renvoyé inclut le jeton d'accès, qui peut généralement effectuer manuellement des requêtes authentifiées.
getUserProfile()	Renvoie:  Object Récupère des informations de profil de base sur l'utilisateur actuellement connecté. Cela inclut le nom, l'adresse e-mail et l'image de profil public de l'utilisateur (le cas échéant).

Méthodes héritées
on
once
off

Options
clientId	Type:string ID client de votre projet dans la console pour les développeurs.
container	Type:string|HTMLElement ID d'un élément HTML dans le DOM qui hébergera le bouton de connexion. Vous pouvez également transmettre une référence à l'élément lui-même.
userInfoLabel	Type:string Texte à afficher avant l'adresse e-mail d'un utilisateur connecté. La valeur par défaut est 'You are logged in as: '.
scopes	Type:Array Liste des champs d'application d'authentification des API Google demandés par votre application. Pour voir tous les champs d'application disponibles, accédez à OAuth 2.0 Playground. Pour les champs d'application d'authentification de l'API Google Analytics, consultez les guides du développeur pour les ressources Configuration et Création de rapports.
overwriteDefaultScopes	Type:boolean Indique si l'option scopes remplace les champs d'application de l'API Embed par défaut ou les ajoute. Si vous indiquez false (valeur par défaut), les champs d'application par défaut seront ajoutés, et true les remplacera par ceux spécifiés par l'option scopes. La valeur par défaut des champs d'application est ['https://www.googleapis.com/auth/analytics.readonly']. Remarque: L'authentification via l'API Embed nécessite l'accès au profil de base de l'utilisateur. Ces champs d'application ne peuvent pas être remplacés.
serverAuth.access_token	Type:string Si vous disposez déjà d'un jeton d'accès valide, vous pouvez le transmettre directement à la méthode d'autorisation. L'utilisateur ne sera alors pas invité à donner son autorisation. Pour savoir comment récupérer un jeton d'accès, consultez la documentation OAuth 2.0.

Événements
signIn	Arguments:aucun Déclenché lorsque l'utilisateur s'est connecté avec succès.
signOut	Arguments:aucun Déclenché lorsque l'utilisateur s'est déconnecté avec succès.
needsAuthorization	Arguments:aucun Lorsque vous appelez la méthode gapi.analytics.auth.authorize, une vérification initiale est effectuée pour voir si l'utilisateur est actuellement connecté. Si l'utilisateur n'est pas connecté, cet événement est déclenché pour indiquer qu'une autorisation supplémentaire est requise.
error	Arguments:response Déclenché lorsqu'une erreur se produit pendant le processus d'authentification. Si vous souhaitez obtenir le message d'erreur de l'objet de réponse, il se trouve à l'adresse response.error.message.

Événements obsolètes
success	Arguments:response Cet événement existe pour assurer la rétrocompatibilité et peut être supprimé dans une prochaine version. Utilisez plutôt l'événement signIn.

Exemple

// Standard client-side authorization.

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

gapi.analytics.auth.on('signIn', function() {
  console.log(gapi.analytics.auth.getUserProfile());
});

// Authorization using an access token obtained server-side.
// You do not need to register an event handler because
// authorization happens immediately.

gapi.analytics.auth.authorize({
  serverAuth: {
    access_token: 'XXXXXX'
  }
});

Remarque:L'autorisation est effective immédiatement lorsque vous utilisez serverAuth.access_token. Il n'est donc pas nécessaire d'enregistrer un gestionnaire d'événements.

Important:Lorsque vous utilisez serverAuth.access_token, il vous appartient de vous assurer que le jeton est valide et qu'il n'a pas expiré. Pour savoir comment actualiser un jeton d'accès expiré, consultez la documentation OAuth 2.0.

Données

gapi.analytics.report.Data

Constructeur
Data(options:Object)	Le composant Data vous permet d'interroger l'API Core Reporting de Google Analytics et d'obtenir les résultats.

Options
query	Type:Object Objet contenant des paramètres de requête de l' API Core Reporting. Les valeurs par défaut suivantes sont utilisées en plus des valeurs par défaut standards fournies par l'API: { 'start-date': '7daysAgo', 'end-date': 'yesterday }

Méthodes héritées
get
set
execute
on
once
off
emit

Événements
success	Arguments:response Déclenché lorsque la requête est terminée
error	Arguments:response Déclenché lorsqu'une erreur se produit pendant le processus de requête. Si vous souhaitez obtenir le message d'erreur de l'objet de réponse, il se trouve à l'adresse response.error.message.

Exemple

var report = new gapi.analytics.report.Data({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:city'
  }
});

report.on('success', function(response) {
  console.log(response);
});

report.execute();

DataChart

gapi.analytics.googleCharts.DataChart

Constructeur
DataChart(options:Object)	DataChart encapsule un graphique Google standard et un composant Data pour vous permettre de créer facilement une visualisation à partir d'une requête, sans avoir à la relier vous-même.

Options
query	Type:Object Consultez l'option de requête du composant de données.
chart	Type:Object Pour en savoir plus sur les différentes options de graphique, consultez les informations ci-dessous.
chart.container	Type:string|HTMLElement ID d'un élément HTML dans le DOM qui hébergera le DataChart. Vous pouvez également transmettre une référence à l'élément lui-même.
chart.type	Type:string Type de graphique. Les options possibles sont LINE, COLUMN, BAR, TABLE et GEO.
chart.options	Type:Object Toutes les options pouvant être transmises à l'objet Google Chart correspondant

Méthodes héritées
get
set
execute
on
once
off
emit

Événements
success	Arguments:result Déclenché lorsque la requête est exécutée correctement et que le graphique s'affiche entièrement. result.chart : instance de graphique Google. result.data : réponse du rapport au format de paramètre de données. result.dataTable : instance DataTable créée à partir de l'objet result.data. result.response : objet de réponse brut de l'API.
error	Arguments:response Déclenché lorsqu'une erreur se produit pendant le processus de requête ou d'affichage Si vous souhaitez obtenir le message d'erreur de l'objet de réponse, il se trouve à l'adresse response.error.message.

Exemple

var chart = new gapi.analytics.googleCharts.DataChart({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:date'
  },
  chart: {
    type: 'LINE',
    container: 'line-chart',
    options: {
      title: 'Sessions over the past week.',
      fontSize: 12
    }
  }
});
chart.on('success', function(response) {
  // response.chart : the Google Chart instance.
  // response.data : the Google Chart data object.
});

chart.execute();

ViewSelector

gapi.analytics.ViewSelector

Constructeur
ViewSelector(options:Object)	Le composant ViewSelector vous permet de sélectionner votre compte, votre propriété et votre vue via des menus déroulants.

Options
container	Type:string|HTMLElement ID d'un élément HTML dans le DOM qui héberge le ViewSelect. Vous pouvez également transmettre une référence à l'élément lui-même.

Méthodes héritées
get
set
execute
on
once
off
emit

Propriétés de l'instance
ids	Type:string ID de table unique au format ga:XXXX, où XXXX correspond à l'ID de la vue (profil) Analytics.

Événements
change	Arguments:ids Déclenché chaque fois que l'utilisateur sélectionne une nouvelle vue dans les menus déroulants Il se déclenche également lorsque l'instance ViewSelect est affichée pour la première fois et que la vue par défaut s'affiche.

Exemple

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

viewSelector.on('change', function(ids) {
  console.log(ids);
});

viewSelector.execute();

Méthodes du composant partagé

Méthodes
set(options)	returns:this Définit ou met à jour les options de configuration du composant (cela peut également être fait au moment de la création dans le constructeur).
get()	returns:Object Renvoie les options de configuration actuelles d'un composant.
execute()	returns:this Permet d'appeler l'action principale du composant. Cela entraîne généralement l'affichage d'un élément sur la page ou l'exécution d'un rapport (ou les deux).
on(event, handler)	returns:this Enregistre une fonction à appeler lorsque le composant émet l'événement spécifié.
once(event, handler)	returns:this Enregistre une fonction à appeler uniquement lors de la prochaine occurrence de l'événement spécifié. Après l'exécution du gestionnaire, une fois l'enregistrement automatique annulé.
off(opt_event, opt_handler)	returns:undefined Supprime un gestionnaire d'événements d'un composant. Si aucun gestionnaire n'est transmis, cette opération supprime tous les gestionnaires de l'événement transmis. Si aucun événement n'est transmis, tous les gestionnaires sont supprimés pour tous les événements.
emit(event, ...opt_args)	returns:undefined Émet un événement. Vous pouvez éventuellement spécifier les arguments à transmettre à tous les gestionnaires enregistrés.

set

Définit ou met à jour les options de configuration du composant (cela peut également être fait au moment de la création dans le constructeur).

Utilisation

component.set(options);

Paramètres

Nom	Type	Description
options	Object	Options de configuration pour ce composant. Les options transmises seront fusionnées avec les options existantes.

Renvoie

this : instance du composant.

---

get

Renvoie les options de configuration actuelles d'un composant.

Renvoie

Object : options de configuration actuelles du composant.

---

execute()

Permet d'appeler l'action principale du composant. Cela entraîne généralement l'affichage d'un élément sur la page ou l'exécution d'un rapport (ou les deux).

Renvoie

this : instance du composant.

---

on(event, handler)

Enregistre une fonction à appeler lorsque le composant émet l'événement spécifié.

Paramètres

Nom	Type	Description
event	string	Nom de l'événement.
handler	Function	Fonction à appeler lorsque l'événement se produit. Reportez-vous aux références des événements individuels pour en savoir plus sur les paramètres.

Renvoie

this : instance du composant.

---

once(event, handler)

Enregistre une fonction à appeler uniquement lors de la prochaine occurrence de l'événement spécifié. Après l'exécution du gestionnaire, une fois l'enregistrement automatique annulé.

Paramètres

Nom	Type	Description
event	string	Nom de l'événement.
handler	Function	Fonction à appeler lorsque l'événement se produit. Reportez-vous aux références des événements individuels pour en savoir plus sur les paramètres.

Renvoie

this : instance du composant.

---

off(opt_event, opt_handler)

Supprime un gestionnaire d'événements d'un composant. Si aucun gestionnaire n'est transmis, cette opération supprime tous les gestionnaires de l'événement transmis. Si aucun événement n'est transmis, tous les gestionnaires sont supprimés pour tous les événements.

Paramètres

Nom	Type	Description
opt_event	string	Nom de l'événement. Si aucun événement n'est spécifié, tous les gestionnaires de tous les événements sont supprimés. Facultatif.
opt_handler	Function	Référence au gestionnaire de fonctions à supprimer. Si aucune fonction n'est transmise, tous les gestionnaires sont supprimés. Facultatif.

Renvoie

undefined

---

emit(event, ...opt_args)

Émet un événement. Vous pouvez éventuellement spécifier les arguments à transmettre à tous les gestionnaires enregistrés.

Paramètres

Nom	Type	Description
event	string	Nom de l'événement.
...opt_args	*	Arguments facultatifs à transmettre à tous les gestionnaires d'événements enregistrés.

Renvoie

undefined