استفاده از «بررسی برنامه» برای ایمن کردن «کیت توسعه نرم‌افزار ناوبری» برای Android

بررسی برنامه Firebase با مسدود کردن ترافیکی که از منابعی غیراز برنامه‌های قانونی شما می‌آید، از تماس‌های برنامه‌تان با «پلاتفرم Google Maps» محافظت می‌کند. این کار را با درخواست ارزیابی اصالت برنامه یا دستگاه از ارائه‌دهنده گواهی مانند Play Integrity انجام می‌دهد. وقتی برنامه‌تان را با «بررسی برنامه» ادغام می‌کنید، محافظتی دربرابر درخواست‌های مخرب و غیرمجاز اضافه می‌کنید که به‌نوبه خود از صورت‌حساب شما دربرابر کسر هزینه‌های غیرمجاز محافظت می‌کند. «بررسی برنامه» همچنین گزارش اختلال هم‌زمان را در بوم‌سازگان برنامه ناوگان شما به‌طور قابل‌توجهی بهبود می‌بخشد و درنتیجه به نفع همه رانندگانی است که از برنامه شما استفاده می‌کنند. برای اطلاعات بیشتر، به گزارش اختلال مراجعه کنید.

چرا باید از App Check استفاده کرد؟

«بررسی برنامه» از دو بخش متمایز Navigation SDK for Android محافظت می‌کند: عملکرد اصلی پیمایش و گزارش اختلال.

«بررسی برنامه» کمک می‌کند درخواست‌های اصلی «کیت توسعه نرم‌افزار پیمایش برای Android» از منابع مخرب یا غیرمجاز مسدود شود. این کار با محافظت از پروژه‌تان دربرابر کلاهبرداری صورت‌حسابی و اتمام سهمیه، مستقیماً به شما سود می‌رساند.

گزارش کردن اختلال

اگر برنامه‌تان از قابلیت‌های رأی‌گیری و گزارش اختلال هم‌زمان پشتیبانی می‌کند، «بررسی برنامه» به‌شدت توصیه می‌شود. با فعال کردن App Check، مطمئن می‌شوید که دقیق‌ترین مسیرها با درنظر گرفتن همه بازخوردهای هم‌زمان به رانندگان شما ارائه می‌شود.

چرا App Check برای گزارش‌دهی مهم است:

  • معیار اعتماد بالا برای بستن مسیر: رویدادهای تأثیرگذار بر مسیر، مانند بستن جاده، می‌توانند رفتار مسیریابی را برای همه رانندگان به‌طور قابل‌توجهی تغییر دهند. برای محافظت از نقشه دربرابر خرابکاری احتمالی، هرزنامه، یا گزارش نادرست، زیرساخت تعدیل Google برای اختلالات راه‌بندان به سیگنال‌های قوی تمامیت برنامه و دستگاه متکی است.
  • نحوه اعتبارسنجی گزارش‌ها توسط App Check: گزارش‌ها و رأی‌های کاربر که از Navigation SDK for Android ارسال می‌شوند حاوی کد App Check هستند که توسط پسای Google برای اعتبارسنجی مشروعیت بازخورد استفاده می‌شود، سطح اعتماد آن را افزایش می‌دهد، و امکان ارزیابی آن را برای تأثیرگذاری بر نقشه زنده فراهم می‌کند.
  • تأثیر حذف App Check: گزارش‌های ارسال‌شده بدون یک توکن معتبر App Check تحت یک مدل با اعتماد پایین‌تر ارزیابی می‌شوند و ممکن است صرفاً به‌عنوان نشان‌های بی‌صدا پردازش شوند. این یعنی اگرچه کاربران شما همچنان می‌توانند گزارش دهند و رأی دهند، اما احتمال کمتری وجود دارد که گزارش‌های آن‌ها در نقشه قابل‌مشاهده باشد یا بر مسیرهای رانندگان دیگر تأثیر بگذارد و به اعتبارسنجی بیشتری نیاز خواهد داشت.

آیا «بررسی برنامه» برای من مناسب است؟

در بیشتر موارد، «بررسی برنامه» توصیه می‌شود؛ بااین‌حال، در سناریوهای زیر به «بررسی برنامه» نیازی نیست یا از آن پشتیبانی نمی‌شود:

  • برنامه‌های خصوصی یا آزمایشی: اگر برنامه‌تان به‌طور عمومی دردسترس نیست، به «بررسی برنامه» نیازی نیست.
  • دستگاه‌های به‌خطرافتاده: ارائه‌دهندگان گواهی توصیه‌شده از اجرای Navigation SDK for Android در دستگاه‌های غیرقابل‌اعتماد، مانند تلفن‌های روت‌شده یا جیلبریک‌شده، جلوگیری می‌کنند. برای پشتیبانی از این دستگاه‌ها، ارائه‌دهنده گواهی سفارشی را مستقر کنید.
  • دستگاه‌های Android بدون GMS: دستگاه‌های Android باید «سرویس‌های تلفن همراه Google» (GMS) را برای Play Integrity اجرا کنند. اگر قصد دارید از دستگاه‌های Android غیرGMS پشتیبانی کنید، یک ارائه‌دهنده تصدیق سفارشی را مستقر کنید.

نمای کلی مراحل پیاده‌سازی

در سطح بالا، این مراحل را برای ادغام برنامه‌تان با «بررسی برنامه» دنبال خواهید کرد:

  1. Firebase را به برنامه‌تان اضافه کنید.
  2. کتابخانه App Check را اضافه کنید و App Check را مقداردهی اولیه کنید.
  3. ارائه‌دهنده رمزه اضافه کنید. این مرحله ارائه‌دهنده تصدیق انتخابی شما را فراخوانی می‌کند تا یکپارچگی دستگاه یا برنامه را درستی‌سنجی کند.
  4. میاناهای برنامه‌سازی کاربردی Navigation و App Check را مقداردهی اولیه کنید.
  5. اشکال‌زدایی را فعال کنید. این کار درطول توسعه یا در محیط‌های ادغام مداوم (CI) مفید است.
  6. قبل‌از فعال کردن اجرا، درخواست‌های برنامه‌تان را پایش کنید. به‌این‌ترتیب، «بررسی برنامه» را بدون ایجاد اختلال برای کاربران به‌طور یکپارچه اجرا می‌کنید.

ملاحظات هنگام برنامه‌ریزی برای ادغام «بررسی برنامه»

  • سهمیه‌های ارائه‌دهنده گواهی: ارائه‌دهنده گواهی‌ای که توصیه می‌کنیم، Play Integrity، برای سطح استفاده از API استاندارد خود محدودیت تماس روزانه دارد. برای اطلاعات بیشتر درباره محدودیت‌های فراخوانی، به صفحه راه‌اندازی در اسناد توسعه‌دهنده Google Play Integrity مراجعه کنید.
  • تأخیر راه‌اندازی: در اکثر شرایط، کاربران شما درطول استفاده عادی با تأخیر مواجه نخواهند شد، زیرا کدهای App Check در دستگاه ذخیره می‌شوند. سیستم به‌طور خودکار کدهای App Check را در پس‌زمینه قبل‌از انقضا بازآوری می‌کند تا عملکرد یکپارچه حفظ شود. بااین‌حال، اگر یک کد معتبر App Check وجود نداشته باشد، کاربران برنامه شما در هنگام راه‌اندازی با کمی تأخیر مواجه خواهند شد. برای مثال، این تأخیر درطول راه‌اندازی سرد زمانی رخ می‌دهد که یک کد ذخیره‌شده در حافظه نهان منقضی شده یا وجود نداشته باشد.
  • زمان بقای (TTL) کد: زمان بقا (TTL) مدت زمانی را تعیین می‌کند که کد App Check قبل‌از نیاز به بازآوری معتبر است. می‌توانید این مدت را از ۳۰ دقیقه تا ۷ روز در کنسول Firebase پیکربندی کنید. مدت ۱ ساعت به‌عنوان خط مبنای امن توصیه می‌شود، اما کیت توسعه نرم‌افزار به‌طور خودکار تلاش می‌کند بازآوری پس‌زمینه را تقریباً در نصف مدت TTL انجام دهد. برای دستورالعمل‌های گام‌به‌گام کنسول، سند Firebase App Check را ببینید.

ادغام کردن برنامه با App Check

پیش‌نیازها و الزامات

  • برنامه‌ای که «کیت توسعه نرم‌افزار پیمایش برای Android» نسخه ۷.۹ یا جدیدتر در آن نصب شده باشد.
  • اثر انگشت گواهی SHA-256 برنامه‌تان.
  • نام بسته برنامه‌تان.
  • باید مالک برنامه در کنسول Google Cloud باشید.
  • شناسه پروژه برنامه‌تان از کنسول Google Cloud.

مرحله ۱: Firebase را به برنامه‌تان اضافه کنید

دستورالعمل‌های موجود در مستندات توسعه‌دهنده Firebase را برای افزودن Firebase به برنامه‌تان دنبال کنید. فایل google-services.json را به دایرکتوری سطح برنامه پروژه‌تان اضافه کنید.

مرحله ۲: افزودن کتابخانه App Check و مقداردهی اولیه App Check

وابستگی «بررسی برنامه» را به فایل build.gradle برنامه‌تان اضافه کنید:

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

«بررسی برنامه» را در کلاس «برنامه» یا فعالیت اصلی‌تان مقداردهی اولیه کنید:

جاوا

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(),
)

مرحله ۳: افزودن ارائه‌دهنده کد

پیاده‌سازی میانای MapsAppCheckTokenProvider را ایجاد کنید. این ارائه‌دهنده به‌صورت ناهمگام کدهای App Check را از Firebase App Check واکشی می‌کند و آن‌ها را بااستفاده از MapsAppCheckTokenCallback به پشته شبکه Navigation SDK for Android ارسال می‌کند:

جاوا

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()
            }
    }
}

مرحله ۴: مقداردهی اولیه Navigation و App Check APIs

«کیت توسعه نرم‌افزار ناوبری» برای Android را مقداردهی اولیه کنید و نمونه ارائه‌دهنده کد یکپارچه خود را بااستفاده از MapsApiSettings.setAppCheckTokenProvider() ثبت کنید:

جاوا

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())

مرحله ۵: فعال کردن اشکال‌زدایی (اختیاری)

پس‌از اعمال «بررسی برنامه» برای Navigation SDK for Android، ویژگی‌های برنامه‌تان که به Navigation SDK for Android وابسته است در شبیه‌ساز یا از محیط ادغام مداوم (CI) اجرا نخواهد شد زیرا این محیط‌ها به‌عنوان دستگاه‌های معتبر واجدشرایط نیستند. برای اجرای برنامه‌تان در این محیط‌ها درطول توسعه و آزمایش، باید نسخه ساخت اشکال‌زدایی از برنامه‌تان ایجاد کنید که به‌جای ارائه‌دهنده گواهی تولید، از ارائه‌دهنده اشکال‌زدایی App Check استفاده کند.

  1. وابستگی ارائه‌دهنده اشکال‌زدایی را به فایل build.gradle برنامه‌تان اضافه کنید:

    Groovy (build.gradle)

    dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
  2. «بررسی برنامه» را پیکربندی کنید تا از کارخانه ارائه‌کننده اشکال‌زدایی در ساخت‌های اشکال‌زدایی شما استفاده کند:

    جاوا

    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. برنامه‌تان را در شبیه‌ساز یا دستگاه اشکال‌زدایی راه‌اندازی کنید. «بررسی برنامه» یک کلید اشکال‌زدایی محلی را در خروجی logcat شما چاپ می‌کند.
  4. این کد اشکال‌زدایی را کپی و در «کنسول Firebase» ثبت کنید. برای جزئیات بیشتر، به سند ارائه‌کننده اشکال‌زدایی «بررسی برنامه Firebase» مراجعه کنید.

مرحله ۶: نظارت بر درخواست‌های برنامه و تصمیم‌گیری درباره اجرا

قبل‌از فعال کردن اجرای اجباری، درخواست‌های برنامه‌تان را پایش کنید تا مطمئن شوید که برای کاربران قانونی اختلال ایجاد نمی‌کنید.

  1. برای دیدن درصد ترافیک تأییدشده درمقابل تأییدنشده، به صفحه معیارهای «بررسی برنامه» در کنسول Firebase بروید.
  2. وقتی مطمئن شدید که اکثر ترافیک شما درستی‌سنجی شده است و کاربران قانونی به نسخه‌ای از برنامه‌تان که حاوی پیاده‌سازی App Check است به‌روزرسانی کرده‌اند، اجرای اجباری را فعال کنید.
  3. وقتی اجرا فعال باشد، «بررسی برنامه» همه ترافیک‌های بدون کد App Check معتبر را رد خواهد کرد.