Bereitstellung von nutzergesteuerten Konten – API-Entwicklerhandbuch

In diesem Dokument werden wichtige Konzepte zur Verwendung der Provisioning API zum Erstellen neuer Google Analytics-Konten erläutert.

Einleitung

Mit der Provisioning API können neue Google Analytics-Konten erstellt und Google Analytics in großem Umfang für Kunden aktiviert werden. Sie richtet sich an qualifizierte Dienstanbieter und große Partner. Eine Einführung in die Provisioning API finden Sie unter Provisioning API – Übersicht.

Vorbereitung

Der Zugriff auf alle Google Analytics APIs erfolgt auf ähnliche Weise. Bevor Sie mit der Provisioning API beginnen, sollten Sie Folgendes tun:

  • Auf der Seite Clientbibliotheken finden Sie eine vollständige Liste der programmiersprachenspezifischen Clientbibliotheken, die mit der API funktionieren.
  • Im Referenzhandbuch erhalten Sie Informationen zur API-Oberfläche und zum Zugriff auf Daten ohne Clientbibliothek.

Jede Clientbibliothek stellt ein einzelnes Analysedienstobjekt für den Zugriff auf die Provisioning API bereit. In der Regel müssen Sie die folgenden Schritte ausführen, um das Dienstobjekt zu erstellen:

  1. Registrieren Sie Ihre Anwendung in der Google API Console.
  2. Autorisieren Sie die Berechtigung, ein neues Google Analytics-Konto zu erstellen.
  3. Erstellen Sie ein Analytics-Dienstobjekt.

Falls Sie diese Schritte noch nicht ausgeführt haben, beenden Sie bitte die Anleitung zur Google Analytics API. In dieser Anleitung werden Sie durch die ersten Schritte zum Erstellen einer Google Analytics API-Anwendung geführt. Anschließend wissen Sie, wie Sie mit den Google Analytics APIs praktische Aufgaben ausführen.

Überblick

Beim Erstellen von Google Analytics-Konten mit der Provisioning API sind zwei separate Abläufe zu berücksichtigen:

  • Technischer Ablauf: Der gesamte Ablauf zur programmatischen Bereitstellung eines Google Analytics-Kontos für einen Nutzer.
  • Nutzerfluss: Die Implementierungsüberlegungen, die Sie aus Sicht des Nutzers bei der Kontoerstellung berücksichtigen sollten.

In diesem Dokument werden für jeden Ablauf die allgemeinen Schritte und Anforderungen beschrieben.

Technischer Ablauf

Die übergeordneten Schritte zur Verwendung der Provisioning API zum Erstellen eines neuen Kontos und zur Einbindung in Google Analytics sind:

  1. Fordern Sie den Nutzer auf, die Anwendung/den Dienst mit OAuth 2.0 zu authentifizieren und zu autorisieren.
  2. Erstellen Sie mit der Provisioning API ein Kontoticket.
  3. Leiten Sie den Nutzer weiter, damit er die Nutzungsbedingungen von Google Analytics akzeptiert und die Antwort verarbeitet.
  4. (Optional) Konfigurieren Sie das Konto und Integrationsmöglichkeiten.

Wenn diese Schritte erfolgreich abgeschlossen wurden, wird ein Google Analytics-Konto für den Nutzer erstellt. Ihnen stehen dann die Konto-ID, die Property-ID und die ID der Datenansicht (Profil) für das neue Konto zur Verfügung.

Für jeden der nachfolgenden Schritte gibt es Anforderungen zum Ausführen des Schritts, die Ergebnisse des Schritts und eine Beschreibung des technischen Ablaufs für den Schritt.

1. Authentifizierung und Autorisierung

Jeder Nutzer muss Ihre Anwendung autorisieren und ihr die Berechtigung erteilen, in seinem Namen ein Google Analytics-Konto bereitzustellen. Für diesen Schritt wird der Anwendungsablauf für den OAuth 2.0-Webserver empfohlen.

Voraussetzungen für diesen Schritt

  • Client-ID: Die Client ID des Projekts, das Sie verwenden. Diese Option ist in der Google Developers Console verfügbar. Weitere Informationen findest du im Artikel zum OAuth 2.0-Webserver.
  • Weiterleitungs-URI: An diese URL wird der Nutzer weitergeleitet und die OAuth 2.0-Antwort gesendet.
    • Konfigurieren Sie Redirect URIs und rufen Sie die Client ID für Ihr Projekt über die Google Developers Console ab.
    • Der Wert dieses Parameters muss genau mit einem der in der Google Developers Console registrierten Werte übereinstimmen, einschließlich HTTP- oder HTTPS-Schemata, Groß-/Kleinschreibung und nachgestelltem Schrägstrich (/).
  • Auth-Bereich für Google Analytics Provisioning API

Das Ergebnis dieses Schritts

Sobald der OAuth 2.0-Vorgang abgeschlossen ist, hat der Nutzer Ihre Anwendung autorisiert, in seinem Namen ein Konto bereitzustellen. Außerdem erhalten Sie ein Zugriffstoken für den Nutzer.

Hinweis zu Tokens und Bereichen:

  • Falls Sie beabsichtigen, nach dem Erstellen des Kontos zusätzliche Anfragen für die Kontokonfiguration oder Berichtsdaten des Nutzers zu senden, können Sie in diesem Schritt auch zusätzliche Bereiche autorisieren. z. B. im Bereich readonly oder edit.
  • Zugriffstokens haben eine begrenzte Lebensdauer. Wenn Ihre Anwendung über die Lebensdauer eines einzelnen Zugriffstokens hinaus Zugriff auf die Google Analytics API benötigt, können Sie auch ein Aktualisierungstoken anfordern, indem Sie access_type=offline festlegen. Ein Aktualisierungstoken sollte für jeden Nutzer sicher und langfristig gespeichert werden, da Ihre Anwendung damit neue Zugriffstokens abrufen kann. Weitere Informationen finden Sie unter Offlinezugriff.

Technischer Ablauf für diesen Schritt

Sie benötigen ein Zugriffstoken für den Nutzer. Senden Sie den Nutzer gemäß dem unter OAuth 2.0-Webserver beschriebenen Ablauf an den Google Konten-Dienst und verarbeiten Sie die Antwort, wenn der Nutzer nach Abschluss des Authentifizierungsvorgangs zu Ihrem Dienst zurückgeleitet wird.

OAuth 2.0-URL erstellen, die der Nutzer aufrufen soll

Wenn der Nutzer auf eine Schaltfläche oder einen Link zu „Jetzt starten“ oder „Konto erstellen“ klickt, sollte der Link auf den Beginn des OAuth 2.0-Vorgangs verweisen, in dem der Nutzer um Bereitstellungsberechtigungen gebeten wird. Beispiel:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
Antwort des Google Konten-Dienstes verarbeiten

Sobald der Nutzer entschieden hat, Ihrer Anwendung Zugriff zu gewähren, wird er zu redirect_uri weitergeleitet, wie in der von Ihnen erstellten URL mit einem Abfrageparameter angegeben, der einen Autorisierungscode enthält. Wenn der Nutzer die Anfrage genehmigt hat, kann die Antwort mit dem Autorisierungscode verwendet werden, um den Autorisierungscode gegen ein Zugriffstoken auszutauschen. Dazu stellen Sie eine POST-Anfrage an die Google Accounts API.

Aktualisierungstoken speichern (falls zutreffend)

Das Zugriffstoken wird im nächsten Schritt verwendet, damit Sie es vorübergehend speichern können. Wenn Sie auch ein Aktualisierungstoken für den Nutzer angefordert haben, sollten Sie dieses für eine langfristige Nutzung an einem sicheren Ort speichern. Ein Aktualisierungstoken ist langlebig und kann zum Ausstellen neuer Zugriffstokens verwendet werden.

2. Kontoticket mit der Provisioning API erstellen

Sobald du ein Zugriffstoken für den autorisierten Nutzer hast, kannst du damit eine Anfrage an die Provisioning API senden, um ein Kontoticket für den Nutzer zu erstellen. Das Kontoticket ist der erste Schritt beim Erstellen eines Kontos für einen Nutzer.

Voraussetzungen für diesen Schritt

Ein Zugriffstoken für den autorisierten Nutzer, wie unter Authentifizierung und Autorisierung beschrieben, und die folgenden Details zur Bereitstellung:

  • Weiterleitungs-URI
    • Gibt an, wohin der Nutzer nach den Nutzungsbedingungen von Google Analytics weitergeleitet wird. Er kann sich von dem Weiterleitungs-URI unterscheiden, der während des OAuth 2.0-Autorisierungsablaufs angegeben wurde.
    • Der Wert des Weiterleitungs-URI-Parameters muss genau mit einem der in der Google Developers Console registrierten Werte übereinstimmen, einschließlich HTTP- oder HTTPS-Schemas, Groß-/Kleinschreibung und nachgestelltem Schrägstrich (/).
  • Kontofelder
    • Für das Konto ist die Property name erforderlich.
  • Web-Property-Felder
    • Für die Property ist die Property name erforderlich.
    • websiteUrl ist erforderlich.
  • Profilfelder
    • Für das Profil ist die Property name erforderlich.
    • Optional kann ein timezone angegeben werden. Der Standardwert ist America/Los_Angeles.

Beim Erstellen eines Kontotickets können nur die oben genannten grundlegenden Felder festgelegt werden. Nachdem das Konto erstellt wurde, können über die Management API zusätzliche Konfigurationsänderungen an der Property oder der Datenansicht (Profil) vorgenommen werden.

Weitere Informationen zu diesen Feldern finden Sie in der API-Referenz für Konten, Properties und Datenansichten (Profile).

Das Ergebnis dieses Schritts

Nachdem eine erfolgreiche Anfrage an die Provisioning API gesendet wurde, erhalten Sie ein kurzlebiges Konto-Ticket für den Nutzer. Die Konto-Ticket-ID wird im letzten Schritt verwendet, um den Nutzer aufzufordern, die Nutzungsbedingungen zu akzeptieren und sein Konto zu aktivieren. Das Konto kann erst verwendet werden, wenn die Nutzungsbedingungen akzeptiert wurden.

Technischer Ablauf für diesen Schritt

Mit dem Zugriffstoken für den Nutzer, das während der Authentifizierung und Autorisierung abgerufen wurde, wird eine HTTP POST-Anfrage an die Provisioning API gesendet.

Provisioning API-Anfrage zum Erstellen des Kontotickets

Weitere Informationen zum Stellen der Anfrage finden Sie in der Referenz zur Provisioning API unter der Methode createAccountTicket.

Antwort von der Provisioning API

Bei einer erfolgreichen Anfrage wird der Antwortcode 200 zurückgegeben. Der Antworttext enthält ein Account Ticket, das kurzlebig ist. Das Konto-Ticket besteht aus einer ID und Details zur neuen Kontostruktur.

Weitere Informationen zur Antwort finden Sie in der Referenz zur Provisioning API unter Account Ticket resource.

Fehlerantworten müssen ebenfalls von der Anwendung verarbeitet werden.

3. Der Nutzer akzeptiert die Nutzungsbedingungen für Google Analytics.

Wenn Sie eine Kontoticket-ID für den Nutzer haben, können Sie sie zusammen mit der Anfrage für die Nutzungsbedingungen verwenden, um den Nutzer aufzufordern, die Google Analytics-Nutzungsbedingungen zu akzeptieren.

Voraussetzungen für diesen Schritt

Eine Konto-Ticket-ID für den autorisierten Nutzer.

Das Ergebnis dieses Schritts

Nachdem Sie den Nutzungsbedingungen mithilfe der Konto-Ticket-ID erfolgreich abgeschlossen haben, werden das Konto, die Property und die Datenansicht (Profil) erstellt. Der Nutzer hat jetzt ein aktives Konto. Die Antwort auf der Seite mit den Nutzungsbedingungen enthält die Konto-ID, die Property-ID und die ID der Datenansicht (Profil).

Technischer Ablauf für diesen Schritt

Leite den Nutzer mithilfe der Konto-Ticket-ID zur Seite mit den Google Analytics-Nutzungsbedingungen weiter, auf der er die Nutzungsbedingungen akzeptieren kann. Anschließend musst du die Antwort der API verarbeiten.

Die URL für die Nutzungsbedingungen erstellen, die der Nutzer besuchen soll

Leite den Nutzer auf die Seite mit den Nutzungsbedingungen weiter und füge die Konto-Ticket-ID als Teil der URL hinzu:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
Umgang mit der Antwort auf die Nutzungsbedingungen

Nachdem der Nutzer eine Aktion auf der Seite mit den Nutzungsbedingungen ausgeführt hat, wird er zurück zur redirectUri weitergeleitet, die beim Erstellen des Kontotickets angegeben wurde. Die Antwort von der Seite mit den Nutzungsbedingungen ist Teil des Abfragestrings.

Bei erfolgreichen Antworten werden Daten zur neu erstellten Kontostruktur sowie zur ursprünglichen accountTicketId zurückgegeben:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

Wenn sich der Nutzungsbedingungen-Handler für Ihre Anwendung beispielsweise unter http://www.your-app.com/gaTOS befindet, sollte er beim Erstellen von Kontotickets auf redirectUri festgelegt werden. Der Nutzungsbedingungen-Handler Ihrer Anwendung sollte HTTP GET-Anfragen, die accountId-, webPropertyId-, profileId- und accountTicketId-Abfrageparameter enthalten, für Fälle erwarten und ordnungsgemäß verarbeiten, in denen das Kontoticket gültig ist und der Nutzer die Nutzungsbedingungen akzeptiert hat.

Fehlgeschlagene Antworten enthalten die Fehlerantwort:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

Der TOS-Handler sollte auch HTTP GET-Anfragen mit einem error-Abfrageparameter richtig verarbeiten, was auf einen Fehler hinweist. Mit dem Wert des Abfrageparameters können weitere Aktionen ausgeführt oder eine Nachricht für den Nutzer angezeigt werden:

  • error=user_cancel: Der Nutzer hat die Nutzungsbedingungen nicht akzeptiert.
  • error=max_accounts_reached: Der Nutzer hat das Google Analytics-Kontolimit erreicht.
  • error=backend_error: Ein allgemeiner Fehler. Der Server hat einen Fehler zurückgegeben, der nicht in den oben genannten Kategorien enthalten ist.

4. Integrationsmöglichkeiten (optional)

Wenn Sie den obigen technischen Ablauf ausgeführt haben, haben Sie ein Konto für den Nutzer mit der Konto-ID, der Property-ID und der ID der Datenansicht (Profil) erstellt. Wenn Sie außerdem zusätzliche Berechtigungen angefordert haben, können Sie auch ein Aktualisierungstoken für den Nutzer haben. Mit diesen Daten können Sie:

  • Binden Sie gegebenenfalls automatisch das standardmäßige Google Analytics-Tracking-Snippet mit der Property-ID des neu erstellten Kontos für jede Seite der Website des Nutzers ein.
  • Sie können die Property des Nutzers mithilfe der Management API automatisch konfigurieren.
  • Stellen Sie mit der Embed API oder der Core Reporting API Berichte für Nutzer in Ihrem Produkt zur Verfügung (z.B. im Admin-Steuerfeld).

Aufrufabfolge von Webseiten

In diesem Abschnitt werden die Implementierungsaspekte im Zusammenhang mit den Schritten der Kontoerstellung aus Sicht des Nutzers beschrieben.

Der Ablauf beginnt damit, dass der Nutzer die folgenden zwei Optionen anbietet, um Analysen für seine Property zu aktivieren:

  1. Google Analytics-Konto erstellen
  2. Ein vorhandenes Google Analytics-Konto verwenden. Hinweis: Dieser Ablauf wird in diesem Dokument nicht behandelt. Weitere Informationen zum Zugriff auf die Google Analytics-Konfigurationsdaten eines Nutzers finden Sie in der Management API.

Wenn Sie ein neues Google Analytics-Konto erstellen, gibt es Informationen, die Sie mit der Bereitstellungsanfrage senden müssen, z. B. Kontoname, Property-Name usw. Je nach den Informationen, die Sie über den Nutzer haben, und der gewünschten Vorgehensweise, gibt es drei Hauptoptionen, um den Nutzerfluss zu starten, nachdem der Nutzer auf „Konto erstellen“ geklickt hat:

Nach der Autorisierung nach Kontodetails fragen

In diesem Fall wird der Nutzer mitten im Vorgang nach seinen Kontodetails gefragt. Der Ablauf sieht in etwa so aus:

  1. Der Nutzer wird zum Google-Kontodienst für den OAuth 2.0-Vorgang weitergeleitet. Wenn der Nutzer kein Google-Konto hat oder nicht angemeldet ist, wird er aufgefordert, ein Google-Konto zu erstellen oder sich anzumelden.
  2. Der Nutzer wird aufgefordert, die Anwendung zum Erstellen von Google Analytics-Konten zu autorisieren.
  3. Der Nutzer akzeptiert Berechtigungsanfragen für die Anwendung.
  4. Der Nutzer wird zum Dienstanbieter weitergeleitet. Wenn der Nutzer die Autorisierung ablehnt, wird er dennoch zum Dienstanbieter zurückgeleitet.
  5. Dem Nutzer wird ein Formular angezeigt, um Details zum Konto zu erfassen, das erstellt werden soll (z. B. Kontoname, Property-Name, Profilname, Zeitzone, Website-URL usw.).
  6. Der Nutzer füllt und sendet das Formular und wird zu Google weitergeleitet bzw. sieht die Nutzungsbedingungen für Google Analytics.
  7. Der Nutzer akzeptiert die Nutzungsbedingungen.
  8. Der Nutzer wird zum Dienstanbieter weitergeleitet und erhält eine Erfolgsmeldung, dass er erfolgreich ein Google Analytics-Konto mit Details zum Konto und den Zugriffsrechten erstellt hat. Wenn der Nutzer die Nutzungsbedingungen nicht akzeptiert, wird er dennoch zurück zum Dienstanbieter weitergeleitet.

Vor der Autorisierung nach Kontodetails fragen

In diesem Fall wird der Nutzer vorab um Konfigurationsdetails des zu erstellenden Kontos gebeten. Der Ablauf sieht in etwa so aus:

  1. Auf der Website des Dienstanbieters wird dem Nutzer ein Formular angezeigt, über das er Details zum zu erstellenden Konto erfassen kann (z.B. Kontoname, Property-Name, Profilname, Zeitzone, Website-URL).
  2. Der Nutzer füllt das Formular aus, klickt auf „Senden“ und wird zum Google Account Service for OAuth 2.0-Vorgang weitergeleitet. Wenn der Nutzer kein Google-Konto hat oder nicht angemeldet ist, wird er aufgefordert, ein Google-Konto zu erstellen oder sich anzumelden.
  3. Der Nutzer wird aufgefordert, die Anwendung zum Erstellen von Google Analytics-Konten zu autorisieren.
  4. Der Nutzer akzeptiert die angeforderten Berechtigungen für die Anwendung.
  5. Der Nutzer wird zum Dienstanbieter weitergeleitet.
  6. Der Nutzer wird zu Google weitergeleitet bzw. es werden die Google Analytics-Nutzungsbedingungen angezeigt.
  7. Der Nutzer akzeptiert die Nutzungsbedingungen.
  8. Der Nutzer wird zum Dienstanbieter weitergeleitet und erhält eine Erfolgsmeldung, dass er erfolgreich ein Google Analytics-Konto mit Details zum Konto und den Zugriffsrechten erstellt hat.

Kontodetails vorausfüllen oder Formulare überspringen

Wenn bereits Informationen zum Nutzerkonto verfügbar sind (z.B. Website-URL, Websitename, Zeitzone usw.), können die beiden obigen Optionen durch Folgendes weiter vereinfacht werden:

  • Das Formular muss im Voraus ausgefüllt werden und der Nutzer kann es bearbeiten, wenn er möchte.
  • Den Formularschritt wird übersprungen und das Konto wird anhand der vorhandenen Informationen automatisch erstellt.