استخدام ميزة "فحص التطبيقات" لتأمين حزمة تطوير البرامج (SDK) للتنقّل على أجهزة Android

توفّر ميزة فحص التطبيقات من Firebase الحماية للطلبات الواردة من تطبيقك إلى "منصة خرائط Google" من خلال حظر الزيارات الواردة من مصادر أخرى غير تطبيقاتك الشرعية. ويتم ذلك من خلال طلب تقييم موثوقية التطبيق أو الجهاز من مقدّم خدمة المصادقة، مثل Play Integrity. عند دمج تطبيقك مع ميزة "فحص التطبيقات"، تتم إضافة حماية ضد الطلبات الضارة وغير المصرّح بها، ما يحمي بدوره الفوترة من الرسوم غير المصرّح بها. تعمل ميزة "فحص التطبيقات" أيضًا على تحسين الإبلاغ عن الأعطال في الوقت الفعلي بشكل كبير في منظومة تطبيقات أسطولك المتكاملة، ما يفيد جميع السائقين الذين يستخدمون تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على الإبلاغ عن الأعطال.

ملاحظة مهمة: لا تحظر ميزة "فحص التطبيقات" الزيارات غير المصرّح بها تلقائيًا. يجب تفعيل إجراء التنفيذ يدويًا بعد التحقّق من مقاييس تطبيقك (راجِع الخطوة 6: تتبُّع طلبات تطبيقك واتّخاذ قرار بشأن إجراء التنفيذ).

ما أهمية استخدام ميزة "فحص التطبيقات"؟

تحمي ميزة "فحص التطبيقات" منطقتَين مختلفتَين في حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لنظام التشغيل Android: وظيفة التنقّل الرئيسية والإبلاغ عن الانقطاعات.

التنقل

تساعد ميزة "فحص التطبيقات" في حظر طلبات "حزمة تطوير البرامج للتنقّل على أجهزة Android" الرئيسية الواردة من مصادر ضارة أو غير مصرّح بها. ويعود ذلك عليك بالفائدة مباشرةً من خلال حماية مشروعك من الاحتيال عبر الفوترة واستنفاد الحصة.

الإبلاغ عن انقطاع الخدمة

ننصح بشدة باستخدام ميزة "فحص التطبيقات" إذا كان تطبيقك يتيح إمكانية الإبلاغ عن الانقطاعات في الوقت الفعلي والتصويت. يضمن تفعيل ميزة "التحقّق من التطبيق" تزويد السائقين بالمسارات الأكثر دقة مع مراعاة جميع الملاحظات في الوقت الفعلي.

أهمية ميزة "فحص التطبيقات" لإعداد التقارير:

• المستوى العالي من الثقة في حالات إغلاق الطرق: يمكن أن تؤدي الأحداث التي تؤثر في المسارات، مثل إغلاق الطرق، إلى تغيير سلوك التوجيه بشكل كبير لجميع السائقين. لحماية الخريطة من أي تخريب أو محتوى غير مرغوب فيه أو إبلاغ غير دقيق، تعتمد البنية الأساسية للإشراف في Google على إشارات قوية لسلامة الأجهزة والتطبيقات في ما يتعلّق بعمليات إغلاق الطرق.
• كيفية تحقّق ميزة "فحص التطبيقات" من صحة البلاغات: تتضمّن بلاغات المستخدمين وعمليات التصويت المُرسَلة من حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لنظام التشغيل Android رمز ميزة "فحص التطبيقات" المميّز، والذي تستخدمه Google في الخلفية للتحقّق من صحة الملاحظات، ما يرفع مستوى الثقة فيها ويسمح بتقييمها لمعرفة تأثيرها في خريطة لحركة المرور المباشرة.
• تأثير عدم استخدام ميزة "فحص التطبيقات": يتم تقييم البلاغات المُرسَلة بدون رمز مميّز صالح لميزة "فحص التطبيقات" وفقًا لنموذج ثقة أقل، وقد تتم معالجتها كإشارات صامتة فقط. هذا يعني أنّه على الرغم من أنّه لا يزال بإمكان المستخدمين الإبلاغ والتصويت، من غير المرجّح أن تظهر بلاغاتهم على الخريطة أو تؤثّر في مسارات السائقين الآخرين، وستتطلّب عملية تحقّق إضافية.

هل ميزة "فحص التطبيقات" مناسبة لي؟

ننصح باستخدام ميزة "فحص التطبيقات" في معظم الحالات، ولكنّها غير مطلوبة أو غير متاحة في الحالات التالية:

• التطبيقات الخاصة أو التجريبية: إذا لم يكن تطبيقك متاحًا للجميع، لن تحتاج إلى ميزة "فحص التطبيقات".
• الأجهزة المخترَقة: يمنع مقدّمو خدمات المصادقة المقترَحون تشغيل حزمة تطوير البرامج (SDK) الخاصة بالتنقّل لنظام التشغيل Android على الأجهزة غير الموثوق بها، مثل الهواتف التي تم الوصول إلى جذرها أو التي تمت إزالة جميع القيود عنها. ولدعم هذه الأجهزة، يمكنك نشر مقدّم خدمة مصادقة مخصّص.
• أجهزة Android التي لا تتضمّن "خدمات Google للأجهزة الجوّالة": يجب أن تعمل أجهزة Android التي تستخدم واجهة برمجة التطبيقات Play Integrity API من خلال "خدمات Google للأجهزة الجوّالة". إذا كنت تخطط لإتاحة أجهزة Android التي لا تتضمّن "خدمات Google للأجهزة الجوّالة"، يمكنك نشر موفّر شهادة مخصّص.

نظرة عامة على خطوات التنفيذ

بشكل عام، عليك اتّباع الخطوات التالية لدمج تطبيقك مع ميزة "فحص التطبيقات":

1. أضِف Firebase إلى تطبيقك.
2. أضِف مكتبة فحص التطبيقات وابدأ تشغيل الميزة.
3. أضِف مقدّم رموز مميزة. تستدعي هذه الخطوة مقدّم خدمة المصادقة الذي تختاره للتحقّق من سلامة الجهاز أو التطبيق.
4. ابدأ بإعداد واجهتَي Navigation API وApp Check API.
5. فعِّل تصحيح الأخطاء. ويُعدّ ذلك مفيدًا أثناء عملية التطوير أو في بيئات التكامل المستمر (CI).
6. راقِب طلبات تطبيقك قبل تفعيل إجراءات التنفيذ. بهذه الطريقة، يمكنك فرض ميزة "فحص التطبيقات" بسلاسة بدون إزعاج المستخدمين.

الاعتبارات الواجب مراعاتها عند التخطيط لدمج ميزة "فحص التطبيقات"

• حصص مزوّد خدمة المصادقة: يفرض مزوّد خدمة المصادقة الذي ننصح به، وهو Play Integrity، حدًا أقصى يوميًا لعدد الطلبات في فئة استخدام Standard API. لمزيد من المعلومات حول حدود الطلبات، يُرجى الاطّلاع على صفحة الإعداد في مستندات المطوّرين حول Google Play Integrity.
• وقت الاستجابة عند بدء التشغيل: في معظم الحالات، لن يواجه المستخدمون وقت استجابة أثناء الاستخدام العادي، لأنّ رموز فحص التطبيقات المميّزة يتم تخزينها مؤقتًا على الجهاز. يُعيد النظام تلقائيًا تحميل رموز ميزة "فحص التطبيقات" في الخلفية قبل انتهاء صلاحيتها للحفاظ على سلاسة الأداء. ومع ذلك، إذا لم يتوفّر رمز مميّز صالح لميزة "فحص التطبيقات"، سيواجه مستخدمو تطبيقك بعض التأخير عند بدء التشغيل. على سبيل المثال، يحدث وقت الاستجابة هذا أثناء عمليات التشغيل الباردة عندما تنتهي صلاحية رمز مميّز مخزّن مؤقتًا أو عندما يكون مفقودًا.
• مدة صلاحية الرمز المميّز: تحدّد مدة الصلاحية (TTL) مقدار الوقت الذي يكون فيه رمز "فحص التطبيقات" صالحًا قبل الحاجة إلى إعادة تحميله. يمكنك ضبط هذه المدة من 30 دقيقة إلى 7 أيام في وحدة تحكُّم Firebase. ننصح بضبط المدة على ساعة واحدة كحد أدنى آمن، ولكن تحاول حزمة تطوير البرامج (SDK) تلقائيًا إعادة تحميل الرمز في الخلفية بعد مرور نصف مدة TTL تقريبًا. للحصول على تعليمات مفصّلة حول وحدة التحكّم، يُرجى الاطّلاع على مستندات ميزة "فحص التطبيقات من Firebase".

دمج تطبيقك مع ميزة "فحص التطبيقات"

المتطلبات الأساسية والمتطلبات

• تطبيق مثبَّت عليه الإصدار 7.9 أو إصدار أحدث من حزمة تطوير البرامج Navigation SDK لنظام التشغيل Android
• الملف المرجعي لشهادة SHA-256 الخاصة بتطبيقك
• اسم حزمة تطبيقك
• يجب أن تكون مالك التطبيق في Google Cloud Console.
• رقم تعريف مشروع تطبيقك من Google Cloud Console

الخطوة 1: إضافة Firebase إلى تطبيقك

اتّبِع التعليمات الواردة في مستندات مطوّري Firebase لإضافة Firebase إلى تطبيقك، ثم أضِف ملف google-services.json إلى دليل مستوى التطبيق في مشروعك.

الخطوة 2: إضافة مكتبة فحص التطبيقات وإعداد فحص التطبيقات

أضِف تبعية فحص التطبيقات إلى ملف 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(),
)

الخطوة 3: إضافة موفِّر الرمز المميّز

ملاحظة: إذا كان تطبيقك يستخدم أيضًا حِزم تطوير برامج أخرى من "منصة خرائط Google" تتوافق مع ميزة "فحص التطبيقات" (مثل حزمة تطوير البرامج بالاستناد إلى الموقع الجغرافي)، يمكنك استخدام إعدادات ميزة "فحص التطبيقات من Firebase" نفسها، ولكن عليك تنفيذ واجهة موفِّر الرموز المميّزة الخاصة بكل حزمة تطوير برامج وتسجيلها.

أنشِئ تنفيذًا لواجهة MapsAppCheckTokenProvider. يسترجع هذا الموفّر رموز "فحص التطبيقات" بشكل غير متزامن من ميزة "فحص التطبيقات من Firebase" ويمرّرها إلى حزمة الشبكات في حزمة تطوير البرامج بالاستناد إلى "SDK التنقّل" لنظام التشغيل Android باستخدام MapsAppCheckTokenCallback:

جافا

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: إعداد واجهتَي برمجة التطبيقات Navigation API وApp Check API

ابدأ حزمة تطوير البرامج للتنقّل على أجهزة 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())

الخطوة 5: تفعيل تصحيح الأخطاء (اختياري)

بعد فرض ميزة "فحص التطبيقات" في حزمة Navigation SDK لنظام التشغيل Android، لن تعمل ميزات تطبيقك التي تعتمد على حزمة Navigation SDK لنظام التشغيل Android في محاكي أو من بيئة دمج مستمر (CI) لأنّ هذه البيئات لا تُعدّ أجهزة صالحة. لتشغيل تطبيقك في هذه البيئات أثناء التطوير والاختبار، عليك إنشاء إصدار مخصص لتصحيح الأخطاء من تطبيقك يستخدم مقدّم خدمة تصحيح الأخطاء في ميزة "فحص التطبيقات" بدلاً من مقدّم خدمة المصادقة في الإصدار العلني.

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".

الخطوة 6: مراقبة طلبات تطبيقك واتّخاذ قرار بشأن إجراءات التنفيذ

ملاحظة: لا يُشترط تفعيل إجراء التنفيذ للاستفادة من ميزة "التحقّق من سلامة الجهاز" في تقارير الانقطاع في الوقت الفعلي، ولكن الحماية الكاملة من الاحتيال عبر الفوترة والانتحال وإساءة استخدام الحصة تعتمد على تفعيل إجراء التنفيذ على مستوى المشروع.

قبل تفعيل إجراء التنفيذ، راقِب طلبات تطبيقك للتأكّد من عدم حظر المستخدمين الشرعيين.

1. انتقِل إلى شاشة مقاييس "فحص التطبيقات" في وحدة تحكُّم Firebase للاطّلاع على النسبة المئوية للزيارات التي تم التحقّق منها مقارنةً بالزيارات التي لم يتم التحقّق منها.
2. بعد التأكّد من أنّ معظم الزيارات تم التحقّق منها وأنّ المستخدمين الشرعيين قد حدّثوا تطبيقك إلى إصدار يتضمّن ميزة "فحص التطبيقات"، فعِّل إجراء التنفيذ.
3. بعد تفعيل فحص التطبيقات، سيرفض فحص التطبيقات جميع الزيارات التي لا تتضمّن رمزًا مميزًا صالحًا من فحص التطبيقات.