Maç İstatistikleri

Oyun istatistikleri, oyuncuların oyuncu profillerinde görebileceği, oyununuzla ilgili kümülatif istatistiklerdir. Bu istatistikler, oyuncuların yaşam boyu ilerlemeyi takip etmesine, önemli anları görmesine ve diğer oyuncularla karşılaştırma yapmasına olanak tanır. Ayrıca, gelecekte Google Play'deki Görevler ve Sosyal Meydan Okumalar gibi özellikleri destekler.

Entegrasyon adımları

Tekrarlanan istatistikler için esnek oyuncu etkinlikleri ve ilerleme durumu istatistiği için önceden tanımlanmış bir etkinlik progressUpdate olarak Oyun İstatistikleri API'sini kullanarak veri gönderin. Ayrıca, oyuncu profilinde görünecek istatistiklerin hesaplanması ve bu istatistiklerin görüntülenme bilgileriyle ilgili mantığı da yapılandırmanız gerekir.

Oyuncu etkinlikleri, farklı oyun içi anları, oyun döngüsü tamamlamalarını veya ilerleme kilometre taşlarını temsil eder.

Oyuncu etkinliği şu şekilde tanımlanır ve modellenir:

1. Etkinlikler, oyuncunun yaptığı belirli bir işlemle (ör. maçı tamamlama, koşuyu bitirme, sandığın kilidini açma veya bir alandaki ilerlemeyi kaydetme) temsil edilir.
2. Her işlem belirli sonuçlar doğurur veya işlemi tanımlayan belirli özelliklere sahiptir. Bunlar, etkinlik ve belirli sonuçları hakkında bağlam sağlayan etkinlik özellikleri olarak modellenir (örneğin, eşleşme türü, bu koşu sırasında toplanan jetonlar, maç sonucu veya headshot sayısı).

Entegrasyon aşağıdaki adımlardan oluşur:

• Ham veri şemasını beyan edin: Play Console'da CSV yükleme kullanarak oyuncu etkinliklerini tanımlayın. CSV dosyası yönergeleri başlıklı makaleyi inceleyin.
• Game Stats API ile entegrasyon: Esnek oyuncu etkinlikleri ve progressUpdate etkinliği için ham oyuncu verilerini belirtilen biçimde gönderin.
  • İstemci tarafı veya sunucu tarafı entegrasyonunu kullanarak tanımlanan tüm etkinlikleri gönderin. Daha fazla bilgi için Esnek Etkinlikler ve progressUpdate etkinliği ile ilgili örneklere bakın.
• ZIP dosyası yükleme: 3 CSV dosyası ve 5 tekrarlayan istatistik ile 1 oyuncu ilerleme düzeyini tanımlayan tüm simge resim dosyalarını sağlayın. Daha fazla bilgi için ZIP dosyası yönergeleri konusunu inceleyin. Aşağıdaki ayrıntıları ekleyin:
  • Tekrarlanan istatistikler için CSV dosyası:
    • İstatistik için benzersiz bir kimlik.
    • İstatistik hesaplamasında kullanılacak etkinlik etiketini belirtin. Burada progressUpdate etkinlik etiketini kullanamazsınız.
      • İstatistik hesaplamasında kullanılacak özellik etiketini belirtin. Bu, belirtilen etkinliğin bir özelliği olmalıdır.
      • Seçili mülk etiketindeki istatistiğin nasıl hesaplanacağını belirlemek için toplama türünü (TOPLAM, MAKS, MİN veya SAY) belirtin.
      • Mantığın yalnızca koşul karşılandığında hesaplanması için isteğe bağlı bir filtre koşulu belirtin. Özelliği ve etkinlik etiketini, operatörü (=, < veya >) ve eşik değerini tanımlayın.
    • İstatistiğin rekabetçi özellikler için kullanılıp kullanılamayacağını belirten bir boole işareti ekleyin.
    • Özellik, rekabetçi özellikler için kullanılabiliyorsa gerçek bir oyuncu için saatlik minimum ve maksimum sınırlar. Bu bilgi, ligler ve sosyal yarışmalar gibi özelliklere katılırken kötüye kullanımda bulunabilecek oyuncuları belirlememize yardımcı olur.
    • Oyuncuların göreceği istatistik için benzersiz bir görünen ad girin.
    • İstatistiği açıklayan benzersiz bir metin girin. Bu açıklama, oyuncunun istatistiği nasıl kazandığıyla ilgili ayrıntılar içermelidir.
    • CSV dosyasına tam simge dosya adını girerek istatistiği temsil eden benzersiz bir simge sağlayın.
    • Oyuncunun, oyuncu profilindeki istatistikleri hangi sırayla göreceğini belirtmek için bir sıra düzeni sağlayın.
    • Artan veya azalan değerin oyuncu için iyi olup olmadığına dair isteğe bağlı bir giriş sağlayın. Bu giriş, oyuncu hareketlerini kutlamak için kullanılacak.
    • İstatistik için isteğe bağlı bir ölçü birimi (ör. kilometre, mil ve saniye) sağlayın.
  • Oyuncu ilerleme durumu istatistiği için CSV dosyası:
    • Oyuncuların göreceği oyuncu ilerleme durumu için benzersiz bir görünen ad girin.
    • İstatistiği temsil eden benzersiz bir simge sağlayın.
    • İlerleme durumu istatistiği için bir açıklama girin.
    • Artan veya azalan değerin oyuncu için iyi olup olmadığıyla ilgili isteğe bağlı bir giriş sağlayın. Bu giriş, yalnızca currentProgress özelliği INT türündeyken oyuncu hareketlerini kutlamak için kullanılır.
    • İstatistik için isteğe bağlı bir ölçü birimi (ör. km, mil, saniye) girin.
  • Yerelleştirme için CSV dosyası: Tüm istatistikler için yerelleştirilmiş görünen adlar sağlayın.
    • Her yerelleştirme için bir satır ekleyin.
    • Yerelleştirmenin eklendiği istatistiği benzersiz şekilde tanımlamak için önceki CSV'ye eklenen istatistik görünen adı dizesini kullanın.
    • Dil kodları listesinden dili belirtin.
    • Belirtilen dilde görünen ad için yerelleştirme ekleyin.
    • İstatistik açıklamasına belirtilen dilde yerelleştirme ekleyin.

Etkinlikler için CSV dosyası yönergeleri

Etkinlikleri PlayerGameEvent.csv dosyasını kullanarak içe aktarabilirsiniz.

PlayerGameEvent.csv biçimi

CSV dosyasında, aşağıdaki sırayla virgülle ayrılmış değerler olarak belirtilen etkinlik ve özellikleri yer alır:

 Event Name,Property Name,Property Type

progressionStat için progressUpdate etkinliğini gönderiyorsanız bu etkinlik için bir satır ekleyin. Bu etkinlik, INT veya STRING türünde en az bir currentProgress özelliği ve göndermek istediğiniz diğer özellikleri içermelidir.

İstatistikler için ZIP dosyası yönergeleri

ZIP dosyası kullanarak istatistikleri tek seferde içe aktarabilirsiniz. ZIP dosyanızda kullanabileceğiniz tam dosya adları için tabloya bakın:

RepetitiveStatsConfig.csv biçimi

CSV dosyasında, aşağıdaki sırayla virgülle ayrılmış değerler olarak belirtilen etkinlik ve özellikleri yer alır:

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

Filtre koşulunu kullanmak istemiyorsanız hücreyi boş bırakın.

ProgressionStatConfig.csv biçimi

CSV dosyasında, aşağıdaki sırayla virgülle ayrılmış değerler olarak belirtilen etkinlik ve özellikleri yer alır:

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

İlerleme durumu istatistiği, oyuncunun oyuncu profilinde ilk gösterilen istatistik olur.

StatLocalizations.csv biçimi

CSV dosyasında, aşağıdaki sırayla virgülle ayrılmış değerler olarak belirtilen etkinlik ve özellikleri yer alır:

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

Şemayı planlama

Game Stats API'yi kullanarak iki tür veri gönderebilirsiniz: esnek oyuncu etkinlikleri ve oyuncu ilerleme istatistikleri için önceden tanımlanmış bir etkinlik. Aşağıdaki örneklerde, esnek etkinliklerin çeşitli oyun türlerinde nasıl göründüğü gösterilmektedir.

Esnek oynatıcı etkinlikleri

Oyuncu etkinlikleri, farklı oyun içi anlar, oyun döngüsü tamamlamaları veya ilerleme kilometre taşları ile tanımlanır.

• Etkinlikleri belirli oyun içi anlar, oyun döngüsü tamamlanmaları veya ilerleme aşamaları olarak tanımlayın:
  • Oyun döngüsü tamamlanmaları (ör. tamamlanan bir maç veya koşu)
  • Kaydedilen alan keşfi ilerlemesi veya tamamlanan seviye gibi ilerleme kilometre taşları.
• Etkinlik ve sonuçları hakkında bağlam bilgisi sağlamak için özellikler ekleyin. Örneğin; seviye numarası, maç türü, silah türü, silah sayısı, kafa vuruşları, toplanan jetonlar, maç sonucu, tur süresi veya araba türü.
• Oyun oturumu içindeki etkinlikleri gerçekleşir gerçekleşmez gönderin. Örneğin, döngü tamamlandıktan hemen sonra bir oyun döngüsü tamamlama etkinliği gönderin.

progressUpdate Etkinlik

Oyununuzda birincil ilerleme mekanizması varsa oyuncunun mevcut ilerleme durumunu göndermek için bu etkinliği kullanın. Etkinlikte INT veya STRING türünde "currentProgress" adlı önceden tanımlanmış bir özellik bulunur. Bu özellik, oyuncu profilinin oyun istatistikleri kullanıcı arayüzünde görünen tek değer olduğundan mevcut ilerleme durumunun değerini bu özelliği kullanarak gönderin.

Oyuncular, profillerini oyun içindeki mevcut ilerleme durumuna göre karşılaştırabildiğinden ilk entegrasyondan sonra mevcut ilerleme durumu değerinin alınmasında gecikme olmaması önemlidir. Oyunculara doğru mevcut ilerleme durumunu göstermek için her oyun oturumunun başında ve mevcut ilerleme durumu güncellendiğinde progressUpdate etkinliğini göndermeniz gerekir.

Entegrasyon ayrıntıları

API uç noktaları ve SDK, erken geri bildirim için kullanılabilir ve Temmuz 2026'dan itibaren Genel Kullanıma (GA) sunulacaktır. Zaman çizelgesini inceleyin.

Bu bölümde, etkinliklerin nasıl oluşturulacağı ve hem istemci tarafı hem de sunucu tarafı entegrasyonlarında nasıl gönderileceği gösterilmektedir.

Verileri ne zaman göndermelisiniz?

Esnek etkinlikler, oyun döngüsünün tamamlanması veya belirli oyun içi anlarla ilgili oyun içi işlemleri temsil eder. Bu etkinlikleri gerçekleşir gerçekleşmez gönderin. Örneğin, döngü tamamlandığı anda oyun döngüsü tamamlama etkinliğini gönderin.

progressUpdate Event, oyuncunun mevcut ilerleme düzeyini gösterir. İlerleme durumu istatistiği verileri, aşağıdaki durumlarda bu etkinlik kullanılarak gönderilmelidir:

1. Mevcut ilerleme durumu güncellendiğinde en son değeri hemen gönderin.
2. Oyuncunun bu istatistiğe her zaman sahip olmasını sağlamak için oyuncu oyunu her başlattığında.

Entegrasyon yolları

İki entegrasyon yolu vardır: istemci ve sunucudan sunucuya.

Sunucudan sunucuya entegrasyon

Herkese açık bir API uç noktası, aşağıdaki yapılandırmaları kullanarak istek yükünde etkinlik göndermenize olanak tanır:

Yol parametreleri

Yetkilendirme ve Kimlik Doğrulama

Sunucudan sunucuya API çağrıları, OAuth 2.0 kullanılarak Play Games Hizmetleri'ne sunucu tarafı erişimi ile ilgili standart yönergeleri izler. İstekler, https://www.googleapis.com/auth/games kapsamıyla yetkilendirilmiş bir Bearer jetonu içermelidir.

Esnek Etkinlikler: İstek Metni

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

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
}

Yanıt Metni

Başarılı olursa boş bir JSON nesnesiyle HTTP 200 OK durumu döndürülür.

Örnek İstek Metni

Esnek etkinlik: 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
        }
      }
    }
  ]
}

progressUpdate etkinliği

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

İstemci tarafı entegrasyonu

İstemci tarafı entegrasyonu Unity, Java ve C++ SDK'ları kullanılarak sağlanacaktır.

PlayerGameEvent için istemci tarafı entegrasyonu, SDK'ya bağlı olarak Java veya Csharp'ta tetikleme noktalarında etkinlik nesnesi oluşturmanızı ve bunları SDK tarafından sağlanan yükleme işlevlerini kullanarak göndermenizi gerektirir.

Benzer şekilde, progressUpdate etkinliği için güncellenen ilerleme durumunu currentProgress özelliğiyle ek tanımlanmış özellikler kullanarak kaydedin ve SDK tarafından sağlanan yükleme işlevlerini kullanarak gönderin.

Etkinlikler

PlayerGameEvent için istemci tarafı entegrasyonları şunlardır:

Esnek Oyuncu Oyunu Etkinliği Oluşturma

// 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);
}

Build progressUpdate Player Game Event

// 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);
}

Etkinliği Kaydetme ve Yükleme

// 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);

Zaman çizelgesi