دمج واجهة برمجة التطبيقات Play Integrity API لأجهزة الكمبيوتر في تطبيقك

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

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

• أكمِل إعداد حزمة تطوير البرامج (SDK).
• راجِع اعتبارات الأمان في Integrity API.
• قراءة بنود خدمة Integrity API ومعلومات معالجة البيانات وفهمها
• في Google Cloud Console، أنشِئ مشروعًا على السحابة الإلكترونية أو اختَر مشروعًا حاليًا على السحابة الإلكترونية تريد استخدامه مع Play Integrity على الكمبيوتر. انتقِل إلى واجهات برمجة التطبيقات والخدمات وفعِّل واجهة Google Play Integrity API.
• إذا كنت تتوقّع إرسال أكثر من 10, 000 طلب إلى واجهة Play Integrity API على الكمبيوتر في اليوم، عليك طلب زيادة الحد الأقصى اليومي.

الخطوة 1: تحديد كيفية استخدام Play Integrity API للكمبيوتر في لعبتك

حدِّد الوقت الذي ستطلب فيه من Play Integrity for PC الحصول على بيان سلامة عن البيئة. على سبيل المثال، يمكنك طلب الحصول على نتيجة عند فتح اللعبة أو عند تسجيل دخول أحد اللاعبين أو انضمامه إلى لعبة متعدّدة اللاعبين. بعد ذلك، حدِّد طريقة التعامل مع الردود المختلفة لبيان السلامة. على سبيل المثال، يمكنك:

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

الخطوة 2: طلب رموز مميّزة للسلامة في لعبتك

إعداد Play Integrity على الكمبيوتر

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

void PrepareIntegrityToken(
  const PrepareIntegrityTokenParams & params,
  PrepareIntegrityTokenContinuation continuation
)

عند النجاح، سيتم استدعاء عملية الاستمرار باستخدام PrepareIntegrityTokenResultValue الذي يحتوي على RequestTokenData الذي يجب استخدامه لطلب رمز مميّز للسلامة. يجب تخزين هذه البيانات مؤقتًا في الذاكرة وإعادة استخدامها طوال مدة جلسة التطبيق عند إجراء طلبات إلى RequestIntegrityToken.

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

في ما يلي مقتطف من الرمز البرمجي يوضّح كيفية استدعاء الإجراء PrepareIntegrityToken:

google::play::integrity::IntegrityClient client_;

google::play::integrity::PrepareIntegrityTokenResult
IntegrityInterface::PrepareIntegrityToken(int64_t cloud_project_number) {
  google::play::integrity::PrepareIntegrityTokenParams params;
  params.cloud_project_number = cloud_project_number;

  auto promise = std::make_shared<
      std::promise<google::play::integrity::PrepareIntegrityTokenResult>>();
  client_.PrepareIntegrityToken(
      params,
      [promise](
          google::play::integrity::PrepareIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

طلب رمز مميّز للتحقّق من السلامة

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

عند التحقّق من إجراء اتّخذه مستخدم في تطبيقك باستخدام واجهة برمجة التطبيقات Play Integrity API لأجهزة الكمبيوتر، يمكنك استخدام الحقل RequestIntegrityTokenParams::request_hash للحدّ من هجمات التلاعب. على سبيل المثال، قد تريد إرسال نتيجة اللاعب إلى خادم الخلفية الخاص باللعبة، ويريد الخادم التأكّد من أنّ خادمًا وكيلاً لم يتلاعب بهذه النتيجة. يمكن أن تعرض خدمة Play Integrity على الكمبيوتر القيمة التي تحدّدها في هذا الحقل، وذلك ضمن الردّ الموقَّع الخاص بالسلامة. بدون requestHash، سيتم ربط الرمز المميز الخاص بالسلامة بالجهاز فقط، وليس بالطلب المحدّد، ما يتيح إمكانية حدوث هجوم.

void RequestIntegrityToken(
  const RequestIntegrityTokenParams & params,
  RequestIntegrityTokenContinuation continuation
)

للحدّ من إمكانية وقوع هجوم، اتّبِع الخطوات التالية عند طلب بيانات السلامة:

• احتساب ملخّص لجميع مَعلمات الطلب ذات الصلة (مثل SHA256 لسلسلة طلب ثابتة) من إجراء المستخدم أو طلب الخادم الذي يتم تنفيذه
• اضبط الحقل RequestIntegrityTokenParams::request_hash على الملخّص.

في ما يلي مقتطف من الرمز البرمجي يوضّح كيفية استدعاء الإجراء RequestIntegrityToken:

absl::StatusOr<google::play::integrity::RequestIntegrityTokenResult>
IntegrityInterface::RequestIntegrityToken(
    const google::play::integrity::PrepareIntegrityTokenResult&
        prepare_integrity_token_result,
    const std::string& request_hash) {
  // Check if the prepare_integrity_token_result is OK
  if (!prepare_integrity_token_result.ok()) {
    return absl::FailedPreconditionError(
        absl::StrCat("PrepareIntegrityTokenResult is not OK. Error code: ",
                     prepare_integrity_token_result.error_code));
  }

  google::play::integrity::RequestIntegrityTokenParams params{
      .request_token_data =
          prepare_integrity_token_result.request_token_data,
      .request_hash = request_hash};

  auto promise = std::make_shared<std::promise<
      google::play::integrity::RequestIntegrityTokenResult>>();
  client_.RequestIntegrityToken(
      params,
      [promise](google::play::integrity::RequestIntegrityTokenResult result) {
        promise->set_value(std::move(result));
      });

  return promise->get_future().get();
}

الخطوة 3: فك تشفير رموز التحقّق من السلامة والتحقّق منها على خادم الخلفية للعبتك

فك تشفير رمز مميّز للسلامة

بعد طلب بيان سلامة، تقدّم واجهة برمجة التطبيقات Play Integrity API رمزًا مميّزًا مشفّرًا للردّ. للحصول على بيانات سلامة الجهاز، عليك فك تشفير رمز السلامة المميّز على خوادم Google باتّباع الخطوات التالية:

1. أنشئ حساب خدمة ضمن مشروع Google Cloud المرتبط بتطبيقك.

2. على خادم تطبيقك، اجلب رمز الدخول من بيانات اعتماد حساب الخدمة باستخدام نطاق playintegrity، وقدِّم الطلب التالي:

   playintegrity.googleapis.com/v1/<var>PACKAGE_NAME</var>:decodePcIntegrityToken -d \
    '{ "integrity_token": "<var>INTEGRITY_TOKEN</var>" }'
   

3. اقرأ استجابة JSON.

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

{
  "requestDetails": {
    "requestPackageName": "com.your.package.name",
    "requestTime": "2025-08-29T13:10:37.285Z",
    "requestHash": "your_request_hash_string"
  },
  "deviceIntegrity": {
    "deviceRecognitionVerdict": [
      "MEETS_PC_INTEGRITY"
    ]
  },
  "accountDetails": {
    "appLicensingVerdict": "LICENSED"
  }
}

التحقّق من رمز السلامة

يحتوي الحقل requestDetails في رمز السلامة الذي تم فك تشفيره على معلومات حول الطلب، بما في ذلك المعلومات التي يقدّمها المطوّر في requestHash.

يجب أن يتطابق الحقلان requestHash وpackageName مع الحقلَين في الطلب الأصلي. لذلك، تحقَّق من الجزء requestDetails من حمولة JSON من خلال التأكّد من أنّ requestPackageName وrequestHash يتطابقان مع ما تم إرساله في الطلب الأصلي، كما هو موضّح في مقتطف الرمز التالي:

const auto& request_details = json_payload["requestDetails"];

if (request_details.value("requestPackageName", "") != <YOUR_PACKAGE_NAME>) {
  // Don't trust the verdicts.
}

// Check for the existence of the request_hash.
// If you set a request hash in the request and it's not present, you shouldn't
// trust the verdicts.
if (!request_details.contains("requestHash")) {
    // Don't trust the verdicts.
}


// The requestHash from request_details needs to match the request hash your
// app provided.
if (request_details.value("requestHash", "") != <PROVIDED_REQUEST_HASH>) {
    // Don't trust the verdicts.
}

// You can read the rest of payload's fields.

الخطوة 4: تحديد الإجراء الذي يجب اتّخاذه استنادًا إلى نتيجة التحقّق من السلامة

يمكن أن يحتوي الحقل deviceIntegrity على قيمة واحدة، وهي deviceRecognitionVerdict. يمكنك استخدام هذه القيمة لتحديد ما إذا كانت لعبتك تعمل على كمبيوتر يجتاز عمليات فحص السلامة في Play (وهو ردّ MEETS_PC_INTEGRITY). يحتوي الحقل accountDetails على قيمة واحدة، وهي appLicensingVerdict. يمكنك استخدام هذه القيمة لتحديد ما إذا كان المستخدم قد حصل على ترخيص من Play أم لا. يمكن لخادم الخلفية في لعبتك جمع هذه المعلومات واستخدامها لتحديد الإجراء الذي يجب أن تتخذه لعبتك، مثل السماح بمتابعة حدث في اللعبة أو رفض الوصول إلى الزيارات المحفوفة بالمخاطر.

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}
"accountDetails": {
  "appLicensingVerdict": "LICENSED"
}

بيانات سلامة الجهاز

يمكن أن تتضمّن deviceRecognitionVerdict القيم التالية:

MEETS_PC_INTEGRITY

يتم تشغيل اللعبة في بيئة كمبيوتر حقيقية لم يتم فيها رصد أي تلاعب على الجهاز.

فارغ (قيمة فارغة)

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

البيانات المتعلقة بتفاصيل الحساب

يمكن أن تتضمّن appLicensingVerdict القيم التالية:

LICENSED

يملك المستخدِم إذن الوصول إلى التطبيق. بمعنى آخر، ثبَّت المستخدم تطبيقك أو حدَّثه من Google Play على جهازه.

UNLICENSED

لا يملك المستخدِم إذنًا للوصول إلى التطبيق. ويحدث ذلك مثلاً في حال ثبَّت المستخدم تطبيقك من مصدر غير معروف أو لم يحصل عليه من Google Play.

UNEVALUATED

لم يتم تقييم تفاصيل الترخيص بسبب عدم استيفاء أحد المتطلّبات الضرورية. قد يحدث ذلك لعدة أسباب، بما فيها ما يلي:

• الجهاز غير موثوق بالقدر الكافي
• لا يتعرّف Google Play على إصدار التطبيق المثبّت على الجهاز
• لم يسجّل المستخدم الدخول إلى Google Play.

الخطوة 5: التعامل مع رموز الخطأ

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

رموز الخطأ التي يمكن إعادة المحاولة فيها

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

اطّلِع هنا على المزيد من الاقتراحات بشأن استراتيجيات إعادة المحاولة.

رموز الخطأ غير القابلة لإعادة المحاولة

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

اختبار ردود مختلفة من واجهة برمجة التطبيقات Play Integrity API داخل تطبيقك

يمكنك إنشاء اختبارات لتقييم طريقة تفاعل واجهة برمجة التطبيقات Play Integrity API مع تطبيقك.

1. إعداد مجموعة على Google (أو العدد الذي تريده) تتضمّن عناوين البريد الإلكتروني للمستخدمين يمكنك اختيار أحكام السلامة أو رمز الخطأ الذي يجب أن يتلقّاه هؤلاء المستخدمون في تطبيقك من خوادم Google Play. يتيح لك ذلك اختبار طريقة تفاعل تطبيقك مع جميع الردود والأخطاء المحتملة.

2. أنشئ تذكرة هنا وأبلِغنا عن مجموعة Google التي ستتلقّى الردّ المناسب من واجهة برمجة التطبيقات. يتم تخصيص كل مجموعة لتلقّي أحد الخيارات التالية:

   	بيان حالة الترخيص "تم اجتياز عملية التحقّق من الترخيص"	قرار بشأن تعذُّر الحصول على الترخيص	يتعذّر تقييم بيان حالة الترخيص
   اجتياز فحص سلامة الجهاز	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_UNLICENSED	ALLOWLIST_CONFIG_MEETS_PC_INTEGRITY_LICENSING_UNEVALUATED
   تعذُّر اجتياز فحص سلامة الجهاز	لا ينطبق	لا ينطبق	ALLOWLIST_CONFIG_NO_PC_INTEGRITY_LICENSING_UNEVALUATED

   إذا لم تستوفِ بيان سلامة الجهاز، سيتم دائمًا عرض القيمة UNEVALUATED في بيان الترخيص.

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