Statystyki meczu

Statystyki gry to zbiorcze statystyki dotyczące Twojej gry, które gracze mogą wyświetlać w swoim profilu gracza. Te statystyki pozwalają graczom śledzić postępy w całej grze, oglądać najważniejsze momenty i porównywać się z innymi graczami. W przyszłości będą też zasilać funkcje Google Play, takie jak zadania, wyzwania społecznościowe i inne.

Statystyki meczowe muszą:

• nie wymagać zakupu (np. kupowania klejnotów), czyli nie powinny się aktualizować w wyniku zakupu w aplikacji.
• nie wymagać oglądania reklam, czyli nie powinny się aktualizować w wyniku oglądania reklamy;
• nie może być ogólnym korzystaniem z gry (np. otwieraniem gry czy używaniem ustawień);
• Nie zawierać danych osobowych ani poufnych danych użytkownika w rozumieniu zasad Google Play, w tym identyfikatorów użytkowników, haseł, dokładnej lokalizacji ani danych dotyczących zdrowia, ani żadnych treści obraźliwych, wulgarnych, o charakterze seksualnym, zawierających przemoc lub szerzących nienawiść.
• być dostępne dla wszystkich użytkowników (np. nie mogą to być działania specyficzne dla zespołu ani dostępne tylko dla użytkowników określonego poziomu lub ograniczone czasowo);

Integracja

Wysyłaj dane za pomocą interfejsu Game Stats API jako zdarzenia gracza w przypadku powtarzalnych statystyk gry i wstępnie zdefiniowane zdarzenie progressUpdate w przypadku statystyk postępów. Musisz też skonfigurować logikę obliczania statystyk gry, które będą wyświetlane w profilu gracza, oraz informacje o ich wyświetlaniu.

Zdarzenia gracza reprezentują odrębne momenty w grze, ukończenie pętli gry lub kamienie milowe postępu.

Zdarzenie związane z graczem jest zdefiniowane i modelowane w ten sposób:

1. Zdarzenie jest reprezentowane przez konkretne działanie gracza, takie jak ukończenie meczu, ukończenie biegu, odblokowanie skrzyni lub zapisanie postępów w danym obszarze.
2. Każde działanie ma określone skutki lub cechy, które je definiują. Są one modelowane jako właściwości zdarzenia, które dostarczają kontekstu zdarzenia i jego konkretnych wyników (np. typ meczu, liczba zebranych monet, wynik meczu lub liczba trafień w głowę).

Integracja obejmuje te kroki:

• Zadeklaruj schemat danych pierwotnych: zdefiniuj zdarzenia dotyczące graczy, przesyłając plik CSV w Konsoli Play. Zobacz Tworzenie wydarzeń.
• Integracja z interfejsem API statystyk gry: wysyłaj nieprzetworzone dane graczy w zadeklarowanym formacie dla zdarzeń graczy i zdarzenia progressUpdate.
  • Wysyłaj wszystkie zdefiniowane zdarzenia za pomocą integracji po stronie klienta lub serwera. Więcej informacji znajdziesz w przykładach zdarzeń odtwarzacza i zdarzenia progressUpdate.
• Prześlij plik ZIP: prześlij 3 pliki CSV i wszystkie pliki obrazów ikon, które określają 5 powtarzających się statystyk i 1 poziom rozwoju gracza. Więcej informacji znajdziesz w wytycznych dotyczących plików ZIP. Podaj te informacje:
  • Plik CSV z powtarzającymi się statystykami:
    • Unikalny identyfikator statystyki.
    • Określ etykietę zdarzenia, która będzie używana do obliczania statystyk. Nie możesz tu użyć etykiety zdarzenia progressUpdate.
      • Określ etykietę właściwości, która ma być używana do obliczania statystyk. Musi to być właściwość określonego zdarzenia.
      • Określ typ agregacji (SUM, MAX, MIN lub COUNT), aby określić sposób obliczania statystyki w wybranej etykiecie właściwości.
      • Określ opcjonalny warunek filtra, aby obliczać logikę tylko wtedy, gdy warunek jest spełniony. Określ właściwość i etykietę zdarzenia, operator (=, <, <=, >= lub >) oraz wartość progową.
    • Dodaj flagę wartości logicznej, aby wskazać, czy statystyki mogą być używane w przypadku funkcji konkurencyjnych.
    • Jeśli funkcja może być używana w przypadku funkcji konkurencyjnych, podaj minimalne i maksymalne limity godzinowe dla prawdziwego gracza. Będziemy go używać do identyfikowania graczy, którzy mogą niewłaściwie korzystać z funkcji takich jak ligi i wyzwania społecznościowe.
    • Podaj unikalną wyświetlaną nazwę statystyki, która będzie widoczna dla graczy.
    • Podaj unikalny tekst opisujący statystykę. Opis powinien zawierać szczegółowe informacje o tym, jak gracz może ją zdobyć. Będzie on wyświetlany graczom w interfejsie profilu gracza.
    • Podaj unikalną ikonę reprezentującą statystykę, wpisując dokładną nazwę pliku ikony w pliku CSV.
    • Podaj opcjonalne dane wejściowe, które określają, czy rosnąca czy malejąca wartość jest korzystna dla gracza. Te dane wejściowe będą używane do świętowania ruchów graczy.
    • Podaj opcjonalną jednostkę miary dla statystyki, np. km, mile lub sekundy.
  • Plik CSV ze statystykami postępów gracza:
    • Podaj unikalną wyświetlaną nazwę postępów gracza, która będzie widoczna dla graczy.
    • Dodaj unikalną ikonę reprezentującą statystykę.
    • Podaj opis statystyki postępu.
    • Podaj opcjonalne dane wejściowe, które określają, czy rosnąca czy malejąca wartość jest korzystna dla gracza. Ten typ danych wejściowych będzie używany do informowania o ruchach graczy tylko wtedy, gdy właściwość currentProgress jest typu INT.
    • Podaj opcjonalną jednostkę miary dla statystyki, np. km, mile, sekundy.
  • Plik CSV do lokalizacji: podaj zlokalizowane nazwy wyświetlane wszystkich statystyk.
    • Dodaj po jednym wierszu dla każdej wersji językowej.
    • Użyj ciągu znaków wyświetlanej nazwy statystyki dodanego w poprzednim pliku CSV, aby jednoznacznie zidentyfikować statystykę, do której dodawane jest tłumaczenie.
    • Określ język z listy kodów języków.
    • Dodaj lokalizację nazwy wyświetlanej w określonym języku.
    • Dodaj zlokalizowany opis statystyki w określonym języku.

Planowanie schematu

Za pomocą interfejsu API statystyk gry możesz wysyłać 2 rodzaje danych: zdarzenia gracza i wstępnie zdefiniowane zdarzenie dotyczące statystyk postępów gracza.

Poniższe przykłady pokazują, jak wyglądają zdarzenia odtwarzacza w różnych typach gier:

Zdarzenia odtwarzacza

Wydarzenia związane z graczem są definiowane przez odrębne momenty w grze, ukończenie pętli rozgrywki lub kamienie milowe postępu.

• Określ zdarzenia jako konkretne momenty w grze, ukończenie pętli gry lub kamienie milowe postępu:
  • Ukończenie pętli gry, np. ukończenie meczu lub biegu.
  • kamienie milowe postępu, np. postęp w odkrywaniu zapisanych obszarów lub ukończony poziom;
  • Powtarzalne statystyki powinny odzwierciedlać powtarzalne działania gracza, dlatego zdefiniowane zdarzenia powinny być powiązane z podstawową rozgrywką.
• Dodaj właściwości, aby podać kontekst zdarzenia i jego wyników, np. numer poziomu, typ meczu, rodzaj broni, liczbę broni, trafienia w głowę, zebrane monety, wynik meczu, czas okrążenia lub typ samochodu.
• Wysyłaj zdarzenia w ramach sesji rozgrywki od razu po ich wystąpieniu. Na przykład wyślij zdarzenie ukończenia pętli gry natychmiast po jej zakończeniu.

progressUpdate zdarzenie

Jeśli w grze występuje podstawowa mechanika postępu, użyj tego zdarzenia, aby wysłać bieżące postępy gracza. Zdarzenie ma 1 wstępnie zdefiniowany parametr o nazwie „currentProgress” typu INT lub STRING. Za pomocą tej właściwości należy przesyłać bieżącą wartość postępów gracza w głównym mechanizmie postępów. Jeśli używasz tego zdarzenia, musi być obecna wstępnie zdefiniowana właściwość „currentProgress”, a za jej pomocą musi być zdefiniowana statystyka postępu.

Możesz wysyłać bieżącą wartość innych systemów postępów w grze, np. lifetime highest score lub current coin balance, jako inne właściwości tego zdarzenia.

Gracze mogą porównywać swoje profile na podstawie aktualnych postępów w grze, dlatego ważne jest, aby po pierwszej integracji nie było opóźnienia w uzyskiwaniu wartości bieżącego postępu. Aby przedstawić graczom aktualny postęp, należy wysyłać zdarzenie progressUpdate na początku każdej sesji gry, a także za każdym razem, gdy nastąpi zmiana aktualnego postępu.

Konfigurowanie statystyk

Musisz skonfigurować statystyki powtarzalne i postępów, definiując logikę obliczeń i informacje o wyświetlaniu każdej statystyki. Poniżej znajdziesz przykłady statystyk powtarzalnych z różnych gatunków gier. Powtarzalne statystyki to zwykle statystyki, które są wielokrotnie aktualizowane w przypadku dowolnego gracza w bardzo niewielu (3–4) sesjach gry i są powiązane z główną pętlą gry.

Szczegóły integracji

Punkty końcowe interfejsu API i pakiet SDK są dostępne do przetestowania i przekazania opinii. Staną się ogólnie dostępne w sierpniu 2026 roku. Zobacz oś czasu

W tej sekcji pokazujemy, jak tworzyć zdarzenia i wysyłać je w ramach integracji po stronie klienta i po stronie serwera.

Kiedy należy wysyłać dane

Zdarzenia gracza reprezentują działania w grze związane z ukończeniem pętli gry lub konkretnymi momentami w grze. Przesyłaj te zdarzenia od razu po ich wystąpieniu. Na przykład prześlij zdarzenie ukończenia pętli rozgrywki od razu po jej zakończeniu.

progressUpdate Event reprezentuje bieżący poziom postępu gracza. Dane dotyczące statystyk postępów należy przesyłać za pomocą tego zdarzenia w tych sytuacjach:

1. Gdy tylko nastąpi zmiana bieżącego postępu, natychmiast wyślij najnowszą wartość.
2. Za każdym razem, gdy gracz uruchamia grę, aby zapewnić stałą obecność tej statystyki.

Ścieżki integracji

Istnieją 2 ścieżki integracji: klient i serwer-serwer.

Integracja serwer-serwer

Publiczny punkt końcowy interfejsu API umożliwia wysyłanie zdarzeń w ładunku żądania przy użyciu tych konfiguracji:

Żądanie HTTP

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

Parametry ścieżki

Autoryzacja i uwierzytelnianie

Wywołania interfejsu API między serwerami są zgodne ze standardowymi wytycznymi dotyczącymi dostępu po stronie serwera do usług gier Play przy użyciu protokołu OAuth 2.0. Żądania muszą zawierać token okaziciela autoryzowany w zakresie https://www.googleapis.com/auth/games.

Zdarzenia: treść żądania

Backend interfejsu API ma ścisłe limity weryfikacji strukturalnej:

• Wielkość wsadu: maksymalnie 30 zdarzeń na BatchRecordEventsRequest.
• Liczba usług: maksymalnie 25 usług niestandardowych na konto.PlayerGameEvent
• Limity długości: nazwa zdarzenia (maks. 100 znaków), klucze właściwości (maks. 100 znaków) i wartości tekstowe właściwości (maks. 1024 znaki).
• Identyfikator zdarzenia: musi być prawidłowym ciągiem znaków UUID o długości 36 znaków.
• Ponawianie i pamięć podręczna: unikaj buforowania lub gromadzenia nadmiernej liczby zdarzeń lokalnie, jeśli interfejs API nie działa, ponieważ ponawianie wsadowe przekraczające 30 zdarzeń zostanie odrzucone. Zawsze dziel ponawiane próby na mniejsze części, aby nie przekroczyć limitu wielkości wsadu.

BatchRecordEventsRequest

Zobacz BatchRecordEventsRequest.

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

progressUpdate event: Request Body

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent – progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

Treść odpowiedzi

Jeśli operacja się powiedzie, zwraca kod stanu HTTP 200 OK z pustym obiektem JSON.

Przykładowa treść żądania

Zdarzenie: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

progressUpdate wydarzenie

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

Implementacje klienta

Więcej informacji o wdrażaniu klienta Statystyk gier na Twojej platformie znajdziesz w tych materiałach:

• Android
• Unity
• C++

Kamienie milowe