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.

• Tidak memerlukan pembelian (Misalnya, beli permata) yang tidak boleh diperbarui sebagai akibat dari pembelian IAP apa pun.
• Tidak memerlukan penayangan iklan, yaitu tidak boleh diupdate sebagai akibat dari penayangan iklan.
• Bukan penggunaan game yang umum (Misalnya, membuka game; menggunakan setelan).
• Tidak menyertakan Data Pengguna yang Bersifat Pribadi dan Sensitif, sebagaimana didefinisikan dalam Kebijakan Play, termasuk ID pengguna, sandi, data kesehatan atau lokasi presisi, atau konten yang menyinggung, tidak sopan, bersifat seksual, mengandung kekerasan, atau penuh kebencian.
• Tersedia untuk semua pengguna (Misalnya, bukan tindakan khusus tim atau hanya tersedia untuk pengguna dengan level tertentu atau terbatas untuk liveops berbatas waktu, dll.)

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. Data 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 Membuat acara.
• Integrasikan dengan Statistik Game 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 Pemutar 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 batas.
    • 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. ID 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 dan akan ditampilkan kepada pemain di UI Profil Gamer.
    • Berikan ikon unik yang merepresentasikan statistik dengan memasukkan nama file ikon yang tepat dalam file CSV.
    • Berikan input opsional apakah nilai yang meningkat atau 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.

Merencanakan skema

Anda dapat mengirim dua jenis data menggunakan Game Stats API: peristiwa pemain dan peristiwa standar untuk statistik progres pemain.

Contoh berikut menggambarkan tampilan peristiwa pemutar di berbagai jenis game:

Acara Pemutar

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.
  • Karena statistik berulang harus benar-benar mewakili tindakan berulang oleh pemain, peristiwa yang ditentukan harus dikaitkan dengan gameplay inti.
• 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 mengirim progres pemain saat ini. Peristiwa ini memiliki satu properti yang telah ditentukan sebelumnya yang disebut “currentProgress” dengan jenis INT atau STRING. Anda diharapkan mengirimkan nilai progres pemain saat ini dalam mekanisme progres utama menggunakan properti ini. Jika Anda menggunakan peristiwa ini, properti standar "currentProgress" harus ada dan statistik progres harus ditentukan menggunakan properti ini.

Anda dapat mengirim nilai saat ini untuk sistem progres lainnya dalam game Anda seperti lifetime highest score atau current coin balance sebagai properti lain dari peristiwa ini.

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.

Mengonfigurasi statistik Anda

Anda harus mengonfigurasi statistik pengulangan dan progres dengan menentukan logika komputasi dan menampilkan informasi tentang setiap statistik. Contoh statistik pengulangan dari berbagai Genre Game disertakan di bawah. Statistik berulang biasanya adalah statistik yang diperbarui berulang kali untuk pemain mana pun di beberapa (3-4) sesi game dan terkait dengan core game loop.

Detail integrasi

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

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

Kapan Anda harus mengirimkan data

Peristiwa Pemain 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.

Peristiwa progressUpdate mewakili 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.

Peristiwa Fleksibel: Isi Permintaan

Backend API memiliki batas validasi struktural yang ketat:

• Ukuran tumpukan: Maksimum 30 peristiwa per BatchRecordEventsRequest.
• Jumlah properti: Maksimum 25 properti kustom per PlayerGameEvent.
• Batasan panjang: Nama peristiwa (maks. 100 karakter), kunci properti (maks. 100 karakter), dan nilai string properti (maks. 1.024 karakter).
• ID Acara: Harus berupa string UUID 36 karakter yang valid.
• Coba lagi dan penyimpanan dalam cache: Hindari penyimpanan dalam cache atau pengumpulan peristiwa berlebihan secara lokal jika API gagal, karena percobaan ulang batch yang melebihi 30 peristiwa akan ditolak. Selalu bagi percobaan ulang menjadi beberapa bagian untuk mematuhi batas ukuran tumpukan.

BatchRecordEventsRequest

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

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 // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

Isi Respons

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

Contoh Isi Permintaan

Event: 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
        }
      }
    }
  ]
}

Acara progressUpdate

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

Implementasi klien

Untuk mempelajari penerapan klien Statistik Game untuk platform Anda, lihat referensi berikut:

• Android
• Unity
• C++

Pencapaian