Komplexere Anwendungsfälle

In diesem Dokument werden einige erweiterte Funktionen der Google Analytics Data API v1 beschrieben. Eine detaillierte Referenz der API finden Sie in der API-Referenz.

Benutzerdefinierte Definitionen auflisten und Berichte erstellen

Mit der Data API können Berichte zu registrierten benutzerdefinierten Dimensionen und benutzerdefinierten Messwerten erstellt werden. Mit der Metadata API-Methode können Sie die API-Namen der registrierten benutzerdefinierten Definitionen Ihrer Property auflisten. Diese API-Namen können beispielsweise in Berichtsabfragen für die Methode runReport verwendet werden.

In den folgenden Abschnitten finden Sie Beispiele für die einzelnen Typen von benutzerdefinierten Definitionen. Ersetzen Sie in diesen Beispielen GA_PROPERTY_ID durch Ihre Property-ID.

Benutzerdefinierte Dimensionen auf Ereignisebene

Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie in der Antwort nach der benutzerdefinierten Dimension auf Ereignisebene, für die Sie Berichte erstellen möchten. Wenn die Dimension nicht vorhanden ist, müssen Sie sie registrieren.

"dimensions": [
...
    {
      "apiName": "customEvent:achievement_id",
      "uiName": "Achievement ID",
      "description": "An event scoped custom dimension for your Analytics property."
    },
...
],

Schritt 3:Benutzerdefinierte Dimension in eine Berichtsanfrage einfügen Im Folgenden sehen Sie ein Beispiel für eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-09-01", "endDate": "2020-09-15" }],
  "dimensions": [{ "name": "customEvent:achievement_id" }],
  "metrics": [{ "name": "eventCount" }]
}

Benutzerdefinierte Dimensionen auf Nutzerebene

Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie in der Antwort nach der benutzerdefinierten Dimension auf Nutzerebene, für die Sie Berichte erstellen möchten. Wenn die Dimension nicht vorhanden ist, müssen Sie sie registrieren.

"dimensions": [
...
    {
      "apiName": "customUser:last_level",
      "uiName": "Last level",
      "description": "A user property for your Analytics property."
    },
...
],

Schritt 3:Benutzerdefinierte Dimension in eine Berichtsanfrage einfügen Im Folgenden sehen Sie ein Beispiel für eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "entity": { "propertyId": "GA_PROPERTY_ID" },
  "dateRanges": [{ "startDate": "7daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "customUser:last_level" }],
  "metrics": [{ "name": "activeUsers" }]
}

Benutzerdefinierte Messwerte auf Ereignisebene

Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie in der Antwort nach dem benutzerdefinierten Messwert auf Ereignisebene, für den Sie Berichte erstellen möchten. Wenn der Messwert nicht vorhanden ist, müssen Sie ihn registrieren.

"metrics": [
...
    {
      "apiName": "customEvent:credits_spent",
      "uiName": "Credits Spent",
      "description": "An event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Schritt 3:Benutzerdefinierten Messwert in eine Berichtsanfrage einfügen Im Folgenden sehen Sie ein Beispiel für eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "customEvent:credits_spent" }]
}

Messwerte für die Schlüsselereignisrate für ein Schlüsselereignis

Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie in der Antwort nach dem Messwert „Schlüsselereignisrate“ für ein Schlüsselereignis, für das Sie Berichte erstellen möchten. Wenn das Schlüsselereignis nicht vorhanden ist, müssen Sie es einrichten.

"metrics": [
...
    {
      "apiName": "sessionKeyEventRate:add_to_cart",
      "uiName": "Session key event rate for add_to_cart",
      "description": "The percentage of sessions in which a specific key event was triggered",
    },
...
],

Schritt 3:Messwert für die Schlüsselereignisrate in eine Berichtsanfrage einfügen Im Folgenden sehen Sie ein Beispiel für eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "30daysAgo", "endDate": "yesterday" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "sessionKeyEventRate:add_to_cart" }]
}

Durchschnittswerte für benutzerdefinierte Messwerte auf Ereignisebene

Schritt 1:Fragen Sie die Metadata API-Methode mit Ihrer Property-ID ab.

GET https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID/metadata

Schritt 2:Suchen Sie in der Antwort nach dem durchschnittlichen benutzerdefinierten Messwert auf Ereignisebene, für den Sie Berichte erstellen möchten. Wenn der Messwert nicht vorhanden ist, müssen Sie ihn registrieren.

"metrics": [
...
    {
      "apiName": "averageCustomEvent:credits_spent",
      "uiName": "Average Credits Spent",
      "description": "The average of an event scoped custom metric for your Analytics property.",
      "type": "TYPE_STANDARD"
    },
...
],

Schritt 3:Durchschnitt des benutzerdefinierten Messwerts in eine Berichtsanfrage einfügen Im Folgenden sehen Sie ein Beispiel für eine Anfrage an die Methode runReport.

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dateRanges": [{ "startDate": "2020-11-01", "endDate": "2020-11-10" }],
  "dimensions": [{ "name": "eventName" }],
  "metrics": [{ "name": "averageCustomEvent:credits_spent" }]
}

Beispiele für Kohortenberichte

Im Kohortenbericht wird eine Zeitreihe der Nutzerbindung für die Kohorte erstellt. Eine detaillierte Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz für CohortSpec.

Kohortenbericht erstellen

Hier sehen Sie ein Beispiel für einen Kohortenbericht:

  • Die Kohorte besteht aus Nutzern mit einem firstSessionDate von 2020-12-01. Sie wird durch das cohorts-Objekt konfiguriert. Die Dimensionen und Messwerte in der Antwort des Berichts basieren nur auf den Nutzern der Kohorte.
  • Der Kohortenbericht enthält drei Spalten, die durch die Dimensions- und Messwertobjekte konfiguriert werden.
    • Die Dimension cohort ist der Name der Kohorte.
    • Die Dimension cohortNthDay ist die Anzahl der Tage seit dem 2020-12-01.
    • Der Messwert cohortActiveUsers gibt die Anzahl der Nutzer an, die noch aktiv sind.
  • Das cohortsRange-Objekt gibt an, dass der Bericht Ereignisdaten für diese Kohorte ab 2020-12-01 bis 2020-12-06 enthalten soll.
    • Wenn die Granularität DAILY verwendet wird, empfiehlt sich die Dimension cohortNthDay, um die Konsistenz zu wahren.

Die Berichtsabfrage für die Kohorte lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" }, { "name": "cohortNthDay" }],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-12-01", "endDate": "2020-12-01" }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "DAILY"
    }
  },
}

Für diese Anfrage ist eine Beispielantwort für einen Bericht:

{
  "dimensionHeaders": [
    { "name": "cohort" }, { "name": "cohortNthDay" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "293" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "143" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "123" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "92" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0005" }],
      "metricValues": [{ "value": "86" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "83" }]
    }
  ],
  "metadata": {},
  "rowCount": 6
}

Auf diese Antwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Anzahl der aktiven Nutzer in dieser Kohorte zwischen dem ersten und dem zweiten Tag am stärksten abnimmt.

Visualisierung von Kohortennutzern im Zeitverlauf

Mehrere Kohorten und Nutzerbindungsanteil

Nutzergewinnung und ‑bindung sind Möglichkeiten, Ihre Website oder App zu optimieren. Kohortenberichte konzentrieren sich auf die Nutzerbindung. In diesem Beispiel sehen Sie, dass die Nutzerbindung nach 4 Tagen für diese Property im Laufe von zwei Wochen um 10% gestiegen ist.

Für diesen Bericht werden drei Kohorten festgelegt: die erste mit einem firstSessionDate von 2020-11-02, die zweite mit einem firstSessionDate von 2020-11-09 und die dritte mit einem firstSessionDate von 2020-11-16. Da die Anzahl der Nutzer in Ihrer Property an diesen drei Tagen unterschiedlich ist, vergleichen wir den Messwert „Anteil der Nutzerbindung“ der Kohorte von cohortActiveUsers/cohortTotalUsers anstelle des direkten Messwerts cohortActiveUsers.

Die Berichtsanfrage für diese Kohorten lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metrics": [
    {
      "name": "cohortRetentionFraction",
      "expression": "cohortActiveUsers/cohortTotalUsers"
    }
  ],
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-02", "endDate": "2020-11-02" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-09", "endDate": "2020-11-09" }
      },
      {
        "dimension": "firstSessionDate",
        "dateRange": { "startDate": "2020-11-16", "endDate": "2020-11-16" }
      }
    ],
    "cohortsRange": {
      "endOffset": 4,
      "granularity": "DAILY"
    }
  },
}

Für diese Anfrage ist eine Beispielantwort für einen Bericht:

{
  "dimensionHeaders": [{ "name": "cohort" },{ "name": "cohortNthDay" }],
  "metricHeaders": [{
      "name": "cohortRetentionFraction",
      "type": "TYPE_FLOAT"
    }
  ],
  "rows": [
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0000" }],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.308" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.272" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.257" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0001" }],
      "metricValues": [{ "value": "0.248" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.235" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_2" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.211" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.198" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0002" }],
      "metricValues": [{ "value": "0.172" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.167" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_1" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.155" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0003" }],
      "metricValues": [{ "value": "0.141" }]
    },
    {
      "dimensionValues": [{ "value": "cohort_0" },{ "value": "0004" }],
      "metricValues": [{ "value": "0.118" }]
    }
  ],
  "metadata": {},
  "rowCount": 15
}

Auf diese Antwort folgt ein Diagramm für diesen Kohortenbericht. Eine Erkenntnis aus diesem Bericht ist, dass die Nutzerbindung über 4 Tage innerhalb von zwei Wochen um 10% gestiegen ist. Die spätere Kohorte mit firstSessionDate von 2020-11-16 übertrifft die Kundenbindung der früheren Kohorte mit firstSessionDate von 2020-11-02.

Diagramm mit mehreren Kohortenbindungsraten

Wöchentliche Kohorten und Verwendung von Kohorten mit anderen API-Funktionen

Um die täglichen Schwankungen im Nutzerverhalten zu entfernen, verwenden Sie wöchentliche Kohorten. In wöchentlichen Kohortenberichten bilden alle Nutzer mit firstSessionDate in derselben Woche die Kohorte. Wochen beginnen am Sonntag und enden am Samstag. Auch in diesem Bericht wird die Kohorte aufgeschlüsselt, um Nutzer mit Aktivitäten in Russland mit Nutzern mit Aktivitäten in Mexiko zu vergleichen. Für diese Aufschlüsselung wird die Dimension country und ein dimensionFilter verwendet, um nur die beiden Länder zu berücksichtigen.

Die Berichtsanfrage für diese Kohorten lautet:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
{
  "dimensions": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metrics": [{ "name": "cohortActiveUsers" }],
  "dimensionFilter": {
    "filter": {
      "fieldName": "country",
      "inListFilter": {
        "values": [ "Russia", "Mexico" ]
      }
    }
  },
  "cohortSpec": {
    "cohorts": [
      {
        "dimension": "firstSessionDate",
        "dateRange": {
          "startDate": "2020-10-04",
          "endDate": "2020-10-10"
        }
      }
    ],
    "cohortsRange": {
      "endOffset": 5,
      "granularity": "WEEKLY"
    }
  },
}

Für diese Anfrage ist eine Beispielantwort für einen Bericht:

{
  "dimensionHeaders": [
    { "name": "cohort" },
    { "name": "cohortNthWeek" },
    { "name": "country" }
  ],
  "metricHeaders": [
    { "name": "cohortActiveUsers", "type": "TYPE_INTEGER" }
  ],
  "rows": [
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "105" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0000" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "98" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "35" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "24" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0001" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "23" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "17" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0005" },{ "value": "Mexico" }
      ],
      "metricValues": [{ "value": "15" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0002" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "3" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0003" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    },
    {
      "dimensionValues": [
        { "value": "cohort_0" },{ "value": "0004" },{ "value": "Russia" }
      ],
      "metricValues": [{ "value": "1" }]
    }
  ],
  "metadata": {},
  "rowCount": 11
}

Nach dieser Antwort auf den Bericht folgt ein Diagramm dieses Kohortenberichts. Anhand dieses Berichts lässt sich erkennen, dass Nutzer mit Aktivitäten in Mexiko besser gebunden werden als Nutzer mit Aktivitäten in Russland.

Diagramm der Kohorten für den Ländervergleich

Vergleiche

Durch Vergleiche lassen sich Teilmengen von Daten gegenüberstellen. Sie können Vergleiche definieren, indem Sie das Feld comparisons in einer Berichtsdefinition angeben. Die Vergleichsfunktion der Data API ähnelt Vergleichen im Google Analytics-Frontend.

Eine detaillierte Dokumentation der einzelnen API-Felder finden Sie in der REST-Referenz für „Vergleich“.

Vergleich erstellen

Sie können für jeden Datensatz, den Sie vergleichen möchten, einen eigenen Vergleich erstellen. Um beispielsweise App- und Webdaten zu vergleichen, können Sie einen Vergleich für Android- und iOS-Daten und einen weiteren für Webdaten erstellen.

Hier sehen Sie ein Beispiel für einen Bericht, in dem zwei Vergleiche definiert und aktive Nutzer nach Land aufgeschlüsselt zurückgegeben werden.

Im ersten Vergleich mit dem Namen „App-Traffic“ wird inListFilter verwendet, um die Dimension platform mit den Werten „iOS“ und „Android“ abzugleichen. Im zweiten Vergleich mit dem Namen „Web-Traffic“ wird stringFilter verwendet, um die Dimension platform mit „Web“ abzugleichen.

  POST https://analyticsdata.googleapis.com/v1beta/properties/GA_PROPERTY_ID:runReport
  {
    "comparisons": [
      {
        "name": "App traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "inListFilter": {
              "values": [
                "iOS",
                "Android"
              ]
            }
          }
        }
      },
      {
        "name": "Web traffic",
        "dimensionFilter": {
          "filter": {
            "fieldName": "platform",
            "stringFilter": {
              "matchType": "EXACT",
              "value": "web"
            }
          }
        }
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ],
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ]
  }

Bei allen Anfragen, in denen die Vergleichsfunktion verwendet wird, wird dem generierten Bericht automatisch das Feld comparison hinzugefügt. Dieses Feld enthält den Namen des in der Anfrage angegebenen Vergleichs.

Hier ist ein Beispiel für ein Snippet aus einer Antwort, die Vergleiche enthält:

{
  "dimensionHeaders": [
    {
      "name": "comparison"
    },
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "638572"
        }
      ]
    },
    {
      "dimensionValues": [
        {
          "value": "Web traffic"
        },
        {
          "value": "Japan"
        }
      ],
      "metricValues": [
        {
          "value": "376578"
        }
      ]
    },
  {
      "dimensionValues": [
        {
          "value": "App traffic"
        },
        {
          "value": "United States"
        }
      ],
      "metricValues": [
        {
          "value": "79527"
        }
      ]
    },

    ...

  ],

...

}