Überblick
In diesem Dokument wird anhand eines vollständigen Beispiels für die Verwendung der Embed API erläutert. Anschließend haben Sie eine Anwendung, die so aussieht.
Ein einfaches Dashboard erstellen
Mit diesen beiden einfachen Schritten können Sie die Beispielanwendung auf Ihrem Server ausführen:
- Neue Client-ID erstellen
- Code kopieren und einfügen
Nachdem Sie diese Anwendung eingerichtet und ausgeführt haben, wird im nächsten Abschnitt ausführlich erklärt, wie die einzelnen Teile zusammenpassen.
Neue Client-ID erstellen
Die Embed API übernimmt fast den gesamten Autorisierungsprozess für dich. Sie stellt eine Anmeldekomponente mit einem Klick bereit, die den bekannten OAuth 2.0-Vorgang verwendet. Sie benötigen eine Client-ID, damit diese Schaltfläche auf Ihrer Seite funktioniert.
Wenn du noch keine Client-ID erstellt hast, kannst du das tun, indem du dieser Anleitung folgst.
Bei der Durcharbeitung der Anleitung ist es wichtig, dass Sie diese beiden wichtigen Schritte nicht übersehen:
- Analytics API aktivieren
- Legen Sie die richtigen Ursprünge fest
Die Ursprünge steuern, welche Domains diesen Code zum Autorisieren von Nutzern verwenden dürfen. Dies verhindert, dass andere Personen Ihren Code kopieren und auf ihrer Website ausführen.
Wenn Ihre Website beispielsweise in der Domain beispiel.de gehostet wird, müssen Sie den folgenden Ursprung für Ihre Client-ID http://example.com festlegen. Wenn Sie den Code lokal testen möchten, müssen Sie auch den Ursprung für Ihren lokalen Server hinzufügen. Beispiel: http://localhost:8080.
Code kopieren und einfügen
Sobald Sie Ihre Client-ID mit den richtigen Ursprüngen festgelegt 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 an der Stelle ein, wo der Text lautet: „Fügen Sie Ihre Client-ID hier 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>
Code-Schritt-für-Schritt-Anleitung
In diesem Abschnitt werden Sie Schritt für Schritt genau durch den Code geführt, der für die Beispielanwendung bereitgestellt wurde. Sobald Sie wissen, wie es funktioniert, können Sie Ihre eigenen erstellen.
Schritt 1: Komponentencontainer erstellen
Die meisten Embed API-Komponenten werden visuell auf Ihrer Seite gerendert. Sie können steuern, wo diese Komponenten platziert werden, indem Sie dafür Container erstellen. Die Beispielanwendung verfügt über eine Authentifizierungsschaltfläche, einen Ansichtsselektor und ein Diagramm. Jede dieser Komponenten wird innerhalb der folgenden HTML-Elemente gerendert:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Beim Erstellen einer Komponente geben Sie über das entsprechende ID-Attribut an, welcher Container verwendet werden soll, wie in den späteren Beispielen gezeigt wird.
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 für dich. Sie stellt eine Anmeldekomponente mit einem Klick bereit, die den bekannten OAuth 2.0-Vorgang verwendet. Damit diese Schaltfläche auf Ihrer Seite funktioniert, müssen Sie einen Container-Verweis und Ihre Client-ID übergeben.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Dadurch wird im Element eine Schaltfläche mit der ID „auth-button“ generiert, die den Autorisierungsvorgang für Sie übernimmt.
Schritt 4: Auswahl für die Datenansicht erstellen
Mit der Komponente „Ansichtenauswahl“ lassen sich die IDs einer bestimmten Ansicht abrufen, um einen Bericht für die Datenansicht zu erstellen.
Zum Erstellen eines Ansichtenselektors benötigen Sie lediglich den Containerverweis, den Sie in Schritt 1 erstellt haben.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Dadurch wird die Komponente für die Ansichtsauswahl erstellt, aber noch nicht auf der Seite gerendert. Dazu müssen Sie execute() aufrufen, was in Schritt 6 behandelt wird.
Schritt 5: Zeitachsendiagramm erstellen
Die Embed API bietet eine Diagrammkomponente, die sowohl ein Google-Diagramm als auch ein Berichtsobjekt in einem ist. Dies vereinfacht das Anzeigen von Daten erheblich, da das Diagrammobjekt Ihre Berichte im Hintergrund ausführt und sich automatisch mit den Ergebnissen aktualisiert.
Zum Erstellen einer Diagrammkomponente müssen Sie die API-Abfrageparameter sowie die Diagrammoptionen angeben. In den Diagrammoptionen finden Sie 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 die Diagrammkomponente erstellt. Um sie auf der Seite zu rendern, müssen Sie jedoch execute() aufrufen, was im nächsten Schritt erläutert wird.
Schritt 6: Komponenten verknüpfen, um zusammenzuarbeiten
Embed API-Komponenten geben Ereignisse aus, wenn verschiedene Dinge eintreten, z. B. eine erfolgreiche Autorisierung, die Auswahl einer neuen Ansicht oder ein vollständig gerendertes Diagramm.
Die Beispielanwendung in diesem Leitfaden wartet mit dem Rendern der Ansichtsauswahl, bis die Autorisierung erfolgt ist, und aktualisiert das Zeitachsendiagramm, sobald eine neue Ansicht über die 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 ausgelöst werden, findest du in der API-Referenz.
Nächste Schritte
In dieser Anleitung wurde beschrieben, wie Sie mit der Embed API eine einfache Visualisierung erstellen. Weitere Informationen zu den Möglichkeiten finden Sie in der API-Referenz.