Analiza

API zapytań analitycznych umożliwia zapytanie o zagregowane metryki doświadczeń w określonym zakresie dat. To API wspiera:

• Zapytania dotyczące dziennych aktywnych użytkowników (DAU), przychodu, retencji i innych metryk dla Twojego doświadczenia.
• Filtrowanie i grupowanie wyników według wymiarów, takich jak platforma, kraj i grupa wiekowa.
• Automatyczne zarządzanie wolnymi zapytaniami jako operacjami długoterminowymi, które możesz sondować w poszukiwaniu wyników.

Przed użyciem tego API, musisz wygenerować klucz API dla swojego doświadczenia. Przy tworzeniu klucza dodaj swoje doświadczenie do Uprawnień dostępu i przyznaj mu dostęp do operacji universe.analytics:read w systemie universe-analytics. Dołącz klucz w nagłówku żądania x-api-key w każdym zapytaniu.

Wszystkie punkty końcowe używają Twojego ID uniwersum, które możesz znaleźć na Dashboardzie Twórcy, wybierając swoje doświadczenie i kopiując ID uniwersum z strony przeglądu.

Zapytanie o metrykę

Aby zapytać o metrykę dla swojego doświadczenia:

1. Skopiuj klucz API do nagłówka żądania x-api-key.
2. Zastąp ${UniverseId} w URL swoim ID uniwersum doświadczenia.
3. Ustaw metric na metrykę, którą chcesz zapytać, np. DailyActiveUsers.
4. Ustaw granularity na obsługiwaną wartość rozmiaru zbioru czasowego, np. OneDay. Zobacz Opcje granularity.
5. Ustaw startTime i endTime na zakres dat, którego chcesz użyć, używając znaczników czasu UTC RFC 3339.
6. Wyślij zapytanie.

Zapytać o dziennych aktywnych użytkowników
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Większość zapytań kończy się natychmiast i zwraca 200 OK:

Odpowiedź (200 OK)
{
  "path": "v1/universes/1234567890/operations/metrics/abc123",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "breakdowns": [],
        "dataPoints": [
          { "time": "2026-01-01T00:00:00Z", "value": 10000 },
          { "time": "2026-01-02T00:00:00Z", "value": 10500 }
        ]
      }
    ]
  }
}

W przypadku dużych zakresów dat API może zwrócić 202 Accepted z "done": false. Zobacz Operacje długoterminowe.

Pola ciała żądania

Najwcześniejszy startTime, którego możesz użyć, zależy od typu metryki:

• Metryki standardowe (angażowanie, monetyzacja, pozyskiwanie, retencja): do 4 lat historii.
• Metryki wydajnościowe (wskaźnik awarii, wskaźnik klatek itp.): do 28 dni historii.

Zapytanie poza okresem retencji zwraca błąd 400 z kodem 2001.

Operacje długoterminowe

Większość zapytań kończy się natychmiast i zwraca 200 OK z "done": true. W przypadku zapytań o dużych zakresach dat lub wielu seriach podziału API zwraca 202 Accepted z "done": false oraz ścieżką do sondowania.

Oczekujące (202):

{
  "path": "path/to/poll",
  "done": false,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  }
}

Gdy done jest false, wyślij żądanie GET do https://apis.roblox.com/analytics-query-api/{path} — zastępując {path} wartością path z odpowiedzi — używając tego samego nagłówka x-api-key. Powtarzaj, aż done będzie true.

Zakończone (200):

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "breakdowns": [],
        "dataPoints": [
          {
            "time": "2026-01-01T00:00:00Z",
            "value": 10000
          }
        ]
      }
    ]
  }
}

Pusta tablica breakdowns wskazuje, że nie żądano podziału. Gdy używany jest podział, każdy wpis w response.values odpowiada jednej wartości wymiaru. Zobacz Użyj podziałów.

Gdy operacja się nie powiedzie, w treści znajduje się error zamiast response:

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "error": {
    "code": 2001,
    "message": "Żądana granularność nie jest obsługiwana dla tej metryki."
  }
}

Każdy wpis w response.values reprezentuje jedną serię, jedną na wartość wymiaru, gdy używany jest podział lub pojedynczy wpis z breakdowns: [], gdy nie żądano podziału. Każdy punkt danych w dataPoints ma:

Metryki o wartości tekstowej

Większość metryk jest liczbowych i raportuje swój wynik w value. Nieliczne metryki opisują zamiast tego każdy punkt danych za pomocą tekstu, a nie liczby. Dla tych danych zwracane są w tablicy stringValues, a value nie ma znaczenia. Pole stringValues jest całkowicie pomijane dla metryk liczbowych.

Na przykład, ThumbnailWinningSegments raportuje wygrywające segmenty miniatur dla każdego zbioru czasowego jako listę łańcuchów:

{
  "time": "2026-01-01T00:00:00Z",
  "value": 0,
  "stringValues": ["TopEngagement", "HighCTR"]
}

Status punktu danych

Opcje granularności

Pole granularity kontroluje rozmiar każdego zbioru czasowego w odpowiedzi. Granice zbiorów są wyrównane do UTC. Na przykład, zbiory OneDay trwają od północy UTC do północy UTC, więc wszelkie przesunięcia UTC w startTime lub endTime są normalizowane do UTC przed podzieleniem.

Nie każda metryka obsługuje każdą granularność. Zobacz Obsługiwane metryki po szczegóły.

Użyj podziałów

Nie każda metryka obsługuje każdy podział. Zobacz Obsługiwane metryki dla dostępnych podziałów dla każdej metryki.

Podziały grupują wyniki metryczny według wymiaru, zwracając jedną serię dla każdej unikalnej wartości wymiaru. Dodaj tablicę breakdown z jedną lub więcej nazw wymiarów do swojego żądania.

Zapytanie o przychód podzielony według platformy
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyRevenue",
    "granularity": "OneDay",
    "breakdown": ["Platform"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Każdy wpis w response.values zawiera tablicę breakdowns, identyfikującą wartość wymiaru dla danej serii:

{
  "response": {
    "values": [
      {
        "breakdowns": [{ "dimension": "Platform", "value": "Computer" }],
        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 8200 }]
      },
      {
        "breakdowns": [{ "dimension": "Platform", "value": "Phone" }],
        "dataPoints": [{ "time": "2026-01-01T00:00:00Z", "value": 3400 }]
      }
    ]
  }
}

Każdy obiekt w breakdowns ma:

Filtruj wyniki

Filtry zawężają wyniki zapytania do konkretnych wartości wymiarów. Dodaj tablicę filter do swojego żądania, gdzie każdy wpis określa dimension, values do dopasowania oraz operation do zastosowania.

Zapytanie o DAU tylko dla urządzeń mobilnych
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "filter": [
        {
            "dimension": "Platform",
            "values": ["Phone", "Tablet"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Operacje filtrowania

Możesz łączyć filtry z podziałami w tym samym żądaniu.

Odkrywanie wartości wymiarów

Punkt końcowy wartości wymiarów wyświetla dostępne wartości dla jednego lub więcej wymiarów metryki w określonym zakresie dat, bez obliczania samej metryki. Użyj go, aby odkryć prawidłowe wartości dla zapytań filter i breakdown — na przykład, krajów, identyfikatorów produktów lub identyfikatorów kroków w leju.

Aby zapytać o wartości wymiarów dla swojego doświadczenia:

1. Skopiuj klucz API do nagłówka żądania x-api-key.
2. Zastąp ${UniverseId} w URL swoim ID uniwersum doświadczenia.
3. Ustaw metric na metrykę, która zapewnia kontekst dla wymiarów.
4. Ustaw dimensions na nazwy wymiarów, dla których chcesz uzyskać wartości.
5. Ustaw startTime i endTime na zakres dat, którego chcesz użyć, używając znaczników czasu UTC RFC 3339.
6. Wyślij zapytanie.

Odkryj wartości krajów dla DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/dimension-values' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "dimensions": ["Country"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Pola ciała żądania

Większość zapytań kończy się natychmiast i zwraca 200 OK z "done": true. W przypadku zapytań o dużych zakresach dat API zwraca 202 Accepted z "done": false oraz path do sondowania. Zobacz Operacje długoterminowe dla procesu sondowania. Podczas sondowania użyj wartości path z odpowiedzi — wskazuje ona na v1/universes/{universeId}/operations/dimension-values/{operationId}, różniącą się od ścieżki sondowania metryk.

Zakończone (200):

{
  "path": "path/to/poll",
  "done": true,
  "metadata": {
    "createdTime": "2026-01-15T00:00:00Z"
  },
  "response": {
    "values": [
      {
        "dimension": "Country",
        "values": [{ "value": "US" }, { "value": "GB" }]
      }
    ]
  }
}

Każdy wpis w response.values reprezentuje jeden żądany wymiar. Każdy obiekt w values ma:

Błędy używają tej samej osłony done: true i error jak punkt końcowy metryk. Nieobsługiwany wymiar dla określonej metryki zwraca 400 z kodem 2001. Zobacz Częste błędy.

Częste zapytania

Poniższe przykłady pokazują częste zapytania, w tym metryki dostępne na stronach analitycznych Dashboarda Twórcy.

Przychód

Zapytać o dzienny przychód w Robux
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyRevenue",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Retencja D1

Zapytać o retencję D1
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "ForwardD1Retention",
    "granularity": "OneDay",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Nowi użytkownicy vs. wracający użytkownicy

Zapytać o DAU podzielone na nowych i wracających
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneDay",
    "breakdown": ["IsNewUser"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Agregacja tygodniowa

Użyj większej granularności dla dłuższej perspektywy z mniejszą liczbą punktów danych. Przy granularności OneWeek, każdy zbiór zlicza unikalnych użytkowników przez cały siedmiodniowy okres — a nie sumę wartości dziennych.

Zapytać o DAU przy tygodniowej granularności
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "OneWeek",
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-04-01T00:00:00Z"
}'

Podział Top-N

Aby sklasyfikować według jednej metryki i wyświetlić inną dla tego samego zbioru wartości, użyj dwóch zapytań. Na przykład, aby zobaczyć konwersję płacących użytkowników dla 5 najlepszych krajów według DAU:

Krok 1: Odkryj najlepsze N wartości wymiarów. Użyj granularity: "None", aby uzyskać jeden zsumowany wynik i użyj limit, aby ograniczyć liczbę zwróconych serii:

Odkryj 5 najlepszych krajów według DAU
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "DailyActiveUsers",
    "granularity": "None",
    "breakdown": ["Country"],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z",
    "limit": 5
}'

Krok 2: Zapytaj o metrykę wyświetlania, filtrując według wartości zwróconych w kroku 1:

Konwersja płacących użytkowników dla 5 najlepszych krajów
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "PayingUsersCVR",
    "granularity": "OneDay",
    "breakdown": ["Country"],
    "filter": [
        {
            "dimension": "Country",
            "values": ["US", "GB", "PH", "VN", "DE"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Kroki w leju

Leje pokazują, jak użytkownicy przechodzą przez zdefiniowaną sekwencję kroków w Twoim doświadczeniu. Zapytanie o metryki w leju wymaga dwóch zapytań, ponieważ identyfikatory kroków są dynamiczne.

Krok 1: Odkryj kroki w leju. Krok w leju pojawia się w wynikach tylko dla dni, gdy co najmniej jeden użytkownik osiągnął ten krok. Użycie dłuższego okresu wstecz (90 dni jest bezpiecznym domyślnym) zapewnia, że rzadko osiągane kroki również pojawią się w odpowiedzi odkrywczej. Użyj granularity: "None", aby uzyskać jeden zsumowany wynik na krok:

Odkryj kroki w leju dla leju poziomów
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "FunnelUserTotalCount",
    "granularity": "None",
    "breakdown": ["FunnelStep"],
    "filter": [
        {
            "dimension": "FunnelName",
            "values": ["Levels"],
            "operation": "In"
        }
    ],
    "startTime": "2025-11-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Krok 2: Zbadaj metrykę leju dla każdego kroku, filtrując według identyfikatorów kroków zwróconych w kroku 1:

Wskaźnik odpływu użytkowników na kroku dla leju poziomów
curl --location 'https://apis.roblox.com/analytics-query-api/v1/universes/${UniverseId}/metrics' \
--header 'x-api-key: ${ApiKey}' \
--header 'Content-Type: application/json' \
--data '{
    "metric": "FunnelUserChurnRate",
    "granularity": "None",
    "breakdown": ["FunnelStep"],
    "filter": [
        {
            "dimension": "FunnelStep",
            "values": ["1", "2", "3", "4", "5"],
            "operation": "In"
        },
        {
            "dimension": "FunnelName",
            "values": ["Levels"],
            "operation": "In"
        }
    ],
    "startTime": "2026-01-01T00:00:00Z",
    "endTime": "2026-02-01T00:00:00Z"
}'

Częste błędy

Większość błędów jest zwracana jako błędy operacji zapytania: treść odpowiedzi zawiera "done": true oraz obiekt error z numerycznym code i tekstem message. Błędy uwierzytelniania i błędy zasobów (401, 404) są prostymi odpowiedziami HTTP bez treści osłony, dlatego tabela poniżej pokazuje — dla ich kodów błędów.