توضّح هذه الصفحة كيفية التعامل مع المشاكل المتعلّقة بنتائج التحقّق من السلامة.
بعد طلب رمز مميّز للسلامة، يمكنك عرض مربّع حوار Google Play للمستخدم. يمكنك عرض مربّع الحوار عندما تكون هناك مشكلة واحدة أو أكثر في نتيجة السلامة أو إذا حدث استثناء أثناء طلب Integrity API. بعد إغلاق مربّع الحوار، يمكنك التأكّد من حلّ المشكلة من خلال طلب رمز مميّز آخر للتحقّق من السلامة. إذا أرسلت طلبات عادية، عليك إعادة تحضير موفّر الرموز المميزة للحصول على نتيجة جديدة.
طلب ظهور مربّع حوار بشأن السلامة لحلّ مشكلة في نتيجة التحقّق
عندما يطلب العميل رمزًا مميّزًا للتحقّق من السلامة، يمكنك استخدام الطريقة المتاحة في StandardIntegrityToken
(واجهة برمجة التطبيقات العادية) وIntegrityTokenResponse
(واجهة برمجة التطبيقات الكلاسيكية): showDialog(Activity activity, int integrityDialogTypeCode)
.
توضّح الخطوات التالية كيفية استخدام واجهة برمجة التطبيقات Play Integrity API لعرض مربّع حوار مخصَّص لتصدير البيانات الناقصة باستخدام رمز مربّع الحوار GET_LICENSED
.
يتم إدراج رموز مربّعات الحوار الأخرى التي يمكن أن يطلبها تطبيقك بعد هذا القسم.
اطلب رمزًا مميزًا للسلامة من تطبيقك، وأرسِل الرمز إلى خادمك. يمكنك استخدام الطلب "العادي" أو "الكلاسيكي".
Kotlin
// Request an integrity token val tokenResponse: StandardIntegrityToken = requestIntegrityToken() // Send token to app server and get response on what to do next val yourServerResponse: YourServerResponse = sendToServer(tokenResponse.token())
Java
// Request an integrity token StandardIntegrityToken tokenResponse = requestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(tokenResponse.token());
Unity
// Request an integrity token StandardIntegrityToken tokenResponse = RequestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(tokenResponse.Token);
Unreal Engine
// Request an integrity token StandardIntegrityToken* Response = RequestIntegrityToken(); // Send token to app server and get response on what to do next YourServerResponse YourServerResponse = SendToServer(Response->Token);
مدمجة مع المحتوى
/// Request an integrity token StandardIntegrityToken* response = requestIntegrityToken(); /// Send token to app server and get response on what to do next YourServerResponse yourServerResponse = sendToServer(StandardIntegrityToken_getToken(response));
على الخادم، فكِّر تشفير رمز التكامل وتحقَّق من الحقل
appLicensingVerdict
. قد يبدو على النحو التالي:// Licensing issue { ... "accountDetails": { "appLicensingVerdict": "UNLICENSED" } }
إذا كانت الرمز المميّز يتضمّن
appLicensingVerdict: "UNLICENSED"
، عليك الردّ على عميل تطبيقك بطلب عرض مربّع حوار الترخيص:Kotlin
private fun getDialogTypeCode(integrityToken: String): Int{ // Get licensing verdict from decrypted and verified integritytoken val licensingVerdict: String = getLicensingVerdictFromDecryptedToken(integrityToken) return if (licensingVerdict == "UNLICENSED") { 1 // GET_LICENSED } else 0 }
Java
private int getDialogTypeCode(String integrityToken) { // Get licensing verdict from decrypted and verified integrityToken String licensingVerdict = getLicensingVerdictFromDecryptedToken(integrityToken); if (licensingVerdict.equals("UNLICENSED")) { return 1; // GET_LICENSED } return 0; }
Unity
private int GetDialogTypeCode(string IntegrityToken) { // Get licensing verdict from decrypted and verified integrityToken string licensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken); if (licensingVerdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
Unreal Engine
private int GetDialogTypeCode(FString IntegrityToken) { // Get licensing verdict from decrypted and verified integrityToken FString LicensingVerdict = GetLicensingVerdictFromDecryptedToken(IntegrityToken); if (LicensingVerdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
مدمجة مع المحتوى
private int getDialogTypeCode(string integrity_token) { /// Get licensing verdict from decrypted and verified integrityToken string licensing_verdict = getLicensingVerdictFromDecryptedToken(integrity_token); if (licensing_verdict == "UNLICENSED") { return 1; // GET_LICENSED } return 0; }
في تطبيقك، استدعِ الدالة
showDialog
باستخدام الرمز المطلوب الذي تم استرداده من الخادم:Kotlin
// Show dialog as indicated by the server val showDialogType: Int? = yourServerResponse.integrityDialogTypeCode() if (showDialogType != null) { // Call showDialog with type code, the dialog will be shown on top of the // provided activity and complete when the dialog is closed. val integrityDialogResponseCode: Task<Int> = tokenResponse.showDialog(activity, showDialogType) // Handle response code, call the Integrity API again to confirm that // verdicts have been resolved. }
Java
// Show dialog as indicated by the server @Nullable Integer showDialogType = yourServerResponse.integrityDialogTypeCode(); if (showDialogType != null) { // Call showDialog with type code, the dialog will be shown on top of the // provided activity and complete when the dialog is closed. Task<Integer> integrityDialogResponseCode = tokenResponse.showDialog(activity, showDialogType); // Handle response code, call the Integrity API again to confirm that // verdicts have been resolved. }
Unity
IEnumerator ShowDialogCoroutine() { int showDialogType = yourServerResponse.IntegrityDialogTypeCode(); // Call showDialog with type code, the dialog will be shown on top of the // provided activity and complete when the dialog is closed. var showDialogTask = tokenResponse.ShowDialog(showDialogType); // Wait for PlayAsyncOperation to complete. yield return showDialogTask; // Handle response code, call the Integrity API again to confirm that // verdicts have been resolved. }
Unreal Engine
// .h void MyClass::OnShowDialogCompleted( EStandardIntegrityErrorCode Error, EIntegrityDialogResponseCode Response) { // Handle response code, call the Integrity API again to confirm that // verdicts have been resolved. } // .cpp void MyClass::RequestIntegrityToken() { UStandardIntegrityToken* Response = ... int TypeCode = YourServerResponse.integrityDialogTypeCode(); // Create a delegate to bind the callback function. FShowDialogStandardOperationCompletedDelegate Delegate; // Bind the completion handler (OnShowDialogCompleted) to the delegate. Delegate.BindDynamic(this, &MyClass::OnShowDialogCompleted); // Call ShowDialog with TypeCode which completes when the dialog is closed. Response->ShowDialog(TypeCode, Delegate); }
مدمجة مع المحتوى
// Show dialog as indicated by the server int show_dialog_type = yourServerResponse.integrityDialogTypeCode(); if (show_dialog_type != 0) { /// Call showDialog with type code, the dialog will be shown on top of the /// provided activity and complete when the dialog is closed. StandardIntegrityErrorCode error_code = IntegrityTokenResponse_showDialog(response, activity, show_dialog_type); /// Proceed to polling iff error_code == STANDARD_INTEGRITY_NO_ERROR if (error_code != STANDARD_INTEGRITY_NO_ERROR) { /// Remember to call the *_destroy() functions. return; } /// Use polling to wait for the async operation to complete. /// Note, the polling shouldn't block the thread where the IntegrityManager /// is running. IntegrityDialogResponseCode* response_code; error_code = StandardIntegrityToken_getDialogResponseCode(response, response_code); if (error_code != STANDARD_INTEGRITY_NO_ERROR) { /// Remember to call the *_destroy() functions. return; } /// Handle response code, call the Integrity API again to confirm that /// verdicts have been resolved. }
يتم عرض مربّع الحوار أعلى النشاط المقدَّم. عندما يغلق المستخدم مربّع الحوار، تكتمل المهمة برمز استجابة.
(اختياري) اطلب رمزًا مميّزًا آخر لعرض أي مربّعات حوار أخرى. في حال تقديم طلبات عادية، عليك إعادة تحضير مقدّم الرموز المميزة للحصول على نتيجة جديدة.
طلب ظهور مربّع حوار "توفير السلامة" لإصلاح خطأ من جهة العميل
إذا تعذّر تنفيذ طلب Integrity API وظهر الرمز StandardIntegrityException
(واجهة برمجة التطبيقات العادية) أو IntegrityServiceException
(واجهة برمجة التطبيقات الكلاسيكية) وكان الخطأ قابلاً للتصحيح، يمكنك استخدام مربّعَي الحوار GET_INTEGRITY
أو GET_STRONG_INTEGRITY
لإصلاح الخطأ.
توضّح الخطوات التالية كيفية استخدام مربّع الحوار GET_INTEGRITY
لإصلاح خطأ يمكن إصلاحه من جهة العميل تم رصده من خلال واجهة Integrity API.
تأكَّد من إمكانية حلّ الاستثناء الذي تم إرجاعه من طلب Integrity API.
Kotlin
private fun isExceptionRemediable(exception: ExecutionException): Boolean { val cause = exception.cause if (cause is StandardIntegrityException && cause.isRemediable) { return true } return false }
Java
private boolean isExceptionRemediable(ExecutionException exception) { Throwable cause = exception.getCause(); if (cause instanceof StandardIntegrityException integrityException && integrityException.isRemediable()) { return true; } return false; }
إذا كان الاستثناء قابلاً للتصحيح، اطلب مربع الحوار
GET_INTEGRITY
باستخدام الاستثناء الذي تم عرضه. سيتم عرض مربّع الحوار فوق النشاط المقدَّم، وسيكتمل Task المعروض برمز استجابة بعد أن يغلق المستخدم مربّع الحوار.Kotlin
private fun showDialog(exception: StandardIntegrityException) { // Create a dialog request val standardIntegrityDialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(activity) .setType(IntegrityDialogTypeCode.GET_INTEGRITY) .setStandardIntegrityResponse(ExceptionDetails(exception)) .build() // Request dialog val responseCode: Task<Int> = standardIntegrityManager.showDialog(standardIntegrityDialogRequest) }
Java
private void showDialog(StandardIntegrityException exception) { // Create a dialog request StandardIntegrityDialogRequest standardIntegrityDialogRequest = StandardIntegrityDialogRequest.builder() .setActivity(this.activity) .setType(IntegrityDialogTypeCode.GET_INTEGRITY) .setStandardIntegrityResponse(new ExceptionDetails(exception)) .build(); // Request dialog Task<Integer> responseCode = standardIntegrityManager.showDialog(standardIntegrityDialogRequest); }
إذا كان رمز الاستجابة الذي تم عرضه يشير إلى نجاح العملية، من المفترض أن ينجح الطلب التالي للحصول على رمز مميز للسلامة بدون أي استثناءات. إذا أجريت طلبات عادية، عليك إعادة إعداد موفّر الرموز المميزة للحصول على نتيجة جديدة.
رموز مربّع حوار التحقّق من السلامة
GET_LICENSED (رمز النوع 1)
مشكلة متعلّقة بالقرار
مربّع الحوار هذا مناسب لحالتَين:
- الوصول غير المصرَّح به:
appLicensingVerdict: "UNLICENSED"
وهذا يعني أنّ حساب المستخدم ليس لديه إذن الوصول إلى تطبيقك، وهو ما يحدث إذا ثبَّت المستخدم التطبيق من مصدر غير معروف أو حصل عليه من متجر تطبيقات آخر غير Google Play. - تطبيق تم التلاعب به:
appRecognitionVerdict: "UNRECOGNIZED_VERSION"
وهذا يعني أنّه تم تعديل البرنامج الثنائي لتطبيقك أو أنّه ليس إصدارًا يتعرّف عليه Google Play.
المعالجة
يمكنك عرض مربّع الحوار GET_LICENSED
لكي تطلب من المستخدم الحصول على التطبيق الأصلي من Google Play. يتناول مربّع الحوار الفردي هذا كلا السيناريوهَين:
- بالنسبة إلى المستخدم غير المرخَّص، يمنحه ترخيص Play. ويتيح ذلك للمستخدم تلقّي تحديثات التطبيقات من Google Play.
- بالنسبة إلى المستخدم الذي لديه إصدار تم التلاعب به من التطبيق، يتم توجيهه إلى تثبيت الإصدار غير المعدَّل من التطبيق من Google Play.
عندما يُكمل المستخدم مربّع الحوار، تعرض عمليات التحقّق اللاحقة من السلامة الرمزين appLicensingVerdict: "LICENSED"
وappRecognitionVerdict: "PLAY_RECOGNIZED"
.
مثال على تجربة المستخدم

CLOSE_UNKNOWN_ACCESS_RISK (رمز النوع 2)
مشكلة متعلّقة بالقرار
عندما تتضمّن environmentDetails.appAccessRiskVerdict.appsDetected
"UNKNOWN_CAPTURING"
أو "UNKNOWN_CONTROLLING"
، يعني ذلك أنّ هناك تطبيقات أخرى (لم يتم تثبيتها من خلال Google Play أو تحميلها مسبقًا على قسم النظام من قِبل الشركة المصنّعة للجهاز) تعمل على الجهاز ويمكنها أخذ لقطات للشاشة أو التحكّم في الجهاز.
المعالجة
يمكنك عرض مربّع الحوار CLOSE_UNKNOWN_ACCESS_RISK
لتنبيه المستخدم إلى إغلاق جميع التطبيقات غير المعروفة التي قد تسجّل الشاشة أو تتحكّم في الجهاز.
إذا نقر المستخدم على الزر Close all
، سيتم إغلاق جميع هذه التطبيقات.
مثال على تجربة المستخدم

CLOSE_ALL_ACCESS_RISK (رمز النوع 3)
مشكلة متعلّقة بالقرار
عندما تتضمّن environmentDetails.appAccessRiskVerdict.appsDetected
أيًا من "KNOWN_CAPTURING"
أو "KNOWN_CONTROLLING"
أو "UNKNOWN_CAPTURING"
أو "UNKNOWN_CONTROLLING"
، يعني ذلك أنّ هناك تطبيقات قيد التشغيل على الجهاز يمكنها أخذ لقطات للشاشة أو التحكم في الجهاز.
المعالجة
يمكنك عرض مربّع الحوار CLOSE_ALL_ACCESS_RISK
لطلب إغلاق جميع التطبيقات التي يمكنها أخذ لقطات للشاشة أو التحكّم في الجهاز. إذا نقر المستخدم على الزر Close all
، سيتم إغلاق جميع هذه التطبيقات على الجهاز.
مثال على تجربة المستخدم

GET_INTEGRITY (رمز النوع 4)
مشكلة متعلّقة بالقرار
هذا المربع مناسب لأي من المشاكل التالية:
سلامة الجهاز ضعيفة: عندما لا يحتوي
deviceRecognitionVerdict
علىMEETS_DEVICE_INTEGRITY
، قد لا يكون الجهاز جهاز Android حقيقيًا معتمدًا من "Play للحماية". يمكن أن يحدث ذلك، على سبيل المثال، إذا كان برنامج إقلاع الجهاز مفتوحًا أو إذا كان نظام التشغيل Android الذي تم تحميله ليس صورة معتمَدة من الشركة المصنّعة.الوصول غير المصرَّح به:
appLicensingVerdict: "UNLICENSED"
يعني ذلك أنّ حساب المستخدم لا يملك إذن الوصول إلى تطبيقك، وقد يحدث ذلك إذا ثبَّت المستخدم التطبيق من مصدر غير معروف أو حصل عليه من متجر تطبيقات آخر غير Google Play.تطبيق تم التلاعب به:
appRecognitionVerdict: "UNRECOGNIZED_VERSION"
وهذا يعني أنّه تم تعديل البرنامج الثنائي لتطبيقك أو أنّه ليس إصدارًا يتعرّف عليه Google Play.استثناءات من جهة العميل: تحدث عندما يقع استثناء يمكن إصلاحه أثناء طلب بيانات من واجهة برمجة التطبيقات Integrity API. الاستثناءات القابلة للإصلاح هي استثناءات Integrity API التي تتضمّن رموز خطأ مثل
PLAY_SERVICES_VERSION_OUTDATED
وNETWORK_ERROR
وPLAY_SERVICES_NOT_FOUND
وما إلى ذلك. يمكنك استخدام طريقةexception.isRemediable()
للتحقّق مما إذا كان يمكن إصلاح الاستثناء من خلال مربّع الحوار.
المعالجة
تم تصميم مربّع الحوار GET_INTEGRITY
لتبسيط تجربة المستخدم من خلال معالجة خطوات متعددة للإصلاح ضمن مسار واحد متواصل. ويمنع ذلك المستخدم من التفاعل مع مربّعات حوار منفصلة متعددة لحل مشاكل مختلفة.
عند طلب مربّع الحوار، يرصد تلقائيًا المشاكل الحالية في نتائج التحقّق المستهدَفة ويقدّم خطوات الإصلاح المناسبة. وهذا يعني أنّ طلب حوار واحد يمكنه معالجة مشاكل متعددة في الوقت نفسه، بما في ذلك:
- سلامة الجهاز: في حال رصد مشكلة تتعلّق بسلامة الجهاز، سيوجّه مربّع الحوار المستخدم إلى كيفية تحسين حالة أمان الجهاز لاستيفاء متطلبات الحصول على حكم
MEETS_DEVICE_INTEGRITY
. - سلامة التطبيق: إذا تم رصد مشاكل مثل الوصول غير المصرّح به أو التلاعب بالتطبيق، سيوجه مربّع الحوار المستخدمين إلى تنزيل التطبيق من "متجر Play" لحلّ هذه المشاكل.
- استثناءات من جهة العميل: يتحقّق مربّع الحوار من أي مشاكل أساسية تسبّبت في حدوث استثناء في Integrity API ويحاول حلّها. على سبيل المثال، قد تطلب من المستخدم تحديث إصدار قديم من "خدمات Google Play".
مثال على تجربة المستخدم

GET_STRONG_INTEGRITY (رمز النوع 5)
مشكلة متعلّقة بالقرار
تم تصميم مربّع الحوار هذا لحلّ جميع المشاكل نفسها التي يعالجها طلب GET_INTEGRITY، مع إمكانية إضافية لحلّ المشاكل التي تمنع الجهاز من تلقّي نتيجة MEETS_STRONG_INTEGRITY
وحلّ المشاكل المتعلّقة بنتائج خدمة "Play للحماية".
المعالجة
تم تصميم GET_STRONG_INTEGRITY
لتبسيط تجربة المستخدم من خلال معالجة خطوات متعددة للإصلاح ضمن مسار واحد متواصل. يتحقّق مربّع الحوار تلقائيًا من المشاكل المتعلّقة بالسلامة التي تنطبق على العنوان، بما في ذلك:
- سلامة الجهاز: في حال رصد مشكلة تتعلّق بسلامة الجهاز، سيوجّه مربّع الحوار المستخدم إلى كيفية تحسين حالة أمان الجهاز لاستيفاء متطلبات الحصول على حكم
MEETS_STRONG_INTEGRITY
. حالة "Play للحماية": إذا كان الرمز
playProtectVerdict
يشير إلى مشكلة، سيرشد مربّع الحوار المستخدم إلى كيفية حلّها:- في حال إيقاف خدمة "Play للحماية" (
playProtectVerdict == POSSIBLE_RISK
)، سيطلب مربع الحوار من المستخدم تفعيلها وإجراء فحص لجميع التطبيقات على الجهاز. - في حال رصد تطبيقات ضارة (
playProtectVerdict == MEDIUM_RISK
أوHIGH_RISK
)، سيوجه مربّع الحوار المستخدم إلى إلغاء تثبيتها باستخدام "Google Play للحماية".
- في حال إيقاف خدمة "Play للحماية" (
سلامة التطبيق: إذا تم رصد مشاكل، مثل الوصول غير المصرَّح به أو التلاعب بالتطبيق، سيطلب مربّع الحوار من المستخدم الحصول على التطبيق من "متجر Play" لحلّ المشكلة.
استثناءات من جهة العميل: يحاول مربّع الحوار أيضًا حلّ أي مشاكل أساسية تسبّبت في حدوث استثناء في Integrity API. على سبيل المثال، قد يطلب من المستخدم تفعيل "خدمات Google Play" إذا تبيّن أنّها غير مفعّلة. الاستثناءات القابلة للإصلاح هي استثناءات Integrity API التي تتضمّن رموز خطأ مثل
PLAY_SERVICES_VERSION_OUTDATED
أوNETWORK_ERROR
أوPLAY_SERVICES_NOT_FOUND
. يمكنك استخدام الطريقةexception.isRemediable()
للتحقّق مما إذا كان يمكن إصلاح الخطأ من خلال مربّع الحوار.
مثال على تجربة المستخدم
