Zaawansowane przypadki użycia

W tym dokumencie opisujemy kilka zaawansowanych funkcji interfejsu Google Analytics Data API w wersji 1. Szczegółowy opis interfejsu API znajdziesz w jego dokumentacji.

Wyświetlanie listy definicji niestandardowych i tworzenie raportów

Interfejs Data API może tworzyć raporty o zarejestrowanych niestandardowych wymiarach i danych niestandardowych. Metoda metadanych API może służyć do wyświetlania nazw interfejsów API zarejestrowanych w usłudze niestandardowej. Te nazwy interfejsów API mogą być np. używane w żądaniach raportów wysyłanych do metody runReport.

W kolejnych sekcjach znajdziesz przykłady poszczególnych typów definicji niestandardowej. W tych przykładach zastąp GA4_PROPERTY_ID swoim identyfikatorem usługi.

Wymiary niestandardowe ograniczone do zdarzenia

Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.

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

Krok 2. Znajdź wymiar niestandardowy ograniczony do zdarzenia, na podstawie którego chcesz tworzyć raporty z odpowiedzi. Jeśli wymiar nie jest dostępny, musisz go zarejestrować.

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

Krok 3. Uwzględnij wymiar niestandardowy w żądaniu raportu. Poniżej znajdziesz przykładowe żądanie metody runReport.

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

Wymiary niestandardowe ograniczone do użytkownika

Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.

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

Krok 2. Znajdź wymiar niestandardowy o zakresie na poziomie użytkownika, na podstawie którego chcesz utworzyć raporty z odpowiedzi. Jeśli wymiar nie jest dostępny, musisz go zarejestrować.

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

Krok 3. Uwzględnij wymiar niestandardowy w żądaniu raportu. Poniżej znajdziesz przykładowe żądanie metody runReport.

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

Dane niestandardowe ograniczone do zdarzenia

Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.

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

Krok 2. Znajdź dane niestandardowe ograniczone do zdarzenia, na podstawie których chcesz tworzyć raporty z odpowiedzi. Jeśli dane są niedostępne, musisz je zarejestrować.

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

Krok 3. Uwzględnij w żądaniu raportu dane niestandardowe. Poniżej znajdziesz przykładowe żądanie metody runReport.

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

Dane współczynnika konwersji dla jednej konwersji

Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.

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

Krok 2. Znajdź dane współczynnika konwersji dla jednej konwersji, dla której chcesz utworzyć raporty na podstawie odpowiedzi. Jeśli nie ma zdarzenia konwersji, musisz je skonfigurować.

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

Krok 3. Uwzględnij w żądaniu raport dane współczynnika konwersji. Poniżej znajdziesz przykładowe żądanie metody runReport.

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

Średnie danych niestandardowych ograniczonych do zdarzenia

Krok 1. Wyślij zapytanie do metody metadanych API, podając identyfikator usługi.

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

Krok 2. Znajdź średnią danych niestandardowych ograniczonych do zdarzenia, na podstawie której chcesz tworzyć raporty z odpowiedzi. Jeśli dane są niedostępne, musisz je zarejestrować.

"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"
    },
...
],

Krok 3. Uwzględnij w żądaniu raportu średnią z danych niestandardowych. Poniżej znajdziesz przykładowe żądanie metody runReport.

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

Przykłady raportów dotyczących kohorty

Raporty dotyczące kohorty tworzą serię czasową utrzymania użytkowników w danej kohorcie. Szczegółową dokumentację poszczególnych pól interfejsu API znajdziesz w dokumentacji REST CohortSpec.

Tworzenie raportu dotyczącego kohorty

Oto przykładowy raport dotyczący kohorty, w którym:

  • Kohorta to użytkownicy z firstSessionDate o wartości 2020-12-01. Jest ona konfigurowana przez obiekt cohorts. Wymiary i dane w odpowiedzi na raport będą oparte tylko na użytkownikach kohorty.
  • Raport dotyczący kohorty będzie zawierał 3 kolumny. Są one konfigurowane za pomocą obiektów wymiarów i danych.
    • Wymiar cohort to nazwa kohorty.
    • Wymiar cohortNthDay to liczba dni od 2020-12-01.
    • Dane cohortActiveUsers to liczba wciąż aktywnych użytkowników.
  • Obiekt cohortsRange określa, że raport powinien zawierać dane zdarzeń dla tej kohorty od 2020-12-01 do 2020-12-06.
    • Jeśli używana jest szczegółowość DAILY, zalecany jest wymiar cohortNthDay, który zapewnia spójność.

Żądanie raportu dla kohorty to:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
    }
  },
}

Przykładowa odpowiedź na to żądanie to:

{
  "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
}

Na podstawie tej odpowiedzi do raportu widoczny jest wykres dotyczący raportu dotyczącego kohorty. Z tego raportu wynika, że największy spadek liczby aktywnych użytkowników w tej kohorcie nastąpił między pierwszym a drugim dniem.

Wizualizacja użytkowników kohorty na przestrzeni czasu

Wiele kohort i ułamek utrzymania użytkowników

Pozyskiwanie i utrzymywanie użytkowników to sposoby na rozwój witryny lub aplikacji. Raporty dotyczące kohorty koncentrują się na utrzymaniu użytkowników. W tym przykładzie raport pokazuje, że w ciągu 2 tygodni ta usługa poprawiła wskaźnik utrzymania użytkowników w ciągu 4 dni o 10%.

Aby utworzyć ten raport, określamy 3 kohorty: pierwsza z firstSessionDate o wartości 2020-11-02, druga z firstSessionDate o wartości 2020-11-09 oraz trzecia z firstSessionDate o wartości 2020-11-16. Liczba użytkowników Twojej usługi w tych 3 dniach będzie inna, dlatego porównujemy dane dotyczące utrzymania użytkowników w kohorcie cohortActiveUsers/cohortTotalUsers, zamiast korzystać z danych Bezpośrednie cohortActiveUsers.

Żądanie raportu dotyczące tych kohort:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
    }
  },
}

Przykładowa odpowiedź na to żądanie to:

{
  "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
}

Na podstawie tej odpowiedzi do raportu widoczny jest wykres dotyczący raportu dotyczącego kohorty. Z tego raportu wynika, że w ciągu 2 tygodni 4-dniowy wskaźnik utrzymania użytkowników wzrósł o 10%. Późniejsza kohorta z firstSessionDate z 2020-11-16 przekracza utrzymanie uwagi odbiorców z wcześniejszej kohorty (firstSessionDate z 2020-11-02).

Wykres przedstawiający wiele utrzymania w kohorcie

Kohorty tygodniowe i korzystanie z kohort z innymi funkcjami interfejsu API

Aby usunąć codzienną wariancję w zachowaniu użytkowników, użyj kohort tygodniowych. W tygodniowych raportach dotyczących kohorty wszyscy użytkownicy z danymi firstSessionDate w tym samym tygodniu tworzą kohortę. Tydzień zaczyna się w niedzielę, a kończy w sobotę. Ponadto w tym raporcie dzielimy tę kohortę, aby porównać użytkowników z aktywnością w Rosji z użytkownikami aktywnymi w Meksyku. W tym wycinku użyto wymiaru country i elementu dimensionFilter, aby uwzględnić tylko 2 kraje.

Żądanie raportu dotyczące tych kohort:

POST https://analyticsdata.googleapis.com/v1beta/properties/GA4_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"
    }
  },
}

Przykładowa odpowiedź na to żądanie to:

{
  "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
}

Na podstawie tej odpowiedzi do raportu widoczny jest wykres raportu dotyczącego kohorty. Z tego raportu wynika, że ta usługa skuteczniej zatrzymuje użytkowników aktywnych w Meksyku niż ci z Rosji.

Wykres przedstawiający porównawcze kohorty krajów