Übersicht
Dieses Dokument führt Sie durch ein vollständiges Beispiel für die Verwendung der Embed API. Danach erhältst du eine Anwendung, die so aussieht.
Einfaches Dashboard erstellen
Sie können die Beispielanwendung mit den folgenden zwei einfachen Schritten auf Ihrem Server ausführen:
- Neue Client-ID erstellen
- Code kopieren und einfügen
Sobald diese Anwendung eingerichtet ist, wird im nächsten Abschnitt ausführlich erläutert, wie alle Teile zusammenpassen.
Neue Client-ID erstellen
Die Embed API übernimmt fast den gesamten Autorisierungsprozess. Dazu stellen Sie eine Anmeldekomponente mit einem Klick bereit, die den bekannten OAuth 2.0-Vorgang verwendet. Damit diese Schaltfläche auf deiner Seite funktioniert, benötigst du eine Client-ID.
Wenn du noch nie eine Client-ID erstellt hast, kannst du das mithilfe dieser Anleitung tun.
Beim Durchgehen der Anleitung sollten Sie diese beiden wichtigen Schritte nicht übersehen:
- Analytics API aktivieren
- Den richtigen Ursprung festlegen
Die Ursprünge steuern, welche Domains diesen Code zur Autorisierung von Nutzern verwenden dürfen. Dadurch wird verhindert, dass andere den Code kopieren und auf seiner Website ausführen.
Wenn deine Website beispielsweise in der Domain beispiel.de gehostet wird, musst du für deine Client-ID http://example.com den folgenden Ursprung angeben. Wenn Sie Ihren Code lokal testen möchten, müssen Sie auch den Ursprung für Ihren lokalen Server hinzufügen, z. B. http://localhost:8080.
Code kopieren und einfügen
Sobald Sie Ihre Client-ID mit den richtigen Ursprüngen haben, können Sie die Demo erstellen. Kopieren Sie einfach den folgenden Code und fügen Sie ihn in eine HTML-Datei auf Ihrem Server ein. Fügen Sie dort Ihre Client-ID ein: "Geben Sie hier Ihre Client-ID ein".
<!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>
Schritt-für-Schritt-Anleitung für den Code
In diesem Abschnitt wird Schritt für Schritt erklärt, was genau im Code für die Beispielanwendung passiert. Sobald Sie mit der Funktionsweise vertraut sind, sollten Sie eigene erstellen können.
Schritt 1: Komponentencontainer erstellen
Die meisten Embed API-Komponenten rendern etwas auf deiner Seite. Sie können steuern, wohin diese Komponenten führen, indem Sie Container für sie erstellen. In der Beispielanwendung gibt es eine Schaltfläche für die Authentifizierung, eine Auswahl für die Ansicht und ein Diagramm. Jede dieser Komponenten wird in den folgenden HTML-Elementen gerendert:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Wenn Sie eine Komponente erstellen, geben Sie anhand des ID-Attributs an, welcher Container verwendet werden soll. Dies wird in den späteren Beispielen gezeigt.
Schritt 2: Bibliothek laden
Die Embed API kann mit dem folgenden Snippet geladen werden.
<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>
Wenn die Bibliothek vollständig geladen ist, werden alle an gapi.analytics.ready übergebenen Callbacks aufgerufen.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Schritt 3: Nutzer autorisieren
Die Embed API übernimmt fast den gesamten Autorisierungsprozess. Dazu stellt sie eine Anmeldekomponente mit einem Klick bereit, die den bekannten OAuth 2.0-Vorgang verwendet. Damit diese Schaltfläche auf deiner Seite funktioniert, musst du eine Containerreferenz und deine Client-ID einfügen.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Dadurch wird innerhalb des Elements eine Schaltfläche mit der ID der Authentifizierungsschaltfläche generiert, die den Autorisierungsvorgang übernimmt.
Schritt 4: Ansichtsauswahl erstellen
Mit der Komponente „Datenansichtsauswahl“ können Sie die IDs einer bestimmten Datenansicht abrufen und einen Bericht dafür erstellen.
Zum Erstellen einer Ansichtsauswahl benötigen Sie lediglich die Containerreferenz, die Sie in Schritt 1 erstellt haben.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Dadurch wird die Komponente für die Ansichtsauswahl erstellt, auf der Seite wird sie aber noch nicht gerendert. Dazu müssen Sie execute() aufrufen, was in Schritt 6 verarbeitet wird.
Schritt 5: Zeitachsendiagramm erstellen
Über die Embed API erhalten Sie eine Diagrammkomponente, die sowohl ein Google-Diagramm als auch ein Berichtsobjekt in einem Diagramm ist. Dies vereinfacht die Anzeige von Daten erheblich, da das Diagrammobjekt Ihre Berichte im Hintergrund ausführt und automatisch mit den Ergebnissen aktualisiert wird.
Zum Erstellen einer Diagrammkomponente müssen Sie die API-Abfrageparameter sowie die Diagrammoptionen angeben. Die Diagrammoptionen enthalten einen Verweis auf die ID des Containers, den Sie in Schritt 1 erstellt haben.
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'
}
});
Wie bei der Ansichtsauswahl wird dabei die Diagrammkomponente erstellt, aber zum Rendern auf der Seite müssen Sie execute() aufrufen, was im nächsten Schritt erläutert wird.
Schritt 6: Komponenten für die Zusammenarbeit nutzen
Embed API-Komponenten geben Ereignisse aus, wenn verschiedene Dinge passieren, z. B. erfolgreiche Autorisierung, Auswahl einer neuen Ansicht oder vollständig gerendertes Diagramm.
Die Beispielanwendung in diesem Leitfaden wartet, bis die Ansichtsauswahl gerendert wird, bis sie abgeschlossen ist, und aktualisiert das Zeitachsendiagramm, wenn eine neue Ansicht aus der Ansichtsauswahl ausgewählt wird.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Eine vollständige Liste aller Ereignisse, die von den verschiedenen Komponenten ausgegeben werden, finden Sie in der API-Referenz.
Next Steps
In diesem Leitfaden wurde erläutert, wie Sie eine grundlegende Visualisierung mit der Embed API erstellen. Weitere Informationen finden Sie in der API-Referenz.