إحصاءات المباراة

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

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

خطوات الدمج

أرسِل البيانات باستخدام واجهة برمجة التطبيقات Game Stats كأحداث مرنة للاعبين للإحصاءات المتكررة، وحدث progressUpdate محدّد مسبقًا لإحصاءات التقدّم. عليك أيضًا ضبط منطق احتساب الإحصاءات التي ستظهر في الملف الشخصي للاعب ومعلومات عرضها.

تمثّل أحداث اللاعبين لحظات مميزة داخل اللعبة أو عمليات إكمال حلقة اللعبة أو إنجازات التقدّم.

يتم تحديد حدث اللاعب وتصميمه على النحو التالي:

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

يتضمّن التكامل الخطوات التالية:

• تحديد مخطط البيانات الأولية: حدِّد أحداث اللاعبين باستخدام عملية تحميل ملف CSV في Play Console. اطّلِع على إنشاء أحداث.
• التكامل مع Game Stats API: أرسِل بيانات اللاعبين الأولية بالتنسيق المحدّد لأحداث اللاعبين المرنة وحدث progressUpdate.
  • إرسال جميع الأحداث المحدّدة باستخدام التكامل من جهة العميل أو جهة الخادم لمزيد من المعلومات، اطّلِع على أمثلة أحداث اللاعبين وحدث progressUpdate.
• تحميل ملف ZIP: قدِّم 3 ملفات CSV وجميع ملفات صور الرموز التي تحدّد 5 إحصاءات متكررة ومستوى تقدّم واحد للاعب. لمزيد من المعلومات، يُرجى الاطّلاع على إرشادات ملف ZIP. احرص على تضمين التفاصيل التالية:
  • ملف CSV للإحصاءات المتكرّرة:
    • معرّف فريد للإحصاء.
    • حدِّد تصنيف الحدث الذي سيتم استخدامه لاحتساب الإحصاءات. لا يمكنك استخدام تصنيف الحدث progressUpdate هنا.
      • تحديد تصنيف السمة المطلوب استخدامه لاحتساب الإحصاءات يجب أن تكون هذه السمة إحدى سمات الحدث المحدّد.
      • حدِّد نوع التجميع (SUM أو MAX أو MIN أو COUNT) لتحديد كيفية حساب الإحصاءات في تصنيف السمة المحدّدة.
      • حدِّد شرط فلتر اختياريًا لاحتساب المنطق فقط عند استيفاء الشرط. حدِّد السمة وتصنيف الحدث وعامل التشغيل (= أو < أو <= أو >= أو >) وقيمة الحد.
    • تضمين علامة منطقية للإشارة إلى ما إذا كان يمكن استخدام الإحصاءات للميزات التنافسية
    • إذا كان يمكن استخدام الميزة في ميزات تنافسية، يجب تحديد الحدّ الأدنى والأقصى للساعات التي يمكن أن يلعبها لاعب حقيقي. سيتم استخدام هذه المعلومات لتحديد اللاعبين الذين قد يسيئون استخدام الميزات، مثل البطولات والتحديات الاجتماعية.
    • أدخِل اسمًا معروضًا فريدًا للإحصاءات التي يراها اللاعبون.
    • قدِّم نصًا فريدًا يصف الإحصاءات، ويجب أن يوفّر هذا الوصف تفاصيل حول كيفية حصول اللاعب على الإحصاءات، وسيتم عرضه للاعبين في واجهة مستخدم &quot;الملف الشخصي للّاعب&quot;.
    • قدِّم رمزًا فريدًا يمثّل الإحصاء من خلال إدخال اسم ملف الرمز الدقيق في ملف CSV.
    • قدِّم إدخالاً اختياريًا يحدّد ما إذا كانت القيمة المتزايدة أو المتناقصة مفيدة للاعب. سيتم استخدام هذا الإدخال للاحتفال بحركات اللاعبين.
    • قدِّم وحدة قياس اختيارية للإحصاءات، مثل الكيلومترات والأميال والثواني.
  • ملف CSV لإحصاء تقدّم اللاعب:
    • أدخِل اسمًا معروضًا فريدًا لمستوى تقدّم اللاعب يظهر للاعبين.
    • قدِّم رمزًا فريدًا يمثّل الإحصاء.
    • قدِّم وصفًا لإحصاءات مستوى التقدّم.
    • قدِّم إدخالاً اختياريًا يحدّد ما إذا كانت القيمة المتزايدة أو المتناقصة مفيدة للاعب. سيتم استخدام هذا الإدخال للاحتفال بحركات اللاعبين فقط عندما تكون السمة currentProgress من النوع INT.
    • قدِّم وحدة قياس اختيارية للإحصاءات، مثل كيلومتر أو ميل أو ثانية.
  • ملف CSV للترجمة: قدِّم أسماء عرض مترجَمة لجميع الإحصاءات.
    • أضِف صفًا واحدًا لكل عملية ترجمة.
    • استخدِم سلسلة الاسم المعروض للإحصاء كما تمت إضافتها في ملف CSV السابق لتحديد الإحصاء بشكل فريد الذي تتم إضافة الترجمة إليه.
    • حدِّد اللغة من قائمة رموز اللغات.
    • أضِف ترجمة للاسم المعروض باللغة المحدّدة.
    • أضِف ترجمة لوصف الإحصاء باللغة المحدّدة.

تخطيط المخطط

يمكنك إرسال نوعَين من البيانات باستخدام Game Stats API: أحداث اللاعبين وحدث محدّد مسبقًا لإحصاءات مستوى تقدّم اللاعبين.

توضّح الأمثلة التالية كيف تبدو أحداث اللاعبين في أنواع مختلفة من الألعاب:

أحداث اللاعب

يتم تحديد "أحداث اللاعبين" من خلال لحظات مميزة داخل اللعبة أو عمليات إكمال حلقة اللعبة أو إنجازات التقدّم.

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

progressUpdate حدث

إذا كانت لعبتك تتضمّن آلية تقدّم أساسية، استخدِم هذا الحدث لإرسال مستوى تقدّم اللاعب الحالي. يحتوي الحدث على سمة محدّدة مسبقًا باسم “currentProgress” من النوع INT أو STRING. يجب إرسال القيمة الحالية لمستوى تقدّم اللاعب في آلية التقدّم الأساسية باستخدام هذه السمة. في حال استخدام هذا الحدث، يجب توفُّر السمة المحدّدة مسبقًا "currentProgress"، ويجب تحديد إحصاءات التقدّم باستخدام هذه السمة.

يمكنك إرسال القيمة الحالية لأنظمة التقدّم الأخرى في لعبتك، مثل lifetime highest score أو current coin balance، كخصائص أخرى لهذا الحدث.

بما أنّ اللاعبين يمكنهم مقارنة ملفاتهم الشخصية حسب مستوى التقدّم الحالي في اللعبة، من المهم ألا يكون هناك أي تأخير في الحصول على قيمة مستوى التقدّم الحالي بعد عملية الدمج الأولى. لعرض مستوى التقدّم الحالي بدقة للاعبين، عليك إرسال الحدث progressUpdate في بداية كل جلسة لعب وعندما يتم تعديل مستوى التقدّم الحالي.

ضبط إحصاءاتك

عليك ضبط إحصاءات التكرار والتقدّم من خلال تحديد منطق الاحتساب وعرض المعلومات الخاصة بكل إحصاء، كما هو موضّح في الأمثلة أدناه على إحصاءات التكرار من مختلف أنواع الألعاب. الإحصاءات المتكرّرة هي عادةً إحصاءات يتم تعديلها بشكل متكرّر لأي لاعب خلال عدد قليل جدًا من جلسات اللعب (3 إلى 4) وتكون مرتبطة بحلقة اللعب الأساسية.

تفاصيل عملية الدمج

تتوفّر نقاط نهاية واجهة برمجة التطبيقات وحزمة تطوير البرامج (SDK) للحصول على ملاحظات مبكرة، وستصبح متاحة للجميع اعتبارًا من أغسطس 2026. الاطّلاع على المخطط الزمني

يوضّح هذا القسم كيفية إنشاء الأحداث وإرسالها في عمليات الدمج من جهة العميل ومن جهة الخادم.

متى يجب إرسال البيانات؟

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

يمثّل progressUpdate الحدث مستوى التقدّم الحالي للاعب. يجب إرسال بيانات إحصاءات التقدّم باستخدام هذا الحدث في الحالات التالية:

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

مسارات الدمج

هناك مساران للدمج، وهما العميل والخادم إلى الخادم.

الدمج من خادم إلى خادم

تتيح لك نقطة نهاية واجهة برمجة التطبيقات العامة إرسال الأحداث في حمولة الطلب باستخدام الإعدادات التالية:

مَعلمات المسار

الترخيص والمصادقة

تتّبع طلبات البيانات من واجهة برمجة التطبيقات بين الخوادم إرشادات الوصول إلى "خدمات ألعاب Play" من جهة الخادم العادية باستخدام OAuth 2.0. يجب أن تتضمّن الطلبات رمز Bearer مميزًا مفوَّضًا باستخدام النطاق https://www.googleapis.com/auth/games.

Flexible Events: نص الطلب

تفرض واجهة برمجة التطبيقات الخلفية حدودًا صارمة للتحقّق من صحة البنية:

• حجم الدفعة: 30 حدثًا كحدّ أقصى لكل BatchRecordEventsRequest.
• عدد المواقع: 25 موقعًا مخصّصًا كحدّ أقصى لكل PlayerGameEvent.
• حدود الطول: اسم الحدث (100 حرف كحد أقصى)، ومفاتيح السمات (100 حرف كحد أقصى)، وقيم السلسلة الخاصة بالسمات (1024 حرفًا كحد أقصى).
• معرّف الحدث: يجب أن يكون سلسلة معرّف فريد عالمي (UUID) صالحة تتألف من 36 حرفًا.
• إعادة المحاولة والتخزين المؤقت: تجنَّب التخزين المؤقت أو تجميع عدد كبير من الأحداث محليًا في حال تعذُّر الوصول إلى واجهة برمجة التطبيقات، لأنّ عمليات إعادة المحاولة المجمّعة التي تتجاوز 30 حدثًا سيتم رفضها. يجب دائمًا تقسيم عمليات إعادة المحاولة إلى أجزاء صغيرة للالتزام بالحدّ الأقصى لحجم الدفعة.

BatchRecordEventsRequest

يمكنك الاطّلاع على BatchRecordEventsRequest.

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent

{
  "eventId": string,
  "eventName": string,
  "eventProperties": {
    // keys (e.g., "matchId", "score")
    "": {
       object (PropertyValue)
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
}

PropertyValue

// ONE of the following fields will be present:
{
// 64-bit integer formatted as a string to prevent data loss
"intValue": "string",
// Double-precision floating point number.
"doubleValue": number,
// Standard UTF-8 text string.
"stringValue": "string",
// Boolean value (true or false).
"boolValue": boolean,
// Duration in seconds suffixed with 's' (e.g., "240s" or "3.5s").
"durationValue": "string"
}

حدث progressUpdate: نص الطلب

BatchRecordEventsRequest

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (PlayerGameEvent)
    }
  ]
}

PlayerGameEvent - progressUpdate

{
  "eventId": string,
  "eventName": "progressUpdate",
  "eventProperties": {
    "": {
       object (PropertyValue)
// Must have at least one property "currentProgress"  of  type  INT  or  STRING
    }
  },
  "eventTime": string // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z")
}

نص الردّ

في حال نجاح العملية، يتم عرض رمز الحالة HTTP 200 OK مع كائن JSON فارغ.

مثال على نص الطلب

الحدث: PlayerGameEvent

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID for deduplication and idempotency
      "eventName": "matchCompleted",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-05-09T01:44:44Z").
      "eventProperties": {
        "matchId": {
          "stringValue": "Match_A"
        },
        "gameMode": {
          "stringValue": "Battle_B"
        },
        "locationId": {
          "stringValue": "Location_XYZ"
        },
        "playerElimination": {
          "intValue": 2
        },
        "isWinner": {
          "boolValue": true
        }
      }
    }
  ]
}

حدث progressUpdate

{
  "packageName": "com.example.awesomegame",//Your package name
  "requestTime": "2026-05-09T00:44:44Z",
  "events": [
    {
      "eventId": "123e1234-e29b-41d4-a123-446655440000", // UUID
      "eventName": "progressUpdate",
      "eventTime": "2026-05-09T01:44:44Z", // RFC 3339 formatted timestamp string (e.g., "2026-01-01T18:00:00Z").
      "eventProperties": {
        "currentProgress": {
          "intValue": 52
        },
//Add more properties as per your requirement
      }
    }
  ]
}

عمليات تنفيذ العميل

للتعرّف على معلومات حول تنفيذ ميزة "إحصاءات الألعاب" على نظامك الأساسي، اطّلِع على المراجع التالية:

• Android
• Unity
• C++‎

الإنجازات