Zaawansowane przypadki użycia

Ten dokument opisuje kilka zaawansowanych funkcji interfejsu Google Analytics Data API w wersji 1. Szczegółowe informacje o tym interfejsie API znajdziesz w dokumentacji interfejsu API.

Wyświetlać definicje niestandardowe i tworzyć raporty

Interfejs Data API może tworzyć raporty na podstawie zarejestrowanych wymiarów niestandardowych i rodzajów danych niestandardowych. Za pomocą metody interfejsu API metadanych możesz wyświetlić nazwy interfejsów API zarejestrowanych definicji niestandardowych Twojej usługi. Nazwa interfejsu API może być używana w żądaniach raportów, np. w metodzie runReport.

W poniższych sekcjach znajdziesz przykłady każdego typu definicji niestandardowej. W tych przykładach zastąp GA_PROPERTY_ID swoim identyfikatorem usługi.

Wymiary niestandardowe ograniczone do zdarzenia

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

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

Krok 2. W odpowiedzi odszukaj wymiar niestandardowy ograniczony do zdarzenia, na podstawie którego chcesz tworzyć raporty. Jeśli wymiar jest niedostępny, musisz go zarejestrować.

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

Krok 3. Dołącz wymiar niestandardowy do żądania raportu. Oto przykładowe żądanie do metody 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" }]
}

Wymiary niestandardowe ograniczone do użytkownika

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

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

Krok 2. Znajdź w odpowiedzi wymiar niestandardowy ograniczony do użytkownika, na podstawie którego chcesz tworzyć raporty. Jeśli wymiar jest niedostępny, musisz go zarejestrować.

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

Krok 3. Dołącz wymiar niestandardowy do żądania raportu. Oto przykładowe żądanie do metody 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" }]
}

Dane niestandardowe ograniczone do zdarzenia

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

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

Krok 2. Znajdź w odpowiedzi dane niestandardowe ograniczone do zdarzenia, na podstawie których chcesz tworzyć raporty. Jeśli danych nie ma, musisz zarejestrować je.

"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 dane niestandardowe w żądaniu raportu. Oto przykładowe żądanie do metody 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" }]
}

Dane o współczynnikach kluczowych zdarzeń dotyczące jednego kluczowego zdarzenia

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

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

Krok 2. Znajdź w odpowiedzi dane o współczynniku kluczowego zdarzenia, które chcesz uwzględnić w raportach. Jeśli kluczowe zdarzenie jest nieobecne, musisz je skonfigurować.

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

Krok 3. Uwzględnij dane o współczynnikach kluczowych zdarzeń w żądaniu raportu. Oto przykładowa prośba do metody 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" }]
}

Średnie danych niestandardowych ograniczone do zdarzenia

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

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

Krok 2. Znajdź w odpowiedzi średnią danych niestandardowych ograniczonych do zdarzenia, na podstawie których chcesz tworzyć raporty. Jeśli danych nie ma, musisz zarejestrować je.

"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 średnią danych niestandardowych w żądaniu raportu. Oto przykładowe żądanie do metody 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" }]
}

Przykłady raportów dotyczących kohort

Raporty kohortowe tworzą serię danych czasowych dotyczących retencji użytkowników w kohortach. Szczegółową dokumentację każdego pola interfejsu API znajdziesz w dokumentacji interfejsu REST CohortSpec.

Tworzenie raportu dotyczącego kohort

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

  • Kohorta to użytkownicy z wartością firstSessionDate 2020-12-01; jest to konfigurowane przez obiekt cohorts. Wymiary i dane w odpowiedzi na to zapytanie będą uwzględniać tylko użytkowników w kohortach.
  • Raport o grupach zawiera 3 kolumny, które są konfigurowane przez obiekty wymiarów i danych.
    • Wymiar cohort to nazwa kohorty.
    • Wymiar cohortNthDay to liczba dni od 2020-12-01.
    • Dane cohortActiveUsers to liczba użytkowników, którzy są nadal aktywni.
  • Obiekt cohortsRange określa, że raport powinien zawierać dane o zdarzeniach w przypadku tej kohorty, które zaczynają się 2020-12-01, a kończą 2020-12-06.
    • Gdy używasz szczegółowości DAILY, zalecamy użycie wymiaru cohortNthDay ze względu na spójność.

Prośba o raport dotyczący kohorty:

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

W przypadku tego żądania przykładowa odpowiedź w raporcie:

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

W odpowiedzi na to zgłoszenie przedstawiamy wykres z tego raportu dotyczącego kohort. Z tego raportu wynika, że największy spadek liczby aktywnych użytkowników w przypadku tej kohorty nastąpił między pierwszym a 2. dniem.

Wizualizacja kohort użytkowników na przestrzeni czasu

Wiele grup i ułamek użytkowników

Pozyskiwanie i utrzymanie użytkowników to sposoby na zwiększenie skuteczności witryny lub aplikacji. Raporty kohortowe koncentrują się na utrzymaniu użytkowników. W tym przykładzie raport pokazuje, że w ciągu 2 tygodni ta usługa zwiększyła utrzymanie użytkowników na 4. poziomie o 10%.

Aby utworzyć ten raport, określamy 3 grupy: pierwsza z wartością firstSessionDate 2020-11-02, druga z wartością firstSessionDate 2020-11-09, a trzecia z wartością firstSessionDate 2020-11-16. Ponieważ liczba użytkowników Twojej usługi będzie się różnić w tych 3 dniach, porównujemy ułamek odsetka użytkowników z grupy, który wynosi cohortActiveUsers/cohortTotalUsers, zamiast używać bezpośrednich danych cohortActiveUsers.

Prośba o raport dotyczący tych grup odbiorców:

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

W przypadku tego żądania przykładowa odpowiedź w raporcie:

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

W odpowiedzi na to zgłoszenie przedstawiamy wykres z tego raportu dotyczącego kohort. Z tego raportu wynika, że w ciągu 2 tygodni odsetek użytkowników, którzy powracają po 4 dniach, wzrósł o 10%. Późniejsza kohorta z firstSessionDate z 2020-11-16 przewyższa utrzymanie w poprzedniej kohorcie z firstSessionDate z 2020-11-02.

Wykres przedstawiający utrzymanie uwagi przez użytkowników z kilku kohorty

Kohorty tygodniowe i używanie kohort z innymi funkcjami interfejsu API

Aby wyeliminować z analizy codzienne wahania zachowań użytkowników, używaj kohort tygodniowych. W tygodniowych raportach dotyczących kohort wszyscy użytkownicy z wartością firstSessionDate w tym samym tygodniu tworzą kohortę. Tygodnie rozpoczynają się w niedzielę, a kończą w sobotę. W tym raporcie dzielimy kohorty, aby porównać użytkowników aktywnych w Rosji z użytkownikami aktywnymi w Meksyk. Ten wycinek danych korzysta z wymiaru country i kryterium dimensionFilter, aby uwzględnić tylko te 2 kraje.

Prośba o raport dotyczący tych grup odbiorców:

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

W przypadku tego żądania przykładowa odpowiedź w raporcie:

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

W odpowiedzi na zgłoszenie przedstawiamy wykres z tego raportu. Z tego raportu wynika, że ta usługa lepiej utrzymuje użytkowników aktywnych w Meksyk niż w Rosji.

Wykres kohorty porównania krajów

Porównania

Dzięki porównaniom możesz analizować równolegle podzbiory danych. Porównania możesz definiować, podając w definicji raportu pole comparisons. Funkcja Porównania w interfejsie API danych jest podobna do porównania w interfejsie Google Analytics.

Szczegółową dokumentację każdego pola interfejsu API znajdziesz w dokumentacji interfejsu REST Comparison.

Tworzenie porównania

Możesz utworzyć osobne porównanie w przypadku każdego zbioru danych, który chcesz porównać. Jeśli chcesz np. porównać dane z witryny i aplikacji, możesz utworzyć jedno porównanie dotyczące danych z Androida i iOS oraz drugie porównanie obejmujące dane z sieci.

Oto przykładowy raport, który definiuje 2 porównania i zwraca aktywnych użytkowników według kraju.

Pierwsze porównanie o nazwie „Ruch w aplikacji” używa wymiaru inListFilter do dopasowania wymiaru platform do wartości „iOS” i „Android”. Drugie porównanie o nazwie „Ruch w internecie” używa wymiaru stringFilter do dopasowania wymiaru platform do wartości „internet”.

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

W przypadku wszystkich żądań korzystających z funkcji porównań pole comparison jest automatycznie dodawane do wygenerowanego raportu. To pole zawiera nazwę porównania podanego w prośbie.

Oto przykładowy fragment odpowiedzi zawierającego porównania:

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

    ...

  ],

...

}