واجهة برمجة التطبيقات SafetyNetVerify Apps API

تتيح واجهة برمجة التطبيقات Verify Apps API من SafetyNet، وهي مكتبة تستند إلى خدمات Google Play، لتطبيقك التفاعل آليًا مع ميزة التحقّق من التطبيقات على الجهاز، ما يحمي الجهاز من التطبيقات التي يُحتمل أن تكون ضارة.

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

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

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

بنود الخدمة الإضافية

عند الوصول إلى واجهات برمجة تطبيقات SafetyNet أو استخدامها، فإنّك توافق على بنود خدمة Google APIs وعلى بنود خدمة واجهة برمجة التطبيقات Verify Apps التالية. يُرجى قراءة جميع الأحكام والسياسات السارية وفهمها قبل الوصول إلى واجهات برمجة التطبيقات.

بنود خدمة Verify Apps API

قد تؤدي تحليلات التطبيقات التي تحدد التطبيقات الضارة المحتملة إلى نتائج إيجابية وسلبية خاطئة. يتم عرض النتائج (أو عدم توفّرها) التي يتم الحصول عليها من مجموعة واجهات برمجة التطبيقات هذه بأفضل ما نفهمه. أنت تقرّ وتدرك أنّه لا يمكن ضمان دقة النتائج التي تعرضها مجموعة واجهات برمجة التطبيقات SafetyNet API في جميع الأوقات.

إضافة تبعية SafetyNet API

قبل استخدام واجهة Verify Apps API، أضِف واجهة SafetyNet API إلى مشروعك. إذا كنت تستخدم "استوديو Android"، أضِف هذه الاعتمادية إلى ملف Gradle على مستوى التطبيق. لمزيد من المعلومات، يُرجى الاطّلاع على إعداد SafetyNet API.

تفعيل ميزة "التحقّق من التطبيق"

توفّر واجهة برمجة التطبيقات Verify Apps في SafetyNet طريقتَين لتفعيل ميزة "التحقّق من التطبيقات". يمكنك تحديد ما إذا كانت ميزة "التحقّق من التطبيقات" مفعّلة باستخدام isVerifyAppsEnabled()، ويمكنك طلب تفعيلها باستخدام enableVerifyApps().

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

تحديد ما إذا كان التحقّق من التطبيقات مفعّلاً

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

يوضّح مقتطف الرمز التالي كيفية إنشاء دالة رد الاتصال المرتبطة بهذه الطريقة:

Kotlin

SafetyNet.getClient(this)
        .isVerifyAppsEnabled
        .addOnCompleteListener { task ->
            if (task.isSuccessful) {
                if (task.result.isVerifyAppsEnabled) {
                    Log.d("MY_APP_TAG", "The Verify Apps feature is enabled.")
                } else {
                    Log.d("MY_APP_TAG", "The Verify Apps feature is disabled.")
                }
            } else {
                Log.e("MY_APP_TAG", "A general error occurred.")
            }
        }

Java

SafetyNet.getClient(this)
    .isVerifyAppsEnabled()
    .addOnCompleteListener(new OnCompleteListener<VerifyAppsUserResponse>() {
        @Override
        public void onComplete(Task<VerifyAppsUserResponse> task) {
            if (task.isSuccessful()) {
                VerifyAppsUserResponse result = task.getResult();
                if (result.isVerifyAppsEnabled()) {
                    Log.d("MY_APP_TAG", "The Verify Apps feature is enabled.");
                } else {
                    Log.d("MY_APP_TAG", "The Verify Apps feature is disabled.");
                }
            } else {
                Log.e("MY_APP_TAG", "A general error occurred.");
            }
        }
    });

طلب تفعيل التحقّق من التطبيق

تتيح طريقة enableVerifyApps() غير المتزامنة لتطبيقك عرض مربّع حوار يطلب من المستخدم تفعيل ميزة "التحقّق من التطبيقات". تعرض هذه الطريقة عنصر VerifyAppsUserResponse يحتوي على معلومات بشأن جميع الإجراءات التي اتّخذها المستخدم والمتعلّقة بميزة "التحقّق من التطبيقات"، بما في ذلك ما إذا كان قد وافق على تفعيلها.

يوضّح مقتطف الرمز التالي كيفية إنشاء دالة رد الاتصال المرتبطة بهذه الطريقة:

Kotlin

SafetyNet.getClient(this)
        .enableVerifyApps()
        .addOnCompleteListener { task ->
            if (task.isSuccessful) {
                if (task.result.isVerifyAppsEnabled) {
                    Log.d("MY_APP_TAG", "The user gave consent to enable the Verify Apps feature.")
                } else {
                    Log.d(
                            "MY_APP_TAG",
                            "The user didn't give consent to enable the Verify Apps feature."
                    )
                }
            } else {
                Log.e("MY_APP_TAG", "A general error occurred.")
            }
        }

Java

SafetyNet.getClient(this)
    .enableVerifyApps()
    .addOnCompleteListener(new OnCompleteListener<VerifyAppsUserResponse>() {
        @Override
        public void onComplete(Task<VerifyAppsUserResponse> task) {
            if (task.isSuccessful()) {
                VerifyAppsUserResponse result = task.getResult();
                if (result.isVerifyAppsEnabled()) {
                    Log.d("MY_APP_TAG", "The user gave consent " +
                          "to enable the Verify Apps feature.");
                } else {
                    Log.d("MY_APP_TAG", "The user didn't give consent " +
                          "to enable the Verify Apps feature.");
                }
            } else {
                Log.e("MY_APP_TAG", "A general error occurred.");
            }
        }
    });

قد يواجه تطبيقك حالة واحدة أو أكثر من الحالات غير العادية عند استخدام هذه الطريقة:

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

عرض قائمة بالتطبيقات المثبَّتة التي قد تتسبّب بضرر

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

يوضّح مقتطف الرمز التالي كيفية إنشاء دالة رد الاتصال المرتبطة بهذه الطريقة:

Kotlin

SafetyNet.getClient(this)
        .listHarmfulApps()
        .addOnCompleteListener { task ->
            Log.d(TAG, "Received listHarmfulApps() result")

            if (task.isSuccessful) {
                val result = task.result
                val scanTimeMs = result.lastScanTimeMs

                val appList = result.harmfulAppsList
                if (appList?.isNotEmpty() == true) {
                    Log.e("MY_APP_TAG", "Potentially harmful apps are installed!")

                    for (harmfulApp in appList) {
                        Log.e("MY_APP_TAG", "Information about a harmful app:")
                        Log.e("MY_APP_TAG", "  APK: ${harmfulApp.apkPackageName}")
                        Log.e("MY_APP_TAG", "  SHA-256: ${harmfulApp.apkSha256}")

                        // Categories are defined in VerifyAppsConstants.
                        Log.e("MY_APP_TAG", "  Category: ${harmfulApp.apkCategory}")
                    }
                } else {
                    Log.d("MY_APP_TAG", "There are no known potentially harmful apps installed.")
                }
            } else {
                Log.d(
                        "MY_APP_TAG",
                        "An error occurred. Call isVerifyAppsEnabled() to ensure that the user "
                                + "has consented."
                )
            }
        }

Java

SafetyNet.getClient(this)
    .listHarmfulApps()
    .addOnCompleteListener(new OnCompleteListener<HarmfulAppsResponse>() {
        @Override
        public void onComplete(Task<HarmfulAppsResponse> task) {
            Log.d(TAG, "Received listHarmfulApps() result");

            if (task.isSuccessful()) {
                HarmfulAppsResponse result = task.getResult();
                long scanTimeMs = result.getLastScanTimeMs();

                List<HarmfulAppsData> appList = result.getHarmfulAppsList();
                if (appList.isEmpty()) {
                    Log.d("MY_APP_TAG", "There are no known " +
                          "potentially harmful apps installed.");
                } else {
                    Log.e("MY_APP_TAG",
                          "Potentially harmful apps are installed!");

                    for (HarmfulAppsData harmfulApp : appList) {
                        Log.e("MY_APP_TAG", "Information about a harmful app:");
                        Log.e("MY_APP_TAG",
                              "  APK: " + harmfulApp.apkPackageName);
                        Log.e("MY_APP_TAG",
                              "  SHA-256: " + harmfulApp.apkSha256);

                        // Categories are defined in VerifyAppsConstants.
                        Log.e("MY_APP_TAG",
                              "  Category: " + harmfulApp.apkCategory);
                    }
                }
            } else {
                Log.d("MY_APP_TAG", "An error occurred. " +
                      "Call isVerifyAppsEnabled() to ensure " +
                      "that the user has consented.");
            }
        }
    });