Play Integrity API'yi ekleme

PC için Play Integrity API, etkileşimlerin ve sunucu isteklerinin orijinal bir PC cihazdan gelip gelmediğini kontrol etmenizi sağlar. Uygulamanızın arka uç sunucusu, riskli ve sahte olabilecek etkileşimleri tespit ederek saldırıları önlemek ve kötüye kullanımı azaltmak için uygun işlemleri gerçekleştirerek yanıt verebilir.

API, aşağıdakiler de dahil olmak üzere olası tehditleri tespit etmenize yardımcı olan kararlar döndürür:

• Riskli cihazlar ve ortamlar: deviceIntegrity değerlendirmesi, uygulamanızın çalıştığı cihazın orijinal bir PC cihazı mı yoksa PC için Google Play Games'in orijinal bir örneği mi olduğunu belirlemenize yardımcı olur.

API ile entegrasyon

PC için Play Integrity API'yi uygulamanıza entegre etmek istiyorsanız önce Google Cloud Console'da ilk kurulumu yapmanız gerekir. Ardından, her bir bütünlük kontrolü için aşağıdaki adımları uygulamanız gerekir:

1. Bütünlük jetonunuzu hazırlama
2. Bütünlük jetonunuzu isteme
3. Jeton verilerini isteme

Google Cloud Console'da İlk Kurulum

Play Integrity API'yi çağıran her uygulama veya SDK, çağrılarını doğrulamak ve API kullanımını izlemek için bir Google Cloud projesi kullanmalıdır. Yeni bir Cloud projesi oluşturmak istiyorsanız veya uygulamanız yalnızca Google Play dışında dağıtılıyorsa Play Integrity API yanıtlarını Google Cloud Console'dan etkinleştirebilirsiniz.

Google Cloud Console'unuzda yeni bir Cloud projesi oluşturun veya PC için Play Integrity API ile kullanmak istediğiniz mevcut bir Cloud projesini seçin. API'ler ve hizmetler'e gidin. API'leri ve hizmetleri etkinleştir'i seçin. Play Integrity API'yi arayıp etkinleştirin. Artık Play Integrity API'yi uygulamanıza entegre edebilirsiniz.

1. adım: Bütünlük jetonunuzu hazırlayın

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

Bütünlük jetonu istemeden önce (bkz. RequestIntegrityToken) Play Integrity API'yi hazırlamanız (veya "ısıtmanız") gerekir. Bu sayede Google Play, bütünlük kararı isteğinde bulunduğunuzda kritik yoldaki gecikmeyi azaltmak için cihazda kısmi onay bilgilerini akıllıca önbelleğe alabilir.

İşlem başarılı olduğunda devam işlemi, bir bütünlük kodu istemek için kullanılması gereken bir RequestTokenData içeren bir PrepareIntegrityTokenResultValue ile çağrılır. Bu veriler bellekte önbelleğe alınmalı ve RequestIntegrityToken çağrıları için uygulamanın oturumu süresince yeniden kullanılmalıdır. Yalnızca uygulamanız bütünlük değerlendirmesinin tamamen yeniden değerlendirilmesinin gerekli olduğuna karar verirse PrepareIntegrityToken çağrısı yapılmalıdır.

2. adım: Bütünlük jetonunuzu isteyin

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

Bütünlük jetonları, uygulamanızın cihazda oynama yapılmadığını doğrulamasını sağlayan bir mekanizmadır. Örneğin, arka uç sunucunuz bütünlük jetonunu kullanarak şunları doğrulayabilir:

• Orijinal cihaz: Uygulamanızın, PC için Google Play Games'in orijinal bir örneğini içeren ve üzerinde değişiklik yapılmamış orijinal bir cihazda çalışıp çalışmadığını belirleyin.

Uygulamanızdaki bir kullanıcı işlemini Play Integrity API for PC ile kontrol ederken izinsiz değişiklik saldırılarını azaltmak için RequestIntegrityTokenParams::request_hash alanını kullanabilirsiniz. Örneğin, bir oyun oyuncunun skorunu oyunun arka uç sunucusuna bildirmek isteyebilir ve sunucunuz bu skorun bir proxy sunucusu tarafından değiştirilmediğini doğrulamak isteyebilir. Play Integrity API, bu alanda ayarladığınız değeri imzalı bütünlük yanıtı içinde döndürür. requestHash olmadan bütünlük jetonu yalnızca cihaza bağlanır ancak belirli bir isteğe bağlanmaz. Bu da saldırı olasılığını artırır.

Bütünlük değerlendirmesi istediğinizde bu durumu azaltmak için:

• Kullanıcı işleminden veya gerçekleşen sunucu isteğinden tüm alakalı istek parametrelerinin (ör. sabit bir istek serileştirmesinin SHA256'sı) özetini hesaplayın.
• RequestIntegrityTokenParams::request_hash alanını özet olarak ayarlayın.

3. adım: Jeton verilerini isteyin

Bütünlük değerlendirmesi istedikten sonra Play Integrity API şifrelenmiş bir yanıt jetonu sağlar. Cihaz bütünlüğü kararlarını almak için Google'ın sunucularında bütünlük jetonunun şifresini çözmeniz gerekir. Bunun için aşağıdaki adımları uygulayın:

1. Uygulamanıza bağlı Google Cloud projesinde bir hizmet hesabı oluşturun.

2. Uygulamanızın sunucusunda, playintegrity kapsamını kullanarak hizmet hesabı kimlik bilgilerinizden erişim jetonunu getirin ve şu isteği gönderin:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. JSON yanıtını okuyun.

Elde edilen yük, geliştirici tarafından sağlanan bilgilerin yanı sıra bütünlük değerlendirmelerini ve ayrıntılarını içeren düz metin biçiminde bir jetondur. Jeton biçimi şu şekildedir:

{
  "requestDetails": { ... },
  "deviceIntegrity": { ... },
}

Her bütünlük değerlendirmesini kontrol etmeden önce requestDetails alanındaki değerlerin orijinal istekteki değerlerle eşleştiğinden emin olmanız gerekir. Aşağıdaki bölümlerde her alan ayrıntılı olarak açıklanmıştır.

İstek ayrıntıları alanı

requestDetails alanında istekle ilgili bilgiler yer alır. Standart istekler için requestHash alanında, klasik istekler için de nonce alanında geliştirici tarafından sağlanan bilgiler buna dahildir.

"requestDetails": {
  // Application package name this attestation was requested for.
  // Note that this field might be spoofed in the middle of the request.
  "requestPackageName": "com.package.name",
  // The timestamp when the integrity token was requested.
  "requestTime": "1675655009345"
  // Request hash provided by the developer.
  "requestHash": "aGVsbG8gd29scmQgdGhlcmU",
}

Bu değerler, orijinal isteğin değerleriyle eşleşmelidir. Bu nedenle, requestDetails ve requestHash bölümlerinin orijinal istekte gönderilenlerle eşleştiğinden emin olarak JSON yükünün requestDetails bölümünü doğrulayın.requestPackageName

Cihaz bütünlüğü alanı

deviceIntegrity alanında, bir cihazın uygulama bütünlüğünü ne kadar iyi uygulayabildiğini gösteren bir veya daha fazla etiket içeren tek bir değer ( deviceRecognitionVerdict) bulunabilir. Cihaz hiçbir etiketin ölçütlerini karşılamıyorsa deviceIntegrity alanı deviceRecognitionVerdict değerini içermez.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

Varsayılan olarak deviceRecognitionVerdict aşağıdakileri içerebilir:

MEETS_PC_INTEGRITY

Uygulama, cihaz üzerinde herhangi bir kurcalama tespit edilmeyen orijinal bir PC ortamında çalışıyorsa değerlendirme döndürür.

Boş (boş değer)

Uygulamanın çalıştığı cihazda saldırı (API kancalama gibi) veya sistem bozulması (rootlanma gibi) belirtileri var ya da uygulama fiziksel bir cihazda çalışmıyor (örneğin, Google Play bütünlük kontrollerini geçmeyen bir emülatörde çalışıyor).

Kullanım sınırları

Play Integrity API Kullanım Sınırları

Uygulamanız,uygulama başına günde maksimum 10.000 istek sınırına tabi olur. Uygulamanızın kullanıcılarından çok fazla istek geliyorsa aşağıdaki talimatları uygulayarak günlük sınırın yükseltilmesini talep edebilirsiniz.

Günlük maksimum istek sayınızı artırma

Günlük maksimum istek sayınızın artırılabilmesi için uygulamanızın diğer dağıtım kanallarının yanı sıra Google Play'de de kullanıma sunulması gerekir.

Günlük maksimum istek sayınızın artırılmasını talep etmek için aşağıdakileri yapın:

1. Play Console'da Play Integrity API için kullandığınız Google Cloud projesini bağlayın.
2. Önerilen yeniden deneme stratejisi de dahil olmak üzere API mantığını doğru şekilde uyguladığınızı doğrulayın.
3. Bu formu kullanarak kota artışı isteğinde bulunun.

Play Integrity API kotasının artırılması bir haftayı bulabilir. Bu nedenle, hizmetinizde kesinti olmaması için Google Play Console'da veya Google Cloud Console'da Play Integrity API kullanımınızı izlemenizi önemle tavsiye ederiz. Bu platformlarda kota uyarıları da ayarlayabilirsiniz.

Kota artışları, hem bütünlük jetonları oluşturmak için yapılan istemci çağrısına hem de bütünlük jetonlarının şifresini çözüp doğrulamak için yapılan sunucu çağrısına otomatik olarak uygulanır.

Güvenlikle ilgili olarak göz önünde bulundurulması gerekenler

Uygulamanızın Play Integrity API'den en iyi şekilde yararlanabilmesi için şu önerilen uygulamalara uyun:

Kötüye kullanıma karşı bir stratejiniz olmalıdır.

Play Integrity API; kötüye kullanıma karşı tek mekanizma olarak değil, genel stratejinizin bir parçası olarak diğer sinyallerle birlikte kullanıldığında en iyi performansı gösterir. Bu API'yi uygulamanız için diğer uygun güvenlik en iyi uygulamalarıyla birlikte kullanın. Uygulamanız varsayılan olarak tüm yüklemelerde günde toplam 10.000'e kadar istekte bulunabilir. Günlük maksimum sayınızı artırmayı talep edebilirsiniz.

Harekete geçmeden önce telemetri verilerini toplayın ve kitlenizi anlayın

Uygulamanızın Play Integrity API kararlarına göre davranışını değiştirmeden önce, API'yi zorunlu kılmadan uygulayarak mevcut kitlenizle ilgili durumu anlayabilirsiniz. Mevcut yükleme tabanınızın hangi kararları döndürdüğünü öğrendikten sonra planladığınız yaptırımların etkisini tahmin edebilir ve kötüye kullanım karşıtı stratejinizi buna göre ayarlayabilirsiniz.

Uygun bir anda bütünlük değerlendirmesi isteğinde bulunma

API isteklerini, savunmak istediğiniz işlem veya sunucu isteği zamanına mümkün olduğunca yakın yapmanız gerekir.

API isteklerinizin kopyalanmasını zorlaştırın

API isteklerinde, kurcalamaya ve benzer saldırılara karşı koruma sağlamak için kullanılan requestHash adlı bir alan bulunur. Bu alana, uygulamanızın isteğindeki tüm alakalı değerlerin özetini eklemeniz gerekir. Uygulamanızın standart isteklerini korumak için içerik bağlamayı kullanma ile ilgili yönergeleri uygulayın.

Bütünlük kararlarını önbelleğe almaktan kaçının

Bütünlük kararlarının önbelleğe alınması, kötü niyetli bir aktörün başka bir ortamda kötüye kullanım amaçlı olarak iyi bir cihazdan alınan kararı yeniden kullandığı bir saldırı olan proxy oluşturma riskini artırır.

Sunucunuzdan uygulamanıza bir dizi yanıt gönderme

Bir dizi karar sonucunu kopyalamak, her yanıt için sunucudan uygulamaya ikili (izin ver / reddet) yanıt göndermekten daha zordur. Örneğin, İzin ver, Sınırlamalarla izin ver, CAPTCHA tamamlandıktan sonra sınırlamalarla izin ver ve Reddet gibi bir dizi ilgili yanıt kullanabilirsiniz.

İşleme alınabilir hata mesajlarını gösterme

Mümkün olduğunda, kullanıcıya faydalı hata mesajları göstererek sorunu düzeltmek için neler yapabileceklerini açıklayın.

Beklenmedik sorunlar veya kesintiler için bir planınız olmalı.

Play durum kontrol panelinde Play Integrity API'nin hizmet durumuyla ilgili bilgilerin yanı sıra aksaklıklar ve kesintiler hakkında bilgiler gösterilir. Büyük ölçekli bir Play Integrity API kesintisi gibi olası olmayan bir durumda arka uç sunucunuzun nasıl çalışmasını istediğinizi önceden planlamanız gerekir.

Hizmet şartları ve veri güvenliği

PC için Play Integrity API'ye erişerek veya bu API'yi kullanarak Play Integrity API Hizmet Şartları'nı kabul etmiş olursunuz. API'ye erişmeden önce geçerli tüm şartları ve politikaları okuyup anlayın.

Google Play'de, geliştiricilerin uygulamalarının veri toplama, paylaşma ve güvenlik yöntemlerini açıklayarak kullanıcılarınızı bilgilendirebileceği bir Veri Güvenliği bölümü bulunur. Veri formunuzu doldurmanıza yardımcı olması için Play Integrity API'nin verileri nasıl işlediğiyle ilgili bu bilgilere göz atın.