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

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

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

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

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

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

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

الخطوة 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 Integrity (وهي استجابة 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 على الكمبيوتر وتعذّر إكمال الطلب، ستتلقّى لعبتك رمز خطأ. يمكن أن تحدث هذه الأخطاء لأسباب مختلفة، مثل المشاكل البيئية مثل ضعف الاتصال بالشبكة أو المشاكل في عملية تكامل واجهة برمجة التطبيقات أو النشاط الضار والهجمات النشطة.

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

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

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

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

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

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

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

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

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

   	اجتياز بيان ترخيص	عدم اجتياز بيان ترخيص	تعذُّر تقييم بيان ترخيص
   اجتياز بيان سلامة الجهاز	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. سيتم إشعارك بعد معالجة الطلب وإضافة المستخدمين الذين سيجرون الاختبار إلى القائمة المسموح بها لتلقّي بيانات السلامة المحدّدة مسبقًا للاختبار.