النقل من واجهة برمجة التطبيقات SafetyNet Attestation API

إذا كنت تتحقق من الردود باستخدام خادم موثوق به، يكون نقل البيانات من SafetyNet Attestation API إلى Play Integrity API أمرًا سهلاً. يمكن أيضًا استخدام Play Integrity API كبديل لعمليات التحقّق من ترخيص التطبيق التي يتم إجراؤها مباشرةً مع تطبيق "متجر Play" من خلال AIDL، مثل تلك التي يتم إجراؤها في مكتبة التحقّق من الترخيص (LVL). ستكون معظم التغييرات المطلوبة من جانب الخادم الموثوق به، والذي يحتاج إلى قراءة وتحليل رمز الاستجابة في Play Integrity. لاحظ أنه أثناء النقل، يحتاج كل من التطبيق والخادم إلى دعم كلا واجهتي برمجة التطبيقات في وقت واحد لدعم العملاء الأقدم الذين لم يتم تحديثهم بعد.

إذا مُنح تطبيقك حدودًا أعلى للحصة في واجهة برمجة التطبيقات SafetyNet Attestation API، عليك مراجعة فئة الاستخدام المحدَّدة لواجهة برمجة التطبيقات Play Integrity API، وإرسال طلب الانتقال إلى المستوى المعنيّ إذا لزم الأمر.

يجب إجراء التغييرات التالية لإتاحة واجهة برمجة التطبيقات Play Integrity API:

عميل Android:

  • تأكَّد من أنّ الرمز يمرِّر الرقم الخاص بالتنسيق الصحيح إلى أداة إنشاء IntegrityTokenRequest:
    • String (بدلاً من صفيفة بايت)
    • آمنة مع عناوين URL
    • تم ترميزها بالشكل Base64 وغير المُغلّفة
    • 16 حرفًا كحدّ أدنى
    • 500 حرف كحدّ أقصى
  • راجع منطق إعادة المحاولة، وتأكد من أن التطبيق يعالج الأخطاء بشكل مناسب.
  • تأكَّد من أنّ بيانات الاستجابة المرسَلة إلى الخادم الموثوق تسمح بالتمييز بين استجابات واجهة برمجة التطبيقات SafetyNet Attestation API واستجابات واجهة برمجة التطبيقات Play Integrity API.

الخادم الموثوق به:

  • راجِع منطق الإنشاء غير المدرَج، وتأكَّد من أنّه يستوفي متطلبات واجهة برمجة التطبيقات Play Integrity API.
  • تأكّد من أنّ رمز الخادم يمكنه التمييز بين استجابات SafetyNet Attestation API واستجابات واجهة برمجة التطبيقات Play Integrity API. تأكد من أن التعليمات البرمجية تقوم بتحليل هذه الردود والتحقق من صحتها بشكل صحيح.
  • أضِف منطقًا للتحقّق من صحة وتحليل استجابات واجهة برمجة التطبيقات Play Integrity API.
  • بما أنّ واجهة برمجة التطبيقات Play Integrity API الجديدة توفّر تفاصيل إضافية، قد يكون من الضروري تحسين منطق اتخاذ القرار وبيانات الملاحظات والآراء التي يتم إرسالها إلى أجهزة العملاء. للمزيد من المعلومات، راجع قسم تعيين استجابة واجهة برمجة التطبيقات ضمن هذا الموضوع.

ترميز Nonce

يجب إرسال البيانات غير ذات الصلة بسياسة السلامة إلى واجهة برمجة التطبيقات Play Integrity API بتنسيق Base64 وتوافق مع عنوان URL وغير ملفوف String. ويختلف هذا التنسيق عن واجهة برمجة التطبيقات SafetyNet Attestation API التي تتطلّب استخدام byte[].

  • تعني عبارة "آمنة لعنوان URL" استخدام صيغة "عنوان URL واسم الملف الآمن" لـ Base64 (راجِع القسم 5 من RFC 4648)، حيث يتم استخدام "-" و"_" بدلاً من "+" و"/". لمزيد من المعلومات حول ترميز Base64، يمكنك الاطّلاع على RFC 4648.
  • تعني "بدون التفاف" حذف جميع نقاط نهاية الأسطر. هذا يعني أن المخرج عبارة عن خط طويل واحد.
.setNonce(Base64.encodeToString(NONCE_BYTES,
        Base64.URL_SAFE | Base64.NO_WRAP))

بالإضافة إلى ذلك، يجب التأكّد من أنّ الإصدار غير الأول يتوافق مع إرشادات واجهة برمجة التطبيقات Play Integrity API.

تعيين استجابة واجهة برمجة التطبيقات

يربط الجدول التالي حقول SafetyNet Attestation API بمكافئات واجهة برمجة التطبيقات Play Integrity API.

SafetyNet Attestation API واجهة برمجة التطبيقات Play Integrity API Notes
timestampMs requestDetails.timestampMillis
nonce requestDetails.nonce
apkPackageName appIntegrity.packageName
apkCertificateDigestSha256 appIntegrity.certificateSha256Digest تأكَّد من ضبط appRecognitionVerdict على PLAY_RECOGNIZED.
ctsProfileMatch مدمج في deviceIntegrity.deviceRecognitionVerdict
basicIntegrity مدمج في deviceIntegrity.deviceRecognitionVerdict
evaluationType مدمج في deviceIntegrity.deviceRecognitionVerdict
advice Not available
error Not available ستكون قائمة تصنيفات سلامة الجهاز فارغة.

ربط بيان سلامة الجهاز

واجهة برمجة التطبيقات للمصادقة على SafetyNet Play Integrity API
ctsProfileMatch basicIntegrity evaluationType deviceRecognitionVerdict
FALSE FALSE ما من تصنيفات
FALSE TRUE MEETS_BASIC_INTEGRITY
TRUE FALSE ما من تصنيفات
TRUE TRUE BASIC MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY
TRUE TRUE HARDWARE_BACKED MEETS_STRONG_INTEGRITY, MEETS_DEVICE_INTEGRITY, MEETS_BASIC_INTEGRITY

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

منطق إعادة المحاولة في واجهة برمجة التطبيقات Play Integrity API

يجب أن يعيد التطبيق محاولة طلب بيانات من واجهة برمجة التطبيقات في حال ظهور رموز خطأ معيّنة. تأكد من مراجعة جميع رموز الأخطاء، وتأكد من إعادة محاولة التطبيق عند الضرورة باستخدام خوارزمية الرقود الأسي. يُرجى التأكّد من أنّ الحدّ الأدنى لمدة التأخير يبلغ 5 ثوانٍ على الأقل، مع زيادتها بشكل كبير (5 ثوانٍ و10 ثوانٍ و20 ثانية و40 ثانية وما إلى ذلك)، وذلك لتوفير وقت كافٍ لواجهة برمجة التطبيقات لتقييم سلامة الجهاز والتطبيقات.

الاستبدال الاختياري لواجهة برمجة التطبيقات لترخيص التطبيق

إذا كنت تستخدم App Licensing API، يمكنك اختياريًا نقل البيانات لاستخدام Play Integrity API، لأنّ الرمز المميّز لواجهة برمجة التطبيقات Play Integrity API يتضمّن معلومات الترخيص الخاصة بالتطبيق. وكما هي الحال بالنسبة إلى نقل واجهة برمجة التطبيقات SafetyNet Attestation API، من المفترض أن يحتفظ عدد من الأجهزة بإصدار أقدم من التطبيق. يجب أن يكون الخادم الموثوق به قادرًا على معالجة كل من واجهة برمجة التطبيقات App Licensing API واستجابات واجهة برمجة التطبيقات Play Integrity API.

تلقّي الردود حتى إيقاف الميزة بالكامل

في حال عدم نقل بياناتك إلى واجهة برمجة التطبيقات Play Integrity API أو إزالة SafetyNet إقرار بحلول الموعد النهائي لنقل البيانات (31 كانون الثاني/يناير 2024)، يمكنك إكمال هذا النموذج لطلب تمديد الموعد النهائي. في حال الموافقة على تمديد المهلة الزمنية، سيستمر تطبيقك في تلقّي ردود من SafetyNet Attestation حتى الموعد النهائي لإيقاف الخدمة بالكامل (31 كانون الثاني/يناير 2025).