Statistik Game

Statistik Game adalah statistik kumulatif tentang game Anda yang dapat dilihat pemain di Profil gamer mereka. Statistik ini memungkinkan pemain melacak progres seumur hidup, melihat momen penting, dan membandingkan dengan pemain lain, serta mendukung fitur Google Play seperti Misi, Tantangan Sosial, dan lainnya pada masa mendatang.

Langkah-langkah integrasi

Kirim data menggunakan Game Stats API sebagai peristiwa pemain yang fleksibel untuk statistik berulang dan peristiwa progressUpdate yang telah ditentukan sebelumnya untuk statistik progres. Anda juga perlu mengonfigurasi logika untuk menghitung statistik yang akan muncul di profil Gamer dan informasi tampilannya.

Peristiwa Pemain merepresentasikan momen dalam game yang berbeda, penyelesaian loop game, atau pencapaian progres.

Peristiwa pemain ditentukan dan dimodelkan sebagai berikut:

1. Peristiwa diwakili oleh tindakan tertentu yang dilakukan oleh pemain, seperti menyelesaikan pertandingan, menyelesaikan lari, membuka peti, atau menyimpan progres di suatu area.
2. Setiap tindakan menghasilkan hasil tertentu atau memiliki karakteristik tertentu yang menentukan tindakan tersebut. Ini dimodelkan sebagai properti peristiwa yang memberikan konteks tentang peristiwa dan hasil spesifiknya (misalnya, jenis pertandingan, koin yang dikumpulkan selama pertandingan tersebut, hasil pertandingan, atau jumlah headshot).

Integrasi ini terdiri dari langkah-langkah berikut:

• Nyatakan skema data mentah: Tentukan peristiwa pemain menggunakan upload CSV di Konsol Play. Lihat panduan file CSV.
• Integrasikan dengan Game Stats API: Kirim data pemain mentah dalam format yang dinyatakan untuk peristiwa pemain yang fleksibel dan peristiwa progressUpdate.
  • Kirim semua peristiwa yang ditentukan menggunakan integrasi sisi klien atau sisi server. Untuk mengetahui informasi selengkapnya, lihat contoh untuk Peristiwa Fleksibel dan peristiwa progressUpdate.
• Upload file ZIP: Berikan 3 file CSV dan semua file gambar ikon yang menentukan 5 statistik berulang dan 1 tingkat progres pemain. Untuk mengetahui informasi selengkapnya, lihat Panduan file ZIP. Sertakan detail berikut:
  • File CSV untuk statistik berulang:
    • ID unik untuk statistik.
    • Tentukan label peristiwa yang akan digunakan untuk perhitungan statistik. Anda tidak dapat menggunakan label peristiwa progressUpdate di sini.
      • Tentukan label properti yang akan digunakan untuk perhitungan statistik. Ini harus berupa properti peristiwa yang ditentukan.
      • Tentukan jenis agregasi (SUM, MAX, MIN, atau COUNT) untuk menentukan cara menghitung statistik pada label properti yang dipilih.
      • Tentukan kondisi filter opsional untuk menghitung logika hanya jika kondisi terpenuhi. Tentukan properti dan label peristiwa, operator (=, <, atau >), dan nilai minimum.
    • Sertakan tanda boolean untuk menunjukkan apakah statistik dapat digunakan untuk fitur kompetitif.
    • Jika fitur dapat digunakan untuk fitur kompetitif, maka batas per jam minimum dan maksimum untuk pemain asli. Hal ini akan digunakan oleh kami untuk mengidentifikasi pemain yang mungkin menyalahgunakan saat berpartisipasi dalam fitur seperti liga dan tantangan sosial.
    • Berikan nama tampilan unik untuk statistik yang dilihat pemain.
    • Berikan teks unik yang menjelaskan statistik. Deskripsi ini harus memberikan detail tentang cara pemain memperolehnya.
    • Berikan ikon unik yang merepresentasikan statistik dengan memasukkan nama file ikon yang tepat dalam file CSV.
    • Berikan urutan untuk menentukan urutan pemain akan melihat statistik di Profil gamer mereka
    • Berikan input opsional apakah nilai yang meningkat atau nilai yang menurun baik untuk pemain. Input ini akan digunakan untuk merayakan gerakan pemain.
    • Berikan satuan pengukuran opsional untuk statistik seperti km, mil, dan detik.
  • File CSV untuk statistik progres pemain:
    • Berikan nama tampilan unik untuk progres pemain yang dilihat pemain.
    • Berikan ikon unik yang merepresentasikan statistik.
    • Berikan deskripsi untuk statistik progres.
    • Berikan input opsional apakah nilai yang meningkat atau menurun baik untuk pemain. Input ini akan digunakan untuk merayakan pergerakan pemain hanya jika properti currentProgress berjenis INT.
    • Berikan satuan pengukuran opsional untuk statistik seperti km, mil, detik.
  • File CSV untuk pelokalan: Berikan nama tampilan yang dilokalkan untuk semua statistik.
    • Tambahkan satu baris untuk setiap pelokalan.
    • Gunakan string nama tampilan statistik seperti yang ditambahkan di CSV sebelumnya untuk mengidentifikasi statistik secara unik yang akan ditambahkan pelokalan.
    • Tentukan bahasa dari daftar kode bahasa.
    • Tambahkan pelokalan untuk nama tampilan dalam bahasa yang ditentukan.
    • Menambahkan pelokalan untuk deskripsi statistik dalam bahasa yang ditentukan.

Panduan file CSV untuk acara

Anda dapat mengimpor acara menggunakan file PlayerGameEvent.csv.

Format PlayerGameEvent.csv

CSV berisi peristiwa yang dideklarasikan dan propertinya sebagai nilai yang dipisahkan koma dalam urutan berikut:

 Event Name,Property Name,Property Type

Jika Anda mengirim peristiwa progressUpdate untuk progressionStat, tambahkan baris untuk peristiwa ini. Peristiwa ini harus berisi setidaknya properti currentProgress berjenis INT atau STRING, ditambah properti lain yang ingin Anda kirim.

Panduan file ZIP untuk statistik

Anda dapat mengimpor statistik sekaligus menggunakan file ZIP. Lihat tabel untuk mengetahui nama file yang tepat untuk digunakan dalam file ZIP Anda:

Format RepetitiveStatsConfig.csv

CSV berisi peristiwa yang dideklarasikan dan propertinya sebagai nilai yang dipisahkan koma dalam urutan berikut:

Stat ID, Event Name,    Property Name,  Aggregation,     Stat Display Name, Stat Description, Filter Property,  Filter Operator,    Filter Value,   Is Competitive, minLimit, maxLimit, Icon File Name, Sequence Number, Good value direction, unit

Jika Anda tidak ingin menggunakan kondisi filter, biarkan sel kosong.

Format ProgressionStatConfig.csv

CSV berisi peristiwa yang dideklarasikan dan propertinya sebagai nilai yang dipisahkan koma dalam urutan berikut:

Stat ID, Stat Display Name, Stat Description, Icon File Name, Good value direction, unit

Statistik progres akan ditampilkan sebagai statistik pertama kepada pemain di Profil Gamer mereka.

Format StatLocalizations.csv

CSV berisi peristiwa yang dideklarasikan dan propertinya sebagai nilai yang dipisahkan koma dalam urutan berikut:

Stat ID, Stat Display Name, Language Code, Localized Stat Name, Localized Stat Description

Merencanakan skema

Anda dapat mengirim dua jenis data menggunakan Game Stats API: peristiwa pemain yang fleksibel dan peristiwa standar untuk statistik progres pemain. Contoh berikut menggambarkan tampilan peristiwa fleksibel di berbagai jenis game.

Peristiwa Pemutar Fleksibel

Peristiwa Pemain ditentukan oleh momen dalam game yang berbeda, penyelesaian game loop, atau pencapaian progres.

• Tentukan peristiwa sebagai momen dalam game tertentu, penyelesaian game loop, atau tonggak progres:
  • Penyelesaian loop game, seperti pertandingan atau lari yang telah diselesaikan.
  • Tonggak progres, seperti progres eksplorasi area tersimpan atau level yang diselesaikan.
• Tambahkan properti untuk memberikan konteks tentang peristiwa dan hasilnya, seperti nomor level, jenis pertandingan, jenis senjata, jumlah senjata, headshot, koin yang dikumpulkan, hasil pertandingan, waktu putaran, atau jenis mobil.
• Kirim peristiwa dalam sesi gameplay segera setelah terjadi. Misalnya, kirim peristiwa penyelesaian loop game segera setelah loop selesai.

Acara progressUpdate

Jika game Anda memiliki mekanisme progres utama, gunakan peristiwa ini untuk mengirimkan progres pemain saat ini. Acara ini memiliki satu properti yang telah ditentukan sebelumnya yang disebut "currentProgress" berjenis INT atau STRING. Kirim nilai progres saat ini menggunakan properti ini, karena ini adalah satu-satunya nilai yang muncul di UI Statistik Game Profil Gamer.

Karena pemain dapat membandingkan profil mereka berdasarkan progres saat ini dalam game, penting agar tidak ada penundaan dalam mendapatkan nilai progres saat ini setelah integrasi pertama. Untuk menampilkan progres saat ini yang akurat kepada pemain, Anda harus mengirim peristiwa progressUpdate di awal setiap sesi game serta setiap kali ada pembaruan pada progres saat ini.

Detail integrasi

Endpoint API dan SDK tersedia untuk mendapatkan masukan awal dan akan Tersedia Secara Umum (GA) mulai Juli 2026. Lihat linimasa

Bagian ini menunjukkan cara membuat peristiwa dan mengirimkannya dalam integrasi sisi klien dan sisi server.

Kapan Anda harus mengirimkan data

Acara Fleksibel mewakili tindakan dalam game yang terkait dengan penyelesaian game loop atau momen dalam game tertentu. Kirimkan peristiwa ini segera setelah terjadi. Misalnya, kirimkan peristiwa penyelesaian game loop segera setelah loop selesai.

progressUpdate Event merepresentasikan level progres pemain saat ini. Data untuk statistik progres harus dikirim menggunakan peristiwa ini dalam situasi berikut:

1. Setiap kali ada update pada progres saat ini, kirimkan nilai terbaru segera
2. Setiap kali pemain meluncurkan game untuk memastikan kehadiran statistik ini untuk pemain setiap saat.

Jalur integrasi

Ada dua jalur integrasi - klien dan server ke server.

Integrasi server ke server

Endpoint API publik memungkinkan Anda mengirim peristiwa dalam payload permintaan menggunakan konfigurasi berikut:

Parameter jalur

Otorisasi dan Autentikasi

Panggilan API server ke server mengikuti panduan Akses sisi server ke Layanan game Play standar menggunakan OAuth 2.0. Permintaan harus menyertakan token Bearer yang diotorisasi dengan cakupan https://www.googleapis.com/auth/games.

Acara Fleksibel: Isi Permintaan

BatchRecordEventsRequest

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

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string
}

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,
// RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
"timestampValue": "string",
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

Peristiwa progressUpdate: Isi Permintaan

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
}

Isi Respons

Jika berhasil, akan menampilkan status HTTP 200 OK dengan objek JSON kosong.

Contoh Isi Permintaan

Acara fleksibel: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication //and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "survivalTimeSeconds": {
          "durationValue": "240s"
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

Acara progressUpdate

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-01-01T18:00:00Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-01-01T17:00:00Z",
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

Integrasi sisi klien

Integrasi sisi klien akan tersedia menggunakan SDK Unity, Java, dan C++.

Integrasi sisi klien untuk PlayerGameEvent akan melibatkan pembuatan objek peristiwa di Java atau Csharp, bergantung pada SDK, di titik pemicu dan mengirimkannya menggunakan fungsi upload yang disediakan oleh SDK.

Demikian pula, untuk peristiwa progressUpdate, catat progres yang diperbarui menggunakan properti currentProgress dengan properti tambahan yang ditentukan dan kirimkan menggunakan fungsi upload yang disediakan oleh SDK.

Acara

Integrasi sisi klien untuk PlayerGameEvent adalah:

Membuat Peristiwa Game Pemutar Fleksibel

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("matchCompleted")
  .addProperty("matchId", "Match_A")
  .addProperty("gameMode", "Battle_B")
  .addProperty("mapId", "Location_XYZ")
  .addProperty("isWinner", true)
  .addProperty("survivalTimeSeconds", "240s")
  .addProperty("playerElimination", 2)
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var playerEvent = new PlayerGameEvent.Builder("matchCompleted")
   .AddProperty("matchId", "Match_A")
   .AddProperty("gameMode", "Battle_B")
   .AddProperty("mapId", "Location_XYZ")
   .AddProperty("isWinner", true)
   .AddProperty("survivalTimeSeconds", "240s")
   .AddProperty("playerElimination", 2)
   .Build();
var events = new List();
// ... populate list ...

// Build the PlayerGameEvent
PgsPlayerGameEvent* player_event = PgsPlayerGameEvent_create("matchCompleted");
if (player_event != nullptr) {
   PgsPlayerGameEvent_putString(player_event, "matchId", "Match_A");
   PgsPlayerGameEvent_putString(player_event, "gameMode", "Battle_B");
   PgsPlayerGameEvent_putString(player_event, "mapId", "Location_XYZ");
   PgsPlayerGameEvent_putBoolean(player_event, "isWinner", true);
   PgsPlayerGameEvent_putString(player_event, "survivalTimeSeconds", "240s");
   PgsPlayerGameEvent_putLong(player_event, "playerElimination", 2);
}

Membangun Peristiwa Game Pemain progressUpdate

// Build the PlayerGameEvent
PlayerGameEvent event = new PlayerGameEvent.Builder("progressUpdate")
  .addProperty("currentProgress", 52)
  // Add other properties if needed
  .build();

List events = new ArrayList<>();
// ... populate list ...

// Build the PlayerGameEvent
var progressEvent = new PlayerGameEvent.Builder("progressUpdate")
   .AddProperty("currentProgress", 52)
   // Add other properties if needed
   .Build();
var events = new List();
// ... populate list ...

PgsPlayerGameEvent* progress_event = PgsPlayerGameEvent_create("progressUpdate");
if (progress_event != nullptr) {
   PgsPlayerGameEvent_putLong(progress_event, "currentProgress", 52);
}

Merekam Peristiwa dan Mengupload

// Buffers the event locally.
client.recordEvent(event);

// Buffers the events locally, (List version)
client.recordEvents(events);

// This submits the events to PGS
client.requestEventsUpload();

// Buffers the event locally.
PlayGamesPlatform.Instance.RecordEvent(playerEvent);

// Buffers the events locally, (List version)
PlayGamesPlatform.Instance.RecordEvents(events);

// This submits the events to PGS
PlayGamesPlatform.Instance.RequestEventsUpload();

// Record the event
PgsGameStatsClient_recordEvent(client, player_event);

// This submits the events to PGS
PgsGameStatsClient_requestEventsUpload(client);

// Clean up handle to avoid leaks
PgsPlayerGameEvent_destroy(player_event);

// Clean up client handle when PGS operations are finished
PgsGameStatsClient_destroy(client);

Linimasa