C++ için Play Oyun Hizmetleri

Google ile Giriş 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ıyla yeni entegre edilen oyunları Google Play'de yayınlayamayacaksınız. Bunun yerine games v2 SDK'sını kullanmanızı öneririz.
Önceki Games v1 entegrasyonlarına sahip mevcut uygulamalar birkaç yıl daha çalışmaya devam edecek olsa da Haziran 2025'ten itibaren v2'ye geçiş yapmanız önerilir.
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ılamamaktadır.

Google Play Games Hizmetleri C++ SDK'sı, Google Play Games Hizmetleri ile kullanılmak üzere bir C++ API'si sağlar ve oyunlarının mevcut bir C++ uygulamasını kullanan geliştiriciler için tasarlanmıştır.

SDK şu anda aşağıdaki hizmetleri uygulamaktadır:

  • Yetkilendirme
  • Başarılar
  • Skor tabloları
  • Etkinlikler
  • Kaydedilmiş Oyunlar
  • Yakındaki Bağlantılar (yalnızca Android)
  • Oyuncu İstatistikleri

Kavramlar

SDK'yı kullanmak için genel olarak şu adımları uygulamanız gerekir:

  1. Android için platform yapılandırması oluşturun.
  2. GameServices::Builder kullanarak GameServices nesnesi yapılandırın ve oluşturun. GameServices nesnesi otomatik olarak oturum açmayı dener ve sonucu OnAuthActionFinished() geri çağırması aracılığıyla döndürür. Geri çağırma tarafından döndürülen sonucu not edin. Otomatik oturum açma denemesi başarısız olursa kullanıcılara oturum açma olanağı tanıyan bir düğme gösterebilirsiniz.

  3. OnAuthActionFinished() sonucunu aldıktan sonra, aşağıdakiler de dahil olmak üzere Play Games Hizmetleri çağrıları yapmak için GameServices nesnesini ve alt yöneticilerini kullanabilirsiniz:

    • Oturum açma (yetkilendirme başarısız olduktan sonra): StartAuthorizationUI()
    • Başarıların kilidini açma: Achievements().Unlock()
    • Yerleşik kullanıcı arayüzünü kullanarak başarıları gösterme: Achievements().ShowAllUI()
    • Yüksek puan gönderme: Leaderboards().SubmitScore()
    • Oturumu kapat: SignOut()

  4. GameServices nesnesini kullanmayı tamamladığınızda sıfırlayın veya yok edin.

Daha ayrıntılı düzeyde:

  1. Platform yapılandırmasını başlatma: Bu, platforma özel başlatma bilgilerini içeren bir nesnedir. Android'de platform yapılandırması, Java VM'yi ve mevcut Activity işaretçisini içerir:

    // In android_main(), create a platform configuration
// and bind the object activity.
// Alternately, attach the activity in JNI_Onload().
gpg::AndroidPlatformConfiguration platform_configuration;
platform_configuration.SetActivity(state->activity->clazz);

  2. GameServices nesnesi oluşturun: Bu nesne, Google Play Games Hizmetleri işlevinin ana giriş noktasıdır. GameServices örnekleri GameServices::Builder ile oluşturulur.

    Çoğu uygulamada, belirli bir GameServices nesnesi C ortamınız devam ettiği sürece kalıcı olur. Android Activity duraklatılıp devam ettirildiğinde nesneyi yeniden başlatmanız gerekmez.

    // Creates a GameServices object that has lambda callbacks.
game_services_ = gpg::GameServices::Builder()
        .SetDefaultOnLog(gpg::LogLevel::VERBOSE)
        .SetOnAuthActionStarted([started_callback](gpg::AuthOperation op) {
            is_auth_in_progress_ = true;
            started_callback(op);
        })
        .SetOnAuthActionFinished([finished_callback](gpg::AuthOperation op,
                                                     gpg::AuthStatus status) {
            LOGI("Sign in finished with a result of %d", status);
            is_auth_in_progress_ = false;
            finished_callback(op, status);
        })
        .Create(pc);

  3. GameServices nesnenizi yönetmek için Manager sınıflarını kullanın. Yöneticilere bir GameServices örneğinden erişilir ve grupla ilgili işlevler bir araya getirilir. Başarı ve skor tablosu yöneticileri bu türlere örnek olarak verilebilir. Kullanıcı tarafından görülebilen bir durum içermezler. Yöneticiler referansla döndürülür ve kapsayan GameServices örneği, yaşam döngülerini kontrol eder. Müşteriniz hiçbir zaman bir yönetici referansı tutmamalıdır. Bunun yerine, müşteriniz GameServices örneğini saklamalıdır.

    Yöneticiler, verileri değişmez değer türü nesneleri aracılığıyla döndürür. Bu değerler, sorgunun yapıldığı andaki temel verilerin tutarlı bir görünümünü yansıtır.

    // Submit a high score
game_services_->Leaderboards().SubmitScore(leaderboard_id, score);

// Show the default Achievements UI
game_services_->Achievements().ShowAllUI();

  4. GameServices nesnesini kullanmayı bitirdiğinizde, nesneyi içeren unique_ptr üzerinde reset() işlevini çağırarak veya kapsam dışına çıktığında unique_ptr'nin nesneyi otomatik olarak yok etmesine izin vererek temizleme işlemini yapın.

İş parçacığı modeli

Aksi belirtilmedikçe tüm GameServices ve yönetici yöntemleri, iş parçacığı açısından güvenli ve eşzamansız uygulamalara sahiptir. Bu işlevler, harici kilitleme olmadan herhangi bir iş parçacığında çağrılabilir ve çağrılma sırasına uygun bir sırada yürütülür.

Erişimci yöntemler (durumu okuyanlar) iki ana varyantta gelir. İlk yöntem türü (FetchProperty() gibi adlarla) sonuçlarını eşzamansız olarak sağlanan bir geri çağırmaya iletir. İkinci tür (FetchPropertyBlocking() gibi adlarla) sonuçlarını eşzamanlı olarak çağıran işleme döndürür.

// Blocking callback
gpg::AchievementManager::FetchAllResponse fetchResponse =
        game_services_->Achievements().FetchAllBlocking(std::chrono::milliseconds(1000));

// Non-blocking callback
game_services_->Achievements().FetchAll(gpg::DataSource::CACHE_OR_NETWORK,
    [] (gpg::AchievementManager::FetchAllResponse response) {
    LogI("Achievement response status: %d", response.status);});

Tüm kullanıcı geri çağırmaları özel bir geri çağırma iş parçacığında çağrılır. Bu iş parçacığı, "ana iş parçacığı" veya "kullanıcı arayüzü iş parçacığı" gibi platform kavramlarından farklı olabilir. Ayrıca, kullanıcı geri aramalarının hızlı bir şekilde yürütülmesini sağlamaya çalışmalısınız. Durdurulan bir geri arama iş parçacığı, kullanıcı tarafından görülebilen sorunlara (örneğin, oturumu kapatma isteğinin tamamlanmasının gecikmesi) neden olabilir.

Platforma özgü bilgiler

Android'de Play Games C++ SDK'sını kullanmaya başlamak için hızlı başlangıç kılavuzuna gidin.

Daha fazla bilgi

Daha fazla bilgi için Google Play Oyun Hizmetleri C++ SDK'sında yer alan sınıf dokümanlarını okuduğunuzdan ve SDK'nın nasıl kullanılacağını gösteren örnekleri incelediğinizden emin olun.

Oyununuzda bir arka uç sunucusu kullanılıyorsa Google Play Oyun Hizmetleri'ne Sunucu Tarafı Erişimini Etkinleştirme başlıklı makaleyi inceleyin.