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

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

يجب أن تستوفي إحصاءات اللعب الشروط التالية:

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

تعرض الصورة "إحصاءات اللعب" في "الملف الشخصي للّاعب" ضمن علامة التبويب أنت. تتوفّر واجهة المستخدم هذه في علامة التبويب أنت لأغراض الاختبار فقط. ستتوفّر واجهة مستخدم "إحصاءات اللعب" في سبتمبر 2026.

"إحصاءات اللعب" في علامة التبويب "أنت"
إحصاءات اللعب مع أهم التفاصيل في علامة التبويب "أنت"

نوع التجميع

يحدّد نوع التجميع لـ Google Play كيفية احتساب إحصاءات من القيم لكل حدث التي ترسلها:

  • SUM: تُستخدَم للإحصاءات التراكمية (مثل إجمالي العملات التي تم جمعها، وإجمالي الضرر الذي تم إلحاقه). يجب أن ترسل اللعبة المبلغ المنفصل الذي تم تحقيقه خلال كل مثيل حدث.
  • COUNT: تُستخدَم للإحصاءات التي تمثّل عدد مرات وقوع حدث معيّن (مثل الألعاب التي تم لعبها أو الألعاب التي تم الفوز بها). يجب أن ترسل اللعبة حالات حدوث الأحداث المنفصلة.
  • الحد الأقصى: يُستخدم فقط للإنجازات التي تحدث لمرة واحدة (مثل أعلى نتيجة في جولة واحدة أو الحد الأقصى لسلسلة الانتصارات المتتالية أو أعلى ضرر في مباراة واحدة). لا تستخدِم MAX كحل بديل لعرض الإجماليات منذ بداية النشاط من القيم الجارية المحسوبة مسبقًا.

متطلبات التنفيذ المهمة للإحصاءات المتكررة

  • إرسال القيم لكل حدث: بالنسبة إلى كل حدث، أرسِل فقط ما حدث في ذلك الحدث، مثل العملات المعدنية التي تم جمعها في جولة واحدة. بعد ذلك، اضبط نوع التجميع، مثل SUM أو COUNT، في إعدادات الإحصاءات. يضمن ذلك إمكانية إعادة استخدام الإحصاءات المتكرّرة في آليات التفاعل، ويتيح لـ Google Play إنشاء تجارب اللاعبين المناسبة.
  • عدم إرسال الإجماليات الدائمة: على سبيل المثال، لا تتبَّع إجمالي العملات التي جمعها اللاعب في برنامج العميل أو الخادم الخاص بلعبتك وأرسِل هذا الإجمالي باستخدام تجميع MAX. ستستمر هذه الإحصاءات في الظهور على واجهة مستخدم الملف الشخصي للّاعب، ولكن لن يتمكّن Google Play من استخدامها لتفعيل ميزات المكافآت، مثل الدوريات والمهام والسباقات، لتحسين تجربة اللاعبين وزيادة تأثير لعبتك.

للحصول على تعليمات وأمثلة حول النمذجة الصحيحة للأحداث، يُرجى الاطّلاع على أحداث اللاعبين وضبط الإحصاءات.

خطوات الدمج

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

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

يتم تحديد حدث اللاعب ووضع نموذج له على النحو التالي:

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

يتألف الدمج من الخطوات التالية:

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

التخطيط للمخطط

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

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

أحداث اللاعبين

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

  • حدِّد الأحداث على أنّها لحظات معيّنة داخل اللعبة أو إكمال حلقات الألعاب أو مراحل تقدُّم:
    • عمليات إكمال حلقة الألعاب، مثل مباراة أو جولة مكتملة
    • مراحل التقدّم، مثل مستوى التقدّم المحفوظ في استكشاف منطقة أو إكمال مستوى معيّن
    • بما أنّ الإحصاءات المتكرّرة يجب أن تمثّل الإجراءات المتكرّرة التي يتّخذها اللاعب، يجب ربط الأحداث المحدّدة بأسلوب اللعب الأساسي.
  • أضِف سمات لتقديم سياق حول الحدث ونتائجه، مثل رقم المستوى أو نوع المباراة أو نوع السلاح أو عدد الأسلحة أو الإصابات في الرأس أو العملات المعدنية التي تم جمعها أو نتيجة المباراة أو وقت الدورة أو نوع السيارة.
  • أرسِل الأحداث ضمن جلسة اللعب فور حدوثها. على سبيل المثال، يمكنك إرسال حدث اكتمال حلقة الألعاب فور اكتمال الحلقة.
أمثلة
نوع اللعبة تصنيف الحدث لحظة داخل اللعبة / إكمال حدث تقدُّم / إكمال حلقة الألعاب النتيجة الخصائص
لعبة ألغاز مستقلة ذات تقدّم خطي chapter_completed إكمال حدث تقدُّم لا ينطبق رقم الفصل، اسم الفصل، عدد المحاولات، عدد الشاشات، عدد الحركات، محتوى الفصل
screen_completed إكمال حدث تقدُّم رقم الفصل، اسم الفصل، عدد المحاولات، عدد الحركات، محتوى الفصل
ألعاب الركض اللانهائي الثلاثية الأبعاد run_completed إكمال حلقة الألعاب العملات التي تم جمعها، النتيجة مدة الجري، والعملات التي تم جمعها من الحقيبة النفاثة، والمعزّز المستخدَم في بداية الجري، وألواح التزلج المستخدَمة، والمغناطيس المستخدَم، والقفازات المستخدَمة، والحقيبة النفاثة المستخدَمة
لعبة حركة وتقمّص أدوار في عالم مفتوح areaExplorationProgress إكمال حدث تقدُّم هزيمة الأعداء وجمع الجرعات رقم المنطقة، اسم المنطقة، نسبة التقدّم
questCompleted إكمال حلقة الألعاب لا ينطبق اسم المهمة
weaponUnlocked لحظة داخل اللعبة لا ينطبق اسم السلاح، مستوى السلاح
chestUnlocked لحظة من اللعبة تم جمع خام التعزيز
ألعاب ألغاز بسيطة مع عناصر تزيين puzzleCompleted إكمال حلقة الألعاب / إكمال حدث التقدّم العملات التي تم جمعها، أدوات التعزيز التي تم جمعها عدد الحركات، هل تم استخدام هدية "باتلر"؟، نوع المستوى، ورقم المستوى، والمعزّزات الملوّنة المستخدَمة، والمتفجرات المستخدَمة
cardsCollected لحظة داخل اللعبة بطاقات بنجمة واحدة، بطاقات بنجمتَين، بطاقات بثلاث نجوم، إجمالي البطاقات رقم الألبوم، اسم الألبوم
سباق كلاسيكي raceCompleted إكمال حلقة الألعاب الترتيب، عدد مرات استخدام أكسيد النيتروز، وقت السباق نوع السباق، التقييم، السيارة_المستخدمة
carUpgraded لحظة داخل اللعبة ميزة السيارة التي تمت ترقيتها، والمستوى / القيمة القديمة، والمستوى / القيمة الجديدة نوع السيارة، ومستوى المرآب الحالي
لعبة إطلاق نار ومعارك ملكية من منظور الشخص الثالث matchCompleted إكمال حلقة الألعاب عمليات الإقصاء، والتصويب على الرأس، وقيمة الشرف نوع المباراة، وقت البقاء على قيد الحياة
محاكاة إدارة الرياضات الإلكترونية matchCompleted إكمال حلقة الألعاب النتيجة، الأهداف المسجّلة، الأهداف اسم الفريق الخصم، اسم الفريق الذي يلعب
trainingCompleted لحظة داخل اللعبة تم إكمال التدريبات، teamplay_form_attack، teamplay_form_defense، teamplay_form_possession، teamplay_form_condition

حدث واحد (progressUpdate)

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

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

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

أمثلة
نوع اللعبة سمة currentProgress لحدث `progressUpdate`
لعبة ألغاز ذات تقدّم خطي رقم الفصل أو المستوى الحالي
لعبة ركض لا نهائي ثلاثية الأبعاد أعلى نتيجة، رصيد التعزيزات الحالي
ألعاب ألغاز بسيطة رقم المستوى الحالي، وعدد مرات الفوز من المحاولة الأولى، وعدد المناطق المكتملة، وعدد المجموعات المكتملة
سباق كلاسيكي رقم المستوى الحالي، رصيد العملة
لعبة حركة وتقمّص أدوار في عالم مفتوح ترتيب الشخصية الحالي، رقم المستوى الحالي
ألعاب التصويب من منظور الشخص الثالث رقم المستوى الحالي
محاكاة الرياضات الإلكترونية رقم مستوى المدير، رقم مستوى النادي

ضبط إعدادات الإحصاءات

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

لمعرفة حالات استخدام SUM أو COUNT أو MAX، يُرجى الاطّلاع على المقالة اختيار نوع التجميع المناسب.

اسم اللعبة الاسم المعروض لإحصاءات اللعبة Event Property منطق الاحتساب [aggregation] الفلترة
لعبة ركض ثلاثية الأبعاد بلا نهاية عمليات التشغيل المكتملة أي سمة للحدث run_completed العدد كل القيم [بدون فلتر]
عدد العملات التي جمعتها سمة Coins_collected للحدث run_completed المجموع لا ينطبق
المفاتيح التي تم جمعها سمة Keys_collected للحدث run_completed المجموع لا ينطبق
أعلى نتيجة في الجولة سمة النتيجة للحدث run_completed الحد الأقصى لا ينطبق
عدد الجولات المكتملة التي تم جمع عدد كبير من العملات فيها سمة Coins_collected للحدث run_completed العدد القيمة > 5000
لعبة ألغاز ذات تقدّم خطي الفصول المكتملة أي سمة للحدث chapter_completed العدد كل القيم [بدون فلتر]
الشاشات المكتملة أي سمة للحدث screen_completed العدد كل القيم [بدون فلتر]
الفصول المكتملة من المحاولة الأولى سمة Num_try للحدث chapter_completed العدد Num_try = 1
الشاشات التي تم إكمالها من المحاولة الأولى سمة Num_try للحدث screen_completed العدد Num_try = 1
لعبة حركة وتقمّص أدوار في عالم مفتوح المهام المكتملة أي سمة للحدث quest_completed العدد كل القيم [بدون فلتر]
المناطق التي تم استكشافها سمة Perc_progress لحدث area_exploration_progress العدد القيمة = 100
تم فتح قفل السيوف سمة Weapon_type للحدث weapon_unlocked العدد القيمة = "سيف"
عدد الأعداء الذين تمّت هزيمتهم سمة Enemies_defeated للحدث area_exploration_progress المجموع لا ينطبق
عدد جرعات الصحة التي تم جمعها سمة Enhancement_ores للحدث chest_unlocked المجموع لا ينطبق
ألعاب ألغاز بسيطة المراحل المكتملة أي سمة للحدث level_completed العدد كل القيم [بدون فلتر]
المستويات المكتملة من المحاولة الأولى سمة Num_try للحدث level_completed العدد القيمة = 1
عدد أدوات تحسين الألوان المستخدَمة سمة Color_booster_used للحدث level_completed المجموع لا ينطبق
عدد القنابل المعزِّزة المستخدَمة سمة Bomb_booster_used للحدث level_completed المجموع لا ينطبق
البطاقات التي تم جمعها سمة Total_cards للحدث cards_collected المجموع لا ينطبق
سباق كلاسيكي سباقات الفوز سمة الترتيب للحدث race_completed العدد القيمة = 1
أسرع سباق سمة race_time للحدث race_completed الحد الأدنى لا ينطبق
NOS مستخدَمة سمة NOS_used للحدث race_completed المجموع لا ينطبق
سباقات تم إنهاؤها بسيارة Mustang سمة Car_type للحدث race_completed العدد القيمة = "Mustang"
ترقيات السيارات أي سمة للحدث car_upgraded العدد كل القيم [بدون فلتر]
لعبة إطلاق نار من منظور الشخص الثالث في معركة ملكية المباريات التي فاز بها أي سمة للحدث match_completed العدد Match_result = TRUE
إجمالي عمليات الإقصاء سمة "عمليات الإقصاء" للحدث match_completed المجموع لا ينطبق
أطول مدة بقاء على قيد الحياة سمة Survival_time للحدث match_completed الحد الأقصى لا ينطبق
إجمالي الإصابات في الرأس سمة Headshots للحدث match_completed المجموع لا ينطبق
إجمالي قيمة المهارات سمة Skill_value للحدث match_completed المجموع لا ينطبق
محاكاة إدارة الرياضات الإلكترونية المباريات التي فاز بها سمة النتيجة للحدث match_completed العدد Result = "Won"
إجمالي الأهداف المسجّلة سمة Goals_scored للحدث match_completed المجموع لا ينطبق
المباريات الصعبة التي فزت بها سمة النتيجة للحدث hard_match_completed العدد Result = "Won"
أعلى فارق أهداف في مباراة فوز سمة Goal_difference للحدث match_completed الحد الأقصى Result = "Won"
إجمالي التدريبات سمة Drills_done للحدث training_completed المجموع لا ينطبق
إجمالي الدورات التدريبية المكتملة أي سمة للحدث training_completed العدد لا ينطبق

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

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

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

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

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

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

مسارات الدمج

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

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

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

طلب HTTP

POST https://games.googleapis.com/games/v1/players/{playerId}/gameStats: batchRecordEvents

مَعلمات المسار
المَعلمة نوع البيانات الوصف
playerId سلسلة رقم تعريف اللاعب في "خدمات ألعاب Google Play"

التفويض والمصادقة

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

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

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

  • حجم الدفعة: 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
      }
    }
  ]
}

عمليات التنفيذ لدى العملاء

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

الإنجازات

التاريخ دمج إحصاءات اللعب API إعدادات إحصاءات اللعب
سبتمبر 2026 لا ينطبق يبدأ اللاعبون في الاطّلاع على إحصاءات اللعب في ملفاتهم الشخصية.