Android için Navigation SDK'nın güvenliğini sağlamak üzere Uygulama Kontrolü'nü kullanma

Android için Navigasyon SDK'sında App Check desteği önümüzdeki birkaç gün içinde kullanıma sunulacaktır. Bu özelliği Firebase konsolunda henüz görmüyorsanız birkaç gün içinde tekrar kontrol edin.

Firebase Uygulama Kontrolü, geçerli uygulamalarınız dışındaki kaynaklardan gelen trafiği engelleyerek uygulamanızdan Google Haritalar Platformu'na yapılan çağrıları korur. Bunu, Play Integrity gibi bir onay sağlayıcıdan uygulamanın veya cihazın gerçekliğinin değerlendirilmesini isteyerek yapar. Uygulamanızı Uygulama Kontrolü ile entegre ettiğinizde kötü amaçlı ve yetkisiz isteklere karşı koruma eklersiniz. Bu da faturalandırmanızı yetkisiz ödemelerden korur. App Check, filonuzun uygulama ekosisteminde gerçek zamanlı kesinti raporlamasını da önemli ölçüde iyileştirerek uygulamanızı kullanan tüm sürücülere fayda sağlar. Daha fazla bilgi için Kesinti raporlama başlıklı makaleyi inceleyin.

Önemli: Uygulama Kontrolü, yetkisiz trafiği varsayılan olarak engellemez. Uygulama metriklerinizi doğruladıktan sonra yaptırımı manuel olarak etkinleştirmeniz gerekir (6. adım: Uygulama isteklerinizi izleyin ve yaptırıma karar verin bölümüne bakın).

App Check'i neden kullanmalısınız?

App Check, Android için Navigation SDK'sının iki farklı alanını korur: temel navigasyon işlevi ve kesinti raporlama.

Gezinme

App Check, kötü amaçlı veya yetkisiz kaynaklardan gelen Android için Navigation SDK isteklerinin engellenmesine yardımcı olur. Bu özellik, projenizi faturalandırma sahtekarlığına ve kota tükenmesine karşı koruyarak doğrudan size fayda sağlar.

Kesinti bildirme

Uygulamanızda anlık kesinti bildirme ve oylama özellikleri destekleniyorsa Uygulama Kontrolü'nü kullanmanız önemle tavsiye edilir. Uygulama Kontrolü'nü etkinleştirdiğinizde sürücüleriniz, tüm anlık geri bildirimleri dikkate alan en doğru rotaları alır.

Raporlama açısından Uygulama Denetimi neden önemlidir?

• Kapanışlar için yüksek güven eşiği: Yol kapanışları gibi rotayı etkileyen olaylar, tüm sürücülerin yönlendirme davranışını önemli ölçüde değiştirebilir. Haritayı olası vandalizm, spam veya yanlış bildirimlerden korumak için Google'ın yol kapatma kesintileriyle ilgili moderasyon altyapısında güçlü cihaz ve uygulama bütünlüğü sinyalleri kullanılır.
• Uygulama Kontrolü, raporları nasıl doğrular? Android için Navigation SDK'dan gönderilen kullanıcı raporları ve oyları, geri bildirimin geçerliliğini doğrulamak için Google'ın arka ucu tarafından kullanılan Uygulama Kontrolü jetonunu içerir. Bu jeton, geri bildirimin güven düzeyini yükseltir ve canlı harita üzerindeki etkisinin değerlendirilmesine olanak tanır.
• App Check'in atlanmasının etkisi: Geçerli bir App Check jetonu olmadan gönderilen raporlar, daha düşük güvene sahip bir model kapsamında değerlendirilir ve yalnızca sessiz sinyaller olarak işlenebilir. Bu durumda, kullanıcılarınız bildirimde bulunup oy verebilse de bildirimlerinin haritada görünme veya diğer sürücülerin rotalarını etkileme olasılığı daha düşüktür ve ek doğrulama gerekir.

Uygulama Kontrolü benim için uygun mu?

Çoğu durumda App Check önerilir. Ancak aşağıdaki senaryolarda App Check'e gerek yoktur veya App Check desteklenmez:

• Özel veya deneysel uygulamalar: Uygulamanıza herkes erişemiyorsa Uygulama Denetimi gerekmez.
• Güvenliği ihlal edilmiş cihazlar: Önerilen onay sağlayıcılar, Android için Navigation SDK'nın rootlanmış veya jailbreak'li telefonlar gibi güvenilmeyen cihazlarda çalışmasını engeller. Bu cihazları desteklemek için özel bir onay sağlayıcı dağıtın.
• GMS olmayan Android cihazlar: Android cihazlarda Play Integrity için Google Mobil Hizmetleri (GMS) çalıştırılması gerekir. GMS olmayan Android cihazları desteklemeyi planlıyorsanız özel bir onay sağlayıcı dağıtın.

Uygulama adımlarına genel bakış

Uygulamanızı App Check ile entegre etmek için genel olarak şu adımları uygulayacaksınız:

1. Firebase'i uygulamanıza ekleyin.
2. App Check kitaplığını ekleyin ve App Check'i başlatın.
3. Jeton sağlayıcı ekleyin. Bu adımda, cihazın veya uygulamanın bütünlüğünü doğrulamak için seçtiğiniz onay sağlayıcı çağrılır.
4. Navigation ve App Check API'lerini başlatın.
5. Hata ayıklamayı etkinleştirin. Bu, geliştirme sırasında veya sürekli entegrasyon (CI) ortamlarında kullanışlıdır.
6. Yaptırımı etkinleştirmeden önce uygulama isteklerinizi izleyin. Bu şekilde, kullanıcılarınızı kesintiye uğratmadan App Check'i sorunsuz bir şekilde zorunlu kılabilirsiniz.

Uygulama Kontrolü entegrasyonu planlarken dikkat edilmesi gerekenler

• Onay Sağlayıcı Kotaları: Önerdiğimiz onay sağlayıcı Play Integrity'nin Standart API kullanım katmanı için günlük çağrı sınırı vardır. Arama sınırları hakkında daha fazla bilgi için Google Play Integrity geliştirici belgelerindeki Kurulum sayfasına bakın.
• Başlatma Gecikmesi: App Check jetonları cihazda önbelleğe alındığından, kullanıcılarınız çoğu durumda normal kullanım sırasında gecikme yaşamaz. Sistem, sorunsuz performans sağlamak için App Check jetonlarını arka planda otomatik olarak yeniler. Ancak geçerli bir Uygulama Denetimi jetonu yoksa uygulama kullanıcılarınız başlatma sırasında biraz gecikme yaşar. Örneğin, bu gecikme, önbelleğe alınmış bir jetonun süresi dolduğunda veya jeton eksik olduğunda soğuk başlatmalar sırasında meydana gelir.
• Jeton TTL'si: Geçerlilik süresi (TTL), Uygulama Kontrolü jetonunun yenilenmesi gerekmeden önce geçerli olduğu süreyi belirler. Bu süreyi Firebase konsolunda 30 dakika ile 7 gün arasında yapılandırabilirsiniz. Güvenli bir temel olarak 1 saatlik süre önerilir ancak SDK, TTL süresinin yaklaşık yarısında otomatik olarak arka plan yenileme denemeleri yapar. Konsol talimatları için Firebase Uygulama Kontrolü belgelerine bakın.

Uygulamanızı App Check ile entegre etme

Ön koşullar ve gereksinimler

• Android için Navigasyon SDK'sının 7.9 veya sonraki sürümlerinin yüklü olduğu bir uygulama.
• Uygulamanızın SHA-256 sertifika parmak izi.
• Uygulamanızın paket adı.
• Google Cloud Console'da uygulamanın sahibi olmanız gerekir.
• Uygulamanızın Google Cloud Console'daki proje kimliği.

1. adım: Firebase'i uygulamanıza ekleyin

Firebase'i uygulamanıza eklemek için Firebase geliştirici dokümanlarındaki talimatları uygulayın. google-services.json dosyanızı projenizin uygulama düzeyindeki dizinine ekleyin.

2. adım: App Check kitaplığını ekleyin ve App Check'i başlatın

App Check bağımlılığını uygulamanızın build.gradle dosyasına ekleyin:

Groovy (build.gradle)

dependencies {
    // Import the Firebase BoM
    implementation platform('com.google.firebase:firebase-bom:34.17.0')
    // Add the dependency for the App Check library with Play Integrity
    implementation 'com.google.firebase:firebase-appcheck-playintegrity'
}

Uygulama sınıfınızda veya ana etkinliğinizde App Check'i başlatın:

Java

import com.google.firebase.FirebaseApp;
import com.google.firebase.appcheck.FirebaseAppCheck;
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;

// Initialize Firebase App
FirebaseApp.initializeApp(/* context= */ this);

// Initialize App Check
FirebaseAppCheck firebaseAppCheck = FirebaseAppCheck.getInstance();
firebaseAppCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance());

Kotlin

import com.google.firebase.Firebase
import com.google.firebase.appcheck.appCheck
import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
import com.google.firebase.initialize

// Initialize Firebase App
Firebase.initialize(context = this)

// Initialize App Check
Firebase.appCheck.installAppCheckProviderFactory(
    PlayIntegrityAppCheckProviderFactory.getInstance(),
)

3. adım: Jeton sağlayıcıyı ekleyin

Not: Uygulamanız, Uygulama Kontrolü'nü destekleyen diğer Google Haritalar Platformu SDK'larını (ör. Yerler SDK'sı) da kullanıyorsa aynı Firebase Uygulama Kontrolü yapılandırmasını kullanabilirsiniz ancak her SDK'ya özgü jeton sağlayıcı arayüzünü uygulayıp kaydetmeniz gerekir.

MapsAppCheckTokenProvider arayüzünün bir uygulamasını oluşturun. Bu sağlayıcı, Firebase Uygulama Kontrolü'nden Uygulama Kontrolü jetonlarını eşzamansız olarak getirir ve MapsAppCheckTokenCallback kullanarak Android ağ yığını için Navigation SDK'ya iletir:

Java

import com.google.android.gms.maps.MapsAppCheckTokenCallback;
import com.google.android.gms.maps.MapsAppCheckTokenProvider;
import com.google.firebase.appcheck.FirebaseAppCheck;

public class NavigationTokenProvider implements MapsAppCheckTokenProvider {
  @Override
  public void fetchToken(MapsAppCheckTokenCallback callback) {
    FirebaseAppCheck.getInstance()
        .getAppCheckToken(false) // forcingRefresh = false
        .addOnSuccessListener(
            tokenResult -> {
              String token = tokenResult.getToken();
              callback.onSuccess(token);
            })
        .addOnFailureListener(
            e -> {
              callback.onFailure();
            });
  }
}

Kotlin

import com.google.android.gms.maps.MapsAppCheckTokenCallback
import com.google.android.gms.maps.MapsAppCheckTokenProvider
import com.google.firebase.appcheck.FirebaseAppCheck

class NavigationTokenProvider : MapsAppCheckTokenProvider {
    override fun fetchToken(callback: MapsAppCheckTokenCallback) {
        FirebaseAppCheck.getInstance()
            .getAppCheckToken(false)
            .addOnSuccessListener { tokenResult ->
                callback.onSuccess(tokenResult.token)
            }
            .addOnFailureListener {
                callback.onFailure()
            }
    }
}

4. adım: Navigation ve App Check API'lerini başlatın

MapsApiSettings.setAppCheckTokenProvider() kullanarak Android için Navigation SDK'sını başlatın ve birleştirilmiş jeton sağlayıcı örneğinizi kaydedin:

Java

import com.google.android.gms.maps.MapsApiSettings;

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, new NavigationTokenProvider());

Kotlin

import com.google.android.gms.maps.MapsApiSettings

// Register your App Check token provider before initializing Navigation SDK for Android
MapsApiSettings.setAppCheckTokenProvider(context, NavigationTokenProvider())

5. adım: Hata ayıklamayı etkinleştirin (isteğe bağlı)

Android için Navigasyon SDK'sında Uygulama Kontrolü zorunlu kılındıktan sonra, Android için Navigasyon SDK'sına bağlı olan uygulama özellikleriniz simülatörde veya sürekli entegrasyon (CI) ortamında çalışmaz. Bunun nedeni, bu ortamların geçerli cihaz olarak kabul edilmemesidir. Geliştirme ve test sırasında uygulamanızı bu ortamlarda çalıştırmak için uygulamanızın, üretim onay sağlayıcısı yerine Uygulama Kontrolü hata ayıklama sağlayıcısını kullanan bir hata ayıklama derlemesini oluşturmanız gerekir.

1. Hata ayıklama sağlayıcı bağımlılığını uygulamanızın build.gradle dosyasına ekleyin:

   Groovy (build.gradle)

   dependencies {
       implementation 'com.google.firebase:firebase-appcheck-debug'
   }

2. Hata ayıklama derlemelerinizde hata ayıklama sağlayıcı fabrikasını kullanmak için App Check'i yapılandırın:

   Java

   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory;
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory;
   
   if (BuildConfig.DEBUG) {
       firebaseAppCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance()
       );
   } else {
       firebaseAppCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance()
       );
   }

   Kotlin

   import com.google.firebase.Firebase
   import com.google.firebase.appcheck.appCheck
   import com.google.firebase.appcheck.debug.DebugAppCheckProviderFactory
   import com.google.firebase.appcheck.playintegrity.PlayIntegrityAppCheckProviderFactory
   
   if (BuildConfig.DEBUG) {
       Firebase.appCheck.installAppCheckProviderFactory(
           DebugAppCheckProviderFactory.getInstance(),
       )
   } else {
       Firebase.appCheck.installAppCheckProviderFactory(
           PlayIntegrityAppCheckProviderFactory.getInstance(),
       )
   }

3. Uygulamanızı bir emülatörde veya hata ayıklama cihazında başlatın. App Check, logcat çıktınıza yerel bir hata ayıklama jetonu yazdırır.
4. Bu hata ayıklama jetonunu kopyalayıp Firebase konsoluna kaydedin. Daha fazla bilgi için Firebase Uygulama Kontrolü hata ayıklama sağlayıcısı dokümanlarına bakın.

6. adım: Uygulama isteklerinizi izleyin ve yaptırım konusunda karar verin

Not: Cihaz bütünlüğü doğrulamasından yararlanmak için gerçek zamanlı kesinti raporlarında yaptırım kesinlikle gerekli değildir. Ancak faturalandırma sahtekarlığı, kimlik sahtekarlığı ve kota kötüye kullanımı gibi durumlara karşı tam koruma sağlamak için proje düzeyinde yaptırımın etkinleştirilmesi gerekir.

Yaptırımı etkinleştirmeden önce, meşru kullanıcıların hizmetten yararlanmasını engellemeyeceğinizden emin olmak için uygulama isteklerinizi izleyin.

1. Doğrulanmış ve doğrulanmamış trafiğin yüzdesini görmek için Firebase konsolundaki Uygulama Kontrolü metrikleri ekranını ziyaret edin.
2. Trafiğinizin büyük bir kısmının doğrulanmış olduğundan ve meşru kullanıcıların, App Check uygulamanızı içeren bir uygulama sürümüne güncellediğinden emin olduğunuzda zorunlu kılmayı etkinleştirin.
3. Zorunlu kılma etkinleştirildikten sonra Uygulama Kontrolü, geçerli bir Uygulama Kontrolü jetonu içermeyen tüm trafiği reddeder.