AngularJS – Google Analytics Embed API – ngAnalytics

1. Einleitung

In diesem Artikel geht es um die Benutzung der Google Analytics Embed API, um Daten eigener Analytics-Konten, beispielsweise auf Webseiten, anzuzeigen. In diesem Zusammenhang ist ein eigenständiges Modul – ngAnalytics – mit verschiedenen Direktiven entstanden, welches den Umgang mit der API ein wenig vereinfachen soll. Zu Beginn des Beitrags werden die Grundlagen der API erklärt und im Anschluss das Angular-Modul vorgestellt.

2. Voraussetzung

3. Vorbereitung

Wie bei jeder Nutzung einer Google API muss diese erst eingerichtet und aktiviert werden. Für die Google Analytics API müssen folgenden Schritte durchgeführt werden.

  1. Google Entwickler Konsole aufrufen
  2. Projekt anlegen oder vorhandenes öffnen
  3. In der Seitennavigation APIs auswählen
  4. Analytics API suchen und aktivieren
  5. In der Seitennavigation Zugangsdaten auswählen
  6. OAuth Client ID erzeugen, falls noch nicht vorhanden
  7. Client-ID wird später zu Authentifizierung benötigt

4. Einstieg in die API

Ein einfaches Beispiel zur normalen Benutzung der API kann unter https://ga-dev-tools.appspot.com gefunden werden. Hier werden auch die zwei grundlegenden Schritte deutlich.

  1. Embed API einbinden
  2. Authentifizierung/Autorisierung
  3. Inhalt erstellen/anzeigen

4.1 Embed API einbinden

Als ersten Schritt muss natürlich der Google-Code geladen werden, damit die API genutzt werden kann.

Danach kann ein eigener Skrip-Inhalt definiert werden. Es sollte jedoch drauf gewartet werden, dass die Google-API auch fertig geladen ist.

4.2 Authentifizierung/Autorisierung

Google bindet hier automatisch einen Button ein, falls man nicht autorisiert ist. Andernfalls erscheint die E-Mail-Adresse des Google-Accounts.
Dazu benötigt Google einen DOM-Knoten, worin dieser Inhalt angezeigt wird.

Nun wird die erstellte Client-ID benötigt.

4.3 Inhalt erstellen/anzeigen

Nach der Autorisierung können dann die Goolge Analytics Inhalte, wie Diagramme, View-Selektoren oder Daten-Reports angezeigt werden.

  • Diagramm – DataChart – Diagramm mit konfigurierbaren Inhalten
  • View-Selektor – ViewSelector – DropDown-Auswahl von verschiedenen Ansichten und Webseiten
  • Report-Data – ReportData – Anfrage zu bestimmten Daten

4.3.1 DataChart

Ein DataChart ist im allgemeinen ein Diagramm, welches aufbereitete Daten anzeigt. Auch hier vereinfacht Google den Umgang und übernimmt das Anzeigen dieser Komponente. Die einzige Schwierigkeit ist, die richtige Konfiguration zu finden. Es lassen sich einfach Torten-, Linien- und Säulen-Diagramme erzeugen. Damit Google weiß, wo das Diagramm dargestellt werden soll, wird auch hier wieder ein extra DOM-Knoten benötigt.

Nach dem Authentifizieren kann nun ein Diagramm erstellt werden, welches mit dem DOM-Knoten verknüpft wird.

Im Quellcode zur Diagrammerzeugung gibt es einen Schlüssel mit dem Namen ids. Hier wird eine (oder mehrere) View-Id eingetragen. Eine View kann wie folgt konfiguriert oder angesehen werden: Im Analytics-Konto auf Verwalten wechseln, ein Konto auswählen, im Abschnitt Datenansicht kann eine View erstellt, konfiguriert, gelöscht oder angesehen werden. Unter Einstellungen der Berichtdatenansicht kann die ID der View gefunden werden. Ein Diagramm muss immer mit mindestens einer View verknüpft werden.

4.3.2 ViewSelector

Ein ViewSelector ist nichts anderes als ein bestimmte Anzahl von Auswahllisten zur Filterung von Daten, beispielsweise nach Konto und/oder View. Wie bei den anderen Komponenten auch wird hier ein DOM-Knoten benötigt, in dem Google den Inhalt anzeigt.

Danach kann der ViewSelector erzeugt und angezeigt werden.

4.3.3 Verknüpfung von DataChart und ViewSelector

Natürlich ist der reine ViewSelector, wie er jetzt zu sehen ist, unbrauchbar. Die Auswahllisten sind sicht- und änderbar, aber eine Veränderung hat keinen Effekt. Aus diesem Grund bietet Google die Möglichkeit Diagramme (aber auch andere Komponenten) mit einem ViewSelector zu verknüpfen.

Als Beispiel wird jetzt das DataChart aus 4.3.1 mit dem ViewSelector aus 4.3.2 verknüpft. Als ersten Schritt wird der ‘ids’ Schlüssel aus dem Diagramm-Options-Objekt entfernt und verhindert, dass es angezeigt wird. Bliebe die Anzeige bestehen, würde Google einne Fehler zurückgeben, da Google den Schlüsser ‘ids’ zur Anzeige erwartet.

4.3.4 ReportData

ReportDatas sind eine zusätzliche Möglichkeit, Daten von der Google-Schnittstelle zu einer View zu erhalten. Dabei wird jedoch kein Inhalt angezeigt. Stattdessen funktioniert es wie eine einfache Anfrage, die Daten in JSON-Form zurückliefert. Im folgenden ein kleines Beispiel dafür.

4.3.5 Verknüpfung von ReportData und ViewSelector

Die Verknüpfung folgt im Grunde genau dem gleichen Prinzip, wie das Verknüpfen von Diagramm und ViewSelector. Die ‘ids’ werden nicht direkt gesetzt und der Report auch nicht ausgeführt. Erst wenn sich der ViewSelector ändert, werden die Ids gesetzt und dann die Anfragen abgesendet.

5. Implementierung in AngularJS

Die normale Vorgehensweise zur Benutzung der Google Analytics API ist für AngularJS oder generell für den App-Kontext (ob nun Web- oder Mobile App) sehr umständlich und bietet wenig Flexibilität. Es beginnt mit der festen Einbindung des Analytics-Scripts, über die Erzeugung von generischen Diagrammen bis hin zur Verknüpfung dieser mit ViewSelektoren.

5.1 Vorbetrachtung

Bevor programmiert wird, kommen diverse Fragen auf, die vorher geklärt werden müssen.

  • Modularer Einsatz? – Ja!
  • Wie wird es Modular? – Ein eigenes Module mit verschiedenen Directives!
  • Wie können diese miteinander interagieren (siehe 4.3.3, 4.3.5)? – Ein Service!
  • Welche der vorgestellten Funktionen sollen abgebildet werden? – Möglichst alle!

Daraus leitet sich im Grunde der Implementierungsablauf ab.

5.2 Ablauf

  1. Ein Modul
  2. Ein Service zu Autorisierung und Verknüpfung der Komponenten
  3. Direktiven für Reports, ViewSelectors, DataCharts

5.3 Implementierung

5.3.1 Das Modul

Schlicht und einfach eine normale AngularJS Module-Deklaration.

5.3.2 Der Service

Hier stellt sich die Frage, was der Service alles können muss.

  • Client ID speichern -> Getter und Setter
  • Speichern, ob bereits autorisiert
  • Speichern, ob Analytics geladen ist

5.3.3 API Code einbinden

Damit mit der API gearbeitet werden kann, muss diese natürlich erstmal irgendwie eingebunden werden. Ein geeigneter Zeitpunkt wäre direkt nach dem eigentlich späteren App-Start. Dafür bietet sich in Angular der sogenannte run-Block an. Dort muss das Google-Analytics-Skript eingebunden, geladen werden und die entsprechenden Service-Flags gesetzt werden.

5.3.4 Die Direktiven

Die Direktiven sind im Grunde das Kernstück des Moduls. Um den Rahmen nicht zu sprengen, werden im folgenden Kontext die Funktionsweisen dieser nur wörtlich erklärt.

5.3.4.1 Autorisierung

Diese Direktive kümmert sich darum den Autorisierungsbutton oder falls eingeloggt – und gewünscht – einen Hinweis dazu anzuzeigen. Daraus ergeben sich folgende Konfigurationsparameter für die Direktive:

  • authContainer – Zeichenkette mit der ID des zu erstellenden DOM-Knotens
  • label – optionaler Text, falls man eingeloggt ist
  • hideOnAuth – optionaler Parameter (‘true|false’), ob Hinweis über eingeloggten Account angezeigt werden soll

Aus diesen Parametern lässt sich die Autorisierung möglichst flexibel erstellen. Des Weiteren hört die Direktive darauf, ob Google Analytics bereit ist, setzt daraufhin die Autorisierungsoptionen und erstellt den benötigten DOM-Knoten.

5.3.4.2 ViewSelector

Hier sollen einfach ViewSelectors erstellt werden können ohne etwas über die nötigen Strukturen von diesen zu wissen. Auch hier wird wieder ein DOM-Knoten benötigt und der Selector darf erst angezeigt (ausgeführt) werden, wenn die Autorisierung bei Google geklappt hat. Dadurch wird auch eine Verknüpfung zur Autorisierung benötigt.

  • viewSelectorContainer – ID des zu erzeugenden DOM-Knoten für den ViewSelector
  • authContainer – ID des zu verknüpfenden Autorisierungsknotens

Wird ein ViewSelector erzeugt, wird dieser im Service gespeichert, um später andere Komponenten mit diesem zu verbinden.

5.3.4.3 DataChart

Ein Diagramm benötigt wieder die Verknüpfung mit dem Autorisierungsknoten und die Konfigurationsparameter eines Google-Diagramms (DOM-Knoten, Achsen, Daten, …). Zusätzlich kann es mit einem ViewSelector verbunden werden. Daraus ergeben sich wieder folgende Attribute.

  • viewSelectorContainer – ID des ViewSelectors
  • authContainer – ID des Autorisierungsknotens
  • chart – das Konfigurationsobject

Dadurch ist die Direktive in der Lage auf Änderungen des möglicherweise verbundenen ViewSelectors zu reagieren und sich zu aktualisieren. Um so flexibel, wie möglich zu bleiben, hört das Diagramm darauf, wann der ViewSelector erstellt wurde und verbindet sich danach mit ihm.

5.3.4.4 ReportData

Dies geschieht im Grunde wie bei DataCharts. Jedoch benötigen Reports keinen eigenen DOM-Knoten, können aber auch mit ViewSelectors verbunden werden. Ein Report kann aus einem oder mehreren Anfragen an die API bestehen. Aus diesem Grund wird noch eine Liste von Anfrage-Objekten benötigt.

  • viewSelectorContainer – ID des ViewSelectors
  • authContainer – ID des Autorisierungsknotens
  • queries – Liste von Anfrage-Objekten

Da es jetzt kein visuelles Feedback gibt, wird trotzdem ein leerer DOM-Knoten erstellt und mit dem Report verknüpft. Außerdem wirft die Direktive zwei Events:

  • $gaReportSuccess – Report-Anfragen erfolgreich – enthält die Antworten von Google und den verbunden DOM-Knoten
  • $gaReportError – eine Anfrage ist fehlgeschlagen – enthält die Fehler-Antworten von Google und den verbunden DOM-Knoten

Dadurch besteht die Möglichkeit die erhaltenen Daten weiter zu verarbeiten und im DOM anzuzeigen.

5.3.4.5 Template/DOM-Knoten der Direktiven

Für die Erstellung der benötigten DOM-Knoten werden ganz normale Templates benutzt, welche über den Angular $templateCache im run-Block bekannt gemacht werden.

6. Benutzung

Die Benutzung teilt sich in verschiedene Schritte.

    1. Modul laden:
    2. Module in eigene App einbinden:
    3. ClientID setzen:
    4. Direktiven einbinden: zum Beispiel

Ein vollständiges Beispiel dazu findet sich auf der Demo-Seite.

7. Fazit

Die Google-Analytics Embed API ist ein weiterer toller Service von Google. Sie ist schnell einzurichten und die Nutzung für normale Webseiten ist einfach. In die eher modulare und flexible Struktur einer AngularJS-App fügt sie sich eher weniger gut ein. Aus diesem Grund nimmt ngAnalytics dem Programmierer viel Arbeit ab, da er sich voll und ganz auf die Konfiguration für die Anzeige der Komponenten, wie Diagramm oder Report, konzentrieren kann. Verknüpfungen und die Komponenten selbst werden von dem Modul erstellt und verwaltet. Darüber hinaus wird versucht die von AngularJS vorgeschriebene Struktur einer App einzuhalten. Beispielsweise laufen DOM-Manipulationen Dank der Verwendung einzelner Direktiven nur in begrenzten Scopes ab und Daten werden über Events und Services mit anderen Scopes (und Controllers) geteilt.

Wir freuen uns über eine Bewertung, um ein Feedback zu erhalten:

Durchschnittlich 4.4 Sterne aus 7 Meinungen.

2 Kommentare zu “AngularJS – Google Analytics Embed API – ngAnalytics

  1. Your plugin is great thank you for sharing, But my google account have a lot of websites so it show me a select input in which i can choose the website, how can i only choose one of the site and do not show those selects.

    Thanks in advance

    • Hey Maik,

      i think that is not possible at the moment.
      But you can create charts and so on with fixed viewIds –> so there is no need for the ViewSelector.
      Another workaround –> add a user-account to your google-analytics, that only have the rights to see the wanted views and data.

      For questions you can use our github repository (create an issue for feature requests or questions).

      Greets, Bengt

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.