Oyununuza kaydedilmiş oyunlar ekleyin

Google Sign-in API'sinin desteğinin sonlandırılmasının ardından, 2026'da Games v1 SDK'sını kaldırıyoruz. Şubat 2025'ten sonra, games v1 SDK'sına yeni entegre edilmiş oyunları Google Play'de yayınlayamazsınız. Bunun yerine games v2 SDK'sını kullanmanızı öneririz.
Önceki oyunların v1 entegrasyonlarına sahip mevcut oyunlar birkaç yıl boyunca çalışmaya devam edecek olsa da Haziran 2025'ten itibaren v2'ye geçiş yapmanızı öneririz.
Bu kılavuz, Play Games Hizmetleri v1 SDK'sının kullanımıyla ilgilidir. Play Games Hizmetleri v2 için C++ SDK'sı henüz kullanıma sunulmamıştır.

Bu kılavuzda, C++ uygulamasında Kayıtlı Oyunlar hizmetini kullanarak bir oyuncunun oyundaki ilerleme verilerini nasıl kaydedeceğiniz ve yükleyeceğiniz gösterilmektedir. Oynatma sırasında oyuncunun oyundaki ilerleme durumunu otomatik olarak yüklemek ve kaydetmek için bu hizmeti kullanabilirsiniz. Bu hizmet, oyuncuların mevcut bir kayıtlı oyunu güncellemek veya geri yüklemek ya da yeni bir oyun kaydetmek için kullanıcı arayüzünü tetiklemelerine de olanak tanıyabilir.

Başlamadan önce

Henüz yapmadıysanız Kayıtlı Oyunlar oyun kavramlarını incelemeniz faydalı olabilir.

Kayıtlı Oyunlar API'sini kullanarak kodlamaya başlamadan önce:

Veri biçimleri ve platformlar arası uyumluluk

Google'ın sunucularına kaydettiğiniz Kayıtlı Oyunlar verileri std::vector<uint8_t> biçiminde olmalıdır. Kayıtlı Oyunlar hizmeti, verilerinizi platformlar arası uyumluluk için kodlar. Android uygulamaları, bu verileri platformlar arası uyumluluk sorunları olmadan bayt dizisi olarak okuyabilir.

Kayıtlı Oyunlar verileriniz için veri biçimi seçerken platforma özgü biçimler kullanmaktan kaçının. Birden fazla platformda güçlü kitaplık desteğine sahip XML veya JSON gibi bir veri biçimi kullanmanızı önemle tavsiye ederiz.

Kaydedilmiş Oyunlar hizmetini etkinleştirme

Kayıtlı Oyunlar hizmetini kullanabilmek için önce bu hizmete erişimi etkinleştirmeniz gerekir. Bunu yapmak için gpg::GameServices::Builder ile hizmeti oluştururken EnableSnapshots()'ü arayın. Bu işlem, bir sonraki kimlik doğrulama etkinliğinde Kayıtlı Oyunlar tarafından gereken ek kimlik doğrulama kapsamlarını etkinleştirir.

Kaydedilmiş Oyunlar'ı görüntüleme

Oyununuzda, oyuncuların kayıtlı oyunları kaydetmek veya geri yüklemek için tetikleyebileceği bir seçenek sunabilirsiniz. Oyuncular bu seçeneği belirlediğinde oyununuz, mevcut kayıt alanlarını gösteren bir ekran açmalı ve oyuncuların bu alanlardan birine kayıt yapmalarına veya bu alanlardan oyun yüklemelerine ya da yeni bir kayıtlı oyun oluşturmalarına olanak tanımalıdır. Bunu yapmak için aşağıdaki yöntemi kullanın:

  SnapshotManager::ShowSelectUIOperation(...)

Kayıtlı Oyunlar seçim kullanıcı arayüzü, oyuncuların yeni bir kayıtlı oyun oluşturmasına, mevcut kayıtlı oyunlarla ilgili ayrıntıları görüntülemesine ve önceki kayıtlı oyunları yüklemesine olanak tanır.

  SnapshotManager::SnapshotSelectUIResponse response;
  if (IsSuccess(response.status)) {
  if (response.data.Valid()) {
    LogI("Description: %s", response.data.Description().c_str());
    LogI("FileName %s", response.data.FileName().c_str());
    //Opening the snapshot data
    
  } else {
    LogI("Creating new snapshot");
    
  }
} else {
  LogI("ShowSelectUIOperation returns an error %d", response.status);
}

Aşağıdaki örnekte, varsayılan Kayıtlı Oyunlar kullanıcı arayüzünün nasıl açılacağı ve oynatıcının kullanıcı arayüzü seçiminin nasıl ele alınacağı gösterilmektedir:

  service_->Snapshots().ShowSelectUIOperation(
  ALLOW_CREATE_SNAPSHOT,
  ALLOW_DELETE_SNAPSHOT,
  MAX_SNAPSHOTS,
  SNAPSHOT_UI_TITLE,
  [this](gpg::SnapshotManager::SnapshotSelectUIResponse const & response) {
  
      }

Yukarıdaki örnekte ALLOW_CREATE_SNAPSHOT true ise ve MAX_SNAPSHOTS, kullanıcının o anda oluşturduğu gerçek anlık görüntü sayısından fazlaysa varsayılan anlık görüntü kullanıcı arayüzünde oyunculara mevcut bir oyunu seçmek yerine yeni bir oyun kaydetme düğmesi sunulur. (Gösterildiğinde düğme kullanıcı arayüzünün alt kısmındadır.) Bir oyuncu bu düğmeyi tıkladığında SnapshotSelectUIResponse yanıtı geçerlidir ancak veri içermez.

Kaydedilen oyunları açma ve okuma

Kayıtlı bir oyuna erişmek ve içeriğini okumak ya da değiştirmek için önce bu kayıtlı oyunu temsil eden SnapshotMetadata nesnesini açın. Ardından SnapshotManager::Read*() yöntemini çağırın.

Aşağıdaki örnekte, kayıtlı bir oyunun nasıl açılacağı gösterilmektedir:

  LogI("Opening file");
  service_->Snapshots()
  .Open(current_snapshot_.FileName(),
               gpg::SnapshotConflictPolicy::BASE_WINS,
        [this](gpg::SnapshotManager::OpenResponse const & response) {
           LogI("Reading file");
           gpg::SnapshotManager::ReadResponse responseRead =
           service_->Snapshots().ReadBlocking(response.data);
          
        }

Veri çakışmalarını tespit etme ve çözme

Bir SnapshotMetadata nesnesini açtığınızda Kayıtlı Oyunlar hizmeti, çakışan bir kayıtlı oyun olup olmadığını algılar. Bir oyuncunun yerel cihazında depolanan kayıtlı oyun, Google'ın sunucularında depolanan uzak sürümle senkronize olmadığında veri çakışmaları oluşabilir.

Kayıtlı bir oyunu açarken belirttiğiniz çakışma politikası, Kayıtlı Oyunlar hizmetine veri çakışmalarını otomatik olarak nasıl çözeceğini söyler. Politika aşağıdakilerden biri olabilir:

Çakışma Politikası Açıklama
SnapshotConflictPolicy::MANUAL Kayıtlı Oyunlar hizmetinin herhangi bir çözüm işlemi gerçekleştirmemesi gerektiğini belirtir. Bunun yerine oyununuz özel bir birleştirme gerçekleştirir.
SnapshotConflictPolicy::LONGEST_PLAYTIME Kaydedilmiş Oyunlar hizmetinin, en yüksek oynama süresi değerine sahip kayıtlı oyunu seçmesi gerektiğini belirtir.
SnapshotConflictPolicy::BASE_WINS Kayıtlı Oyunlar hizmetinin temel kayıtlı oyunu seçmesi gerektiğini belirtir.
SnapshotConflictPolicy::REMOTE_WINS Kayıtlı Oyunlar hizmetinin uzaktan kayıtlı oyunu seçmesi gerektiğini belirtir. Uzak sürüm, kayıtlı oyunun oyuncunun cihazlarından birinde algılanan ve temel sürümden daha yeni bir zaman damgasına sahip olan sürümüdür.

GPGSnapshotConflictPolicyManual dışında bir çakışma politikası belirttiyseniz Kayıtlı Oyunlar hizmeti, kayıtlı oyunu birleştirir ve elde edilen SnapshotManager::OpenResponse değeri aracılığıyla güncellenmiş sürümü döndürür. Oyununuz, kayıtlı oyunu açıp üzerine yazabilir ve ardından SnapshotManager::Commit(...) yöntemini çağırarak kayıtlı oyunu Google'ın sunucularına gönderebilir.

Özel bir birleştirme gerçekleştirme

Çakışma politikası olarak SnapshotConflictPolicy::MANUAL değerini belirttiyseniz oyununuz, kaydedilen oyunda başka okuma veya yazma işlemleri gerçekleştirmeden önce algılanan tüm veri çakışmalarını çözmelidir.

Bu durumda, veri çakışması algılandığında hizmet SnapshotManager::OpenResponse üzerinden aşağıdaki parametreleri döndürür:

  • Bu çakışmayı benzersiz bir şekilde tanımlamak için bir conflict_id (Kayıtlı oyunun nihai sürümünü kaydetirken bu değeri kullanırsınız);
  • Kaydedilmiş oyunun çakışan temel sürümü ve
  • Kaydedilen oyunun çakışan uzak sürümü.

Oyununuz hangi verilerin kaydedileceğine karar verdikten sonra nihai sürümü Google'ın sunucularına göndermek/çözmek için SnapshotManager::ResolveConflictBlocking() yöntemini çağırmalıdır.

    //Resolve conflict
    gpg::SnapshotManager::OpenResponse resolveResponse =
        manager.ResolveConflictBlocking(openResponse.conflict_base, metadata_change,
                                  openResponse.conflict_id);

Kaydedilmiş oyunları yazma

Kayıtlı bir oyunu yazmak için önce bu kayıtlı oyunu temsil eden SnapshotMetadata nesnesini açın, algılanan tüm veri çakışmalarını çözün ve ardından kayıtlı oyun değişikliklerinizi kaydetmek için SnapshotManager::Commit() yöntemini çağırın.

Aşağıdaki örnekte, nasıl değişiklik oluşturabileceğiniz ve kayıtlı bir oyunu nasıl kaydedebileceğiniz gösterilmektedir.

  1. Öncelikle, düzenlemek istediğimiz anlık görüntüyü açın ve temeli seçerek tüm çakışmaları çözdüğünüzden emin olun.

    service_->Snapshots().Open(
          file_name,
          gpg::SnapshotConflictPolicy::BASE_WINS,
          [this](gpg::SnapshotManager::OpenResponse const &response) {
            if (IsSuccess(response.status)) {
              // metadata : gpg::SnapshotMetadata
              metadata = response.data;
            } else {
              // Handle snapshot open error here
            }
          });
    
  2. Ardından, kapak resmi için kullanılan resim verilerini içeren bir kayıtlı oyun değişikliği oluşturun:

    gpg::SnapshotMetadataChange::Builder builder;
    gpg::SnapshotMetadataChange metadata_change =
        builder.SetDescription("CollectAllTheStar savedata")
                 .SetCoverImageFromPngData(pngData).Create();
    
  3. Son olarak, kayıtlı oyun değişikliklerini kaydedin.

    gpg::SnapshotManager::CommitResponse commitResponse =
        service_->Snapshots().CommitBlocking(metadata, metadata_change, SetupSnapshotData());
    

    data parametresi, depoladığınız tüm oyun kayıt verilerini içerir. Bu değişiklik, oynanan süre ve kaydedilen oyunun açıklaması gibi ek kaydedilen oyun meta verilerini de içerir.

Taahhüt işlemi başarıyla tamamlanırsa oyuncular, kayıtlı oyunu Kayıtlı Oyunlar seçim kullanıcı arayüzünde görebilir.