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

تساعدك خدمة Play Integrity على الكمبيوتر في التحقّق من أنّ أحداث اللعبة وطلبات الخادم صادرة من نسخة حقيقية من برنامج "ألعاب 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"
    ]
  },
}

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

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

"deviceIntegrity": {
  "deviceRecognitionVerdict": ["MEETS_PC_INTEGRITY"]
}

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

MEETS_PC_INTEGRITY

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

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

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

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

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

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

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

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

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

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