Navigation SDK for Android | Google for Developers

تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

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

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

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

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

الإبلاغ عن حالات الانقطاع

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

أضِف تبعية ميزة "التحقّق من التطبيق" إلى ملف build.gradle في تطبيقك:

أنيق (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: إضافة الجهة التي تقدّم الرموز المميزة

أنشئ عملية تنفيذ لواجهة MapsAppCheckTokenProvider. تجلِب هذه الجهة بشكل غير متزامن رموز فحص التطبيقات من فحص التطبيقات من Firebase وتمرّرها إلى حزمة شبكة حزمة تطوير البرامج للتنقّل على أجهزة 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()
            }
    }
}

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

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

أضِف تبعية الجهة التي تقدّم رموز تصحيح الأخطاء إلى ملف build.gradle في تطبيقك:
أنيق (build.gradle)
```
dependencies {
    implementation 'com.google.firebase:firebase-appcheck-debug'
}
```

اضبط ميزة "التحقّق من التطبيق" لاستخدام المصنع الذي تقدّمه الجهة التي تقدّم رموز تصحيح الأخطاء في إصدارات تصحيح الأخطاء:

جافا

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

شغِّل تطبيقك على محاكي أو جهاز تصحيح أخطاء. ستطبع ميزة فحص التطبيقات رمز تصحيح أخطاء محليًا في ناتج أداة Logcat.
انسخ رمز تصحيح الأخطاء هذا وسجِّله في وحدة تحكّم Firebase. لمزيد من التفاصيل، يُرجى الاطّلاع على مستندات مقدّم خدمة تصحيح الأخطاء لميزة "فحص التطبيقات من Firebase".

الخطوة 6: تتبُّع طلبات تطبيقك وتحديد ما إذا كنت تريد فرض التحقّق

قبل تفعيل ميزة "فرض التحقّق"، تتبَّع طلبات تطبيقك للتأكّد من أنّك لن توقف وصول المستخدمين الشرعيين.

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

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

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

التنقل

الإبلاغ عن حالات الانقطاع

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

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

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

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

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

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

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

أنيق (build.gradle)

جافا

Kotlin

الخطوة 3: إضافة الجهة التي تقدّم الرموز المميزة

جافا

Kotlin

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

جافا

Kotlin

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

أنيق (build.gradle)

جافا

Kotlin

الخطوة 6: تتبُّع طلبات تطبيقك وتحديد ما إذا كنت تريد فرض التحقّق