دمج إحصاءات المباريات

يوضّح هذا المستند كيفية دمج ميزة "إحصاءات اللعب" في لعبتك باستخدام Google Play Console. ويتناول تنسيقات ملفات CSV وZIP الأساسية، ويشرح كيفية إنشائها واستيرادها وإدارتها.

إنشاء الأحداث أو استيرادها

هناك طريقتان لإضافة الأحداث لأول مرة باستخدام Google Play Console:

إنشاء حدث

لإنشاء حدث للعبة، أكمِل الخطوات التالية:

  1. اختَر لعبة في Google Play Console.
  2. في صفحة إحصاءات اللعب ضمن "خدمات ألعاب Play" (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب)، اختَر إضافة حدث > إنشاء حدث.
  3. في صفحة إنشاء حدث، املأ النموذج.
  4. انقر على حفظ التغييرات.

استيراد أحداث

لإضافة عدة أحداث إلى لعبتك في آنٍ واحد، اتّبِع الخطوات التالية:

  1. أنشئ ملف CSV للأحداث باسم PlayerGameEvent.csv.
  2. اختَر لعبة في Google Play Console.
  3. في صفحة إحصاءات اللعب ضمن "خدمات ألعاب Play" (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب)، اختَر إضافة حدث > استيراد من خلال ملف CSV.
  4. في صفحة إعدادات الأحداث، أفلِت ملف CSV لتحميله.
  5. بعد إنشاء حدث، عليك إعداد الإحصاءات.

إنشاء إحصاءات أو استيرادها

هناك طريقتان لإضافة الإحصاءات لأول مرة باستخدام Google Play Console:

إنشاء إحصاء

لإنشاء إحصاءات للعبة، أكمِل الخطوات التالية:

  1. اختَر لعبة في Google Play Console.
  2. في صفحة إحصاءات اللعب ضمن "خدمات ألعاب Play" (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب)، اختَر إضافة إحصاءة > إنشاء إحصاءة.
  3. في صفحة إنشاء إحصاء، املأ النموذج.
  4. انقر على حفظ التغييرات.
  5. بعد إنشاء إحصاء، انشر لعبتك.

استيراد الإحصاءات

لاستيراد الإحصاءات، اتّبِع الخطوات التالية:

  1. أنشئ ملف ZIP يحتوي على الإحصاءات وملفات الترجمة وملفات الرموز وفقًا لإرشادات ملف ZIP للإحصاءات.
  2. اختَر لعبة في Google Play Console.
  3. في صفحة إحصاءات اللعب ضمن "خدمات ألعاب Play" (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب)، اختَر إضافة إحصاءة > استيراد من خلال ملف ZIP.
  4. في صفحة إعدادات إحصاءات اللعب، أفلِت ملف ZIP لتحميله.
  5. بعد تحميل جميع الإحصاءات، انشر لعبتك.

اختبار "إحصاءات اللعب"

للتأكّد من أنّ ميزة "إحصاءات اللعب" تعمل على النحو المطلوب، اتّبِع الخطوات التالية لاختبارها:

  • افتح تطبيق متجر Google Play.
  • سجِّل الدخول إلى ملفك الشخصي على تطبيق "ألعاب Google Play" في تطبيق متجر Google Play.
  • اطّلِع على إحصاءات اللعب في ملفك الشخصي كلاعب.

عرض السجلّات على جهازك

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

  1. فعِّل تصحيح أخطاء adb على جهازك ونفِّذ الأوامر التالية في الوحدة الطرفية:

    adb shell setprop log.tag.Games INFO
    adb logcat -s "PlayGamesServices[GameStatsAgent]:I"
  2. تأكَّد من ظهور رسالة مسجّلة بنجاح، كما هو موضّح في المثال التالي:

    Successfully uploaded batch of X events.
    

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

  3. إذا تعذّر التحقّق من صحة أي أحداث تم إرسالها، ستظهر لك رسالة خطأ توضّح سبب تعذُّر التحقّق:

    BatchRecordEvents validation failed for X event(s): ...
    

نشر "إحصاءات اللعب"

بعد الانتهاء من الاختبار، يجب نشر لعبتك. يتم نشر جميع أحداث لعبتك وإحصاءاتها معها.

لنشرها، اتّبِع الخطوات التالية:

  1. اختَر لعبة في Google Play Console.
  2. في صفحة خدمات ألعاب Play - إحصاءات اللعب (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب)، انقر على المراجعة والنشر.
  3. في صفحة خدمات ألعاب Play - النشر (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > النشر)، راجِع الإجراءات وحُلّ المشاكل.
  4. انقر على نشر. يتم نشر جميع إحصاءات اللعب.

تعديل إحصاءات اللعب

إذا كانت لديك إحصاءات لعب حالية وتريد تعديلها:

  1. اختَر لعبة في Google Play Console.
  2. انتقِل إلى صفحة خدمات ألعاب Play - إحصاءات اللعب (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب).
  3. لتعديل حدث:
    1. في قسم إعدادات الأحداث، اختَر حدثًا.
    2. يمكنك إضافة سمات الأحداث أو حذفها.
      • لا يمكنك تعديل اسم الحدث.
    3. انقر على حفظ التغييرات.
  4. لتعديل إحصاء:
    1. في قسم إعدادات "إحصاءات اللعب"، اختَر إحدى الإحصاءات.
    2. يمكنك تعديل حقول اسم الإحصاءات ووصف الإحصاءات واسم ملف الرمز.
      • لا يمكنك تعديل معرّف الإحصاءات واتجاه التقدّم. وحدة الإحصاءات وتفاصيل الحدث المرتبط
    3. انقر على حفظ التغييرات.
  5. في صفحة خدمات ألعاب Play - إحصاءات اللعب، تكون الإحصاءات المعدَّلة في الحالة متاحة للمختبِرين.
  6. بعد اختبار الإحصاءات، انقر على المراجعة والنشر. يؤدي ذلك إلى إعادة نشر اللعبة للجميع، بالإضافة إلى جميع الإحصاءات المعدَّلة.

حذف إحصاءات اللعب

بعد نشر "إحصاءات اللعب"، لا يمكن حذفها.

يمكنك حذف حدث أو إحصاء في الحالة متاح للمختبِرين.

  1. اختَر لعبة في Google Play Console.
  2. انتقِل إلى صفحة خدمات ألعاب Play - إحصاءات اللعب (زيادة عدد المستخدمين > خدمات ألعاب Play > الإعداد والإدارة > إحصاءات اللعب).
  3. لحذف حدث:
    1. في قسم إعدادات الأحداث، اختَر حدثًا.
    2. انقر على حذف الحدث.
  4. لحذف إحصاء:
    1. في إعدادات إحصاءات اللعب، اختَر الإحصاءات التي تريد حذفها.
    2. انقر على حذف إحصاءات اللعبة.

إرشادات ملفات CSV للأحداث

الصف الأول من ملف CSV هو صف عناوين. يجب استيراد الأحداث باستخدام ملف CSV الخاص بالأحداث، مثل PlayerGameEvent.csv.

تنسيق ملف PlayerGameEvent.csv

يحتوي ملف CSV على الحدث المُعلَن وسماته كقيم مفصولة بفواصل بالترتيب التالي:

 Event Name,Property Name,Property Type

إذا أرسلت حدث progressUpdate لـ progressionStat، أضِف صفًا لهذا الحدث. يجب أن يحتوي هذا الحدث على سمة currentProgress واحدة على الأقل من النوع INT أو STRING، بالإضافة إلى أي سمات أخرى تريد إرسالها.

يتم وصف هذه الحقول في الجدول التالي:

عناوين أعمدة CSV مطلوب أو اختياري القيم المقبولة
اسم الحدث مطلوب ‫50 حرف كحدّ أقصى

يجب أن يتألف من أحرف وأرقام وشرطات سفلية فقط.

في حال استخدام اسم الحدث الخاص progressUpdate، يجب أن يتضمّن سمة باسم currentProgress من النوع INT64 أو STRING.

اسم الموقع مطلوب ‫50 حرف كحدّ أقصى

يجب أن يتألف من أحرف وأرقام وشرطات سفلية فقط.

فريدة لكل حدث: يجب أن تكون أسماء السمات فريدة ضمن الحدث نفسه.

لا تستخدِم الكلمات الرئيسية المحجوزة التالية: id أو count أو key أو value أو where أو from أو and أو or أو true أو false.

نوع الموقع مطلوب سلسلة تعداد حسّاسة لحالة الأحرف تتطابق مع أحد أنواع البيانات المتوافقة: INT64 وDOUBLE وSTRING وBOOL

متطلبات ملف PlayerGameEvent.csv:

  • يتيح الملف استخدام 20 اسم حدث فريد كحد أقصى، مع ما يصل إلى 20 سمة لكل حدث.
  • لا يمكن أن يكون محتوى الملف فارغًا ويجب أن يحتوي على صف واحد على الأقل.
مثال على الجدول
اسم الحدث اسم الموقع نوع الموقع
matchCompleted المدة DOUBLE
matchCompleted عمليات قتل INT64
matchCompleted isWinner BOOL
matchCompleted matchType STRING
itemCollected coinsAmount INT64
itemCollected weaponType STRING
progressUpdate currentProgress INT64

إرشادات ملف ZIP للإحصاءات

يمكنك استيراد الإحصاءات دفعة واحدة باستخدام ملف ZIP. اطّلِع على الجدول لمعرفة أسماء الملفات المحددة التي يجب استخدامها في ملف ZIP:

اسم الملف مطلوب أو اختياري القيم المقبولة
RepetitiveStatsConfig.csv مطلوب تمثّل الإحصاءات المتكررة الإجراءات التي تحدث بانتظام داخل اللعبة وينفّذها اللاعبون.
ProgressionStatConfig.csv مطلوب تمثّل إحصاءات التقدّم مستوى تقدّم اللاعب في اللعبة.
StatLocalizations.csv اختياري يوفّر ترجمات لأسماء إحصاءات اللعب وأوصافها.
ملفات الرموز مطلوب تحتوي على رموز بتنسيق PNG أو JPEG أو JPG بحجم 512 × 512.

يجب أن يستوفي ملف ZIP المتطلبات التالية:

  • الحدّ الأقصى لحجم ملف ZIP: يبلغ الحدّ الأقصى لإجمالي الحجم غير المضغوط 10 ميغابايت.
  • الحد الأقصى لعدد الملفات: يجب ألا يزيد إجمالي عدد الملفات داخل أرشيف ZIP عن 53 ملفًا (3 ملفات CSV و50 رمزًا).
  • الحد الأقصى لإجمالي الإحصاءات: 50 إحصاءً كحد أقصى في ProgressionStatConfig.csv وRepetitiveStatsConfig.csv.
  • ملفات CSV المتوافقة: ProgressionStatConfig.csv وRepetitiveStatsConfig.csv وStatLocalizations.csv (اختياري). إذا أردت تحميل إحصاءات التقدّم فقط، لا تُضمِّن ملف CSV الخاص بالإحصاءات المتكرّرة في ملف ZIP، وإلا ستعرض وحدة التحكّم خطأً. وينطبق الأمر نفسه إذا أردت تحميل إحصاءات متكررة فقط.
  • ملفات صور الرموز: PNG (‎.png) أو JPEG (‎.jpg أو ‎.jpeg)
    • يجب أن تكون جميع الرموز المُشار إليها في ملفات CSV متوفّرة في المجلد الجذر لملف ZIP.
    • يجب أن تتم الإشارة إلى جميع ملفات الصور المتوفّرة في ملف ZIP في إحصاء واحد على الأقل.
  • بنية الدليل: يجب أن تكون جميع الملفات في جذر ملف ZIP. ولا يُسمح باستخدام الأدلة الفرعية.

تنسيق ملف RepetitiveStatsConfig.csv

يحتوي ملف CSV على الحدث المُعلَن وسماته كقيم مفصولة بفواصل بالترتيب التالي:

Stat Id,Event Name,Event Property Name,Aggregation Type,Stat Display Name,Stat Description,Filter Property,Filter Operator,Filter Value,Is Competitive,Min limit,Max limit,Icon File Name,Good value direction,Unit

يتم وصف هذه الحقول في الجدول التالي:

عناوين أعمدة CSV مطلوب أو اختياري القيم المقبولة
رقم تعريف الإحصائية مطلوب ‫100 حرف كحدّ أقصى

يجب أن يتألف من أحرف وأرقام وشرطات سفلية فقط. يجب أن يكون فريدًا في جميع الإحصاءات في اللعبة.

اسم الحدث مطلوب ‫50 حرف كحدّ أقصى

يجب أن يشير إلى اسم الحدث المحدّد في تنسيق PlayerGameEvent.csv.

اسم سمة الحدث مطلوب ‫50 حرفًا كحدّ أقصى
الاسم المعروض للإحصاءات مطلوب ‫50 حرفًا كحدّ أقصى
الاسم المعروض التلقائي للإحصاءات (اللغة التلقائية) يجب أن يكون فريدًا في جميع الإحصاءات.
Stat Description مطلوب ‫500 حرف كحدّ أقصى
الوصف التلقائي للإحصاءات
نوع التجميع مطلوب ‫50 حرفًا كحدّ أقصى
SUM وMAX وMIN وCOUNT
سمة الفلتر اختياري الحد الأقصى هو 50 حرفًا
يجب أن يكون اسم السمة محدّدًا في ملف PlayerGameEvent.csv.
عامل تشغيل الفلتر اختياري =, !=, >, <, >=, <=
عوامل تشغيل مقارنة الفلاتر
قيمة الفلتر اختياري مقارنةً بـ "سمة الفلتر" يجب أن تكون قيمة الفلتر INT64, DOUBLE, BOOL, STRING.
تنافسية مطلوب true, false
الحد الأدنى مطلوبة عندما تكون قيمة "التنافسية" صحيحة الحدّ الأدنى المسموح به لنتيجة الإحصاءات التنافسية
الحد الأقصى مطلوبة عندما تكون قيمة "التنافسية" صحيحة الحدّ الأقصى المسموح به لنتيجة الإحصاءات التنافسية
اسم ملف الرمز مطلوب اسم ملف صورة الرمز المضمّنة في جذر ملف ZIP يجب ألا يتعارض مع أسماء ملفات الرموز المستخدَمة في الإحصاءات المتكررة.
اتجاه القيمة الجيدة مطلوب يحدّد ما إذا كانت القيم الأعلى INCREASING أو القيم الأدنى DECREASING أفضل.
وحدة اختياري وحدة قياس القيم الرقمية أو قيم المدة الأولية على سبيل المثال، KILOMETER أو SECOND أو PERCENTAGE أو UNITLESS.

إذا كنت لا تريد استخدام شرط الفلتر، اترك الخلية فارغة.

مثال على الجدول
رقم تعريف الإحصائية اسم الحدث اسم الموقع التجميع الاسم المعروض للإحصاءات Stat Description سمة الفلتر (اختيارية) عامل تشغيل الفلتر (اختياري) قيمة الفلتر (اختيارية) تنافسية minLimit maxLimit اسم ملف الرمز اتجاه القيمة الجيدة وحدة
1 matchCompleted المدة MAX أطول محتوى مطابق يشير هذا إلى مدة بقاء اللاعب في أي مباراة isWinner = TRUE TRUE 0 50 stat1.png في تراجع ثانية
2 matchCompleted isWinner COUNT المباريات التي فاز بها يشير هذا إلى عدد المباريات التي فاز بها اللاعب isWinner = TRUE TRUE 0 50 stat3.png في تزايد
3 matchCompleted عمليات قتل SUM عمليات القتل في المباريات الفردية عدد عمليات القتل التي تم تنفيذها في مباريات المواجهة matchType = "1-on-1" خطأ stat4.png في تزايد
4 itemCollected coinsAmount SUM إجمالي الذهب الذي تم جمعه لاعب يجمع العملات المعدنية أثناء اللعب في مباراة weaponType = "سيف" خطأ stat2.png في تزايد

تنسيق ملف ProgressionStatConfig.csv

يحتوي ملف CSV على الحدث المُعلَن وسماته كقيم مفصولة بفواصل بالترتيب التالي:

Stat Id,Event Property Name,Stat Display Name,Stat Description,Icon File Name,Good value direction,Unit

ستظهر إحصاءات مستوى التقدّم كأول إحصاءات للاعب في ملفه الشخصي.

يتم وصف هذه الحقول في الجدول التالي:

عناوين أعمدة CSV مطلوب أو اختياري القيم المقبولة
رقم تعريف الإحصائية مطلوب ‫100 حرف كحدّ أقصى

يجب أن يتألف من أحرف وأرقام وشرطات سفلية فقط. يجب أن يكون فريدًا في جميع الإحصاءات في اللعبة.

اسم سمة الحدث مطلوب ‫50 حرف كحدّ أقصى

يجب أن يكون اسم السمة محدّدًا في ملف PlayerGameEvent.csv.

الاسم المعروض للإحصاءات مطلوب يجب أن يكون الاسم فريدًا.
Stat Description مطلوب ‫50 حرفًا كحدّ أقصى
الوصف التلقائي للإحصاءات
اسم ملف الرمز مطلوب اسم ملف صورة الرمز المضمّنة في جذر ملف ZIP يجب ألا يتعارض مع أسماء ملفات الرموز المستخدَمة في الإحصاءات المتكررة.
اتجاه القيمة الجيدة مطلوب يحدّد ما إذا كانت القيم الأعلى INCREASING أو القيم الأدنى DECREASING أفضل.
وحدة اختياري وحدة قياس القيم الرقمية أو قيم المدة الأولية على سبيل المثال، KILOMETER أو SECOND أو PERCENTAGE أو UNITLESS.
مثال على الجدول
رقم تعريف الإحصائية اسم سمة الحدث Stat Display Name وصف الإحصاء اسم ملف الرمز اتجاه القيمة الجيدة
5 currentProgress المستوى يجمع اللاعبون نقاط الخبرة من خلال لعب المباريات والانتقال إلى مستويات أعلى. Level.png متزايد

تنسيق ملف StatLocalizations.csv

يحتوي ملف CSV على الحدث المُعلَن وسماته كقيم مفصولة بفواصل بالترتيب التالي:

Stat Id,Stat Display Name,Locale,Localized Stat Display Name,Localized Stat Description

يتم وصف هذه الحقول في الجدول التالي:

عناوين أعمدة CSV مطلوب أو اختياري القيم المقبولة
رقم تعريف الإحصائية مطلوب ‫100 حرف كحدّ أقصى

يجب أن يتألف من أحرف وأرقام وشرطات سفلية فقط. يجب أن يكون فريدًا في جميع الإحصاءات في اللعبة.

الاسم المعروض للإحصاءات مطلوب يجب أن يكون الاسم فريدًا.
اللغة مطلوب رمز اللغة، مثل en-US
أضِف ترجمات للعبتك قبل تحديد اللغة. يُرجى العِلم أنّه لا يمكنك تحديد اللغة التلقائية.

يمكنك العثور على رموز اللغات المتاحة في قائمة اللغات المتاحة.

الاسم المعروض المترجَم للإحصاءات اختياري ‫50 حرفًا كحدّ أقصى الاسم المعروض المترجَم للإحصاءات حسب اللغة المحدّدة
Localized Stat Description اختياري ‫500 حرف كحدّ أقصى وصف الإحصاء المترجَم للغة المحدّدة
مثال على الجدول
رقم تعريف الإحصائية الاسم المعروض للإحصاءات رمز اللغة الاسم المترجَم للإحصاءات (UTF-8) Localized Stat Description (UTF-8)
1 أطول محتوى مطابق es Supervivencia más larga en partidos Esto denota el tiempo de supervivencia de una jugadora en cualquier partido.
1 أطول محتوى مطابق fr Survie du match le plus long Cela indique la durée de survie d'un joueur dans n'importe quel match.
4 إجمالي الذهب الذي تم جمعه es Oro total recolectado La jugadora recoge monedas mientras juega en un partido
4 إجمالي الذهب الذي تم جمعه fr Or total collecté Le joueur collecte des pièces en jouant un match

ملفات الرموز

يجب أن تكون الرموز التي تشير إليها في ملف CSV متوفّرة في أرشيف ZIP الحالي الذي تستورده.

قواعد التحقّق من صحة الرموز هي:

سمة التحقّق القيد أو القاعدة المفروضة
الحد الأقصى لحجم الملف الحد الأقصى لحجم ملف الرمز هو 1 ميغابايت (1,048,576 بايت).
الأبعاد ‫512 × 512 بكسل بالضبط (العرض = 512، الارتفاع = 512)
نسبة العرض إلى الارتفاع ‫1:1 فقط (نسبة عرض إلى ارتفاع مربّعة)
التنسيقات المسموح بها ‫PNG ‏(‎.png) وJPEG ‏(‎.jpg, .jpeg)
الموضع في ملف ZIP يجب أن يكون في الدليل الجذري في ملف ZIP.
التحقّق من الملفات المرجعية يجب أن تكون جميع أسماء ملفات الرموز المحدّدة في أعمدة "اسم ملف الرمز" متوفّرة في ملف ZIP.
التحقّق من وجود أطفال أيتام يجب أن تتم الإشارة إلى جميع ملفات الصور داخل ملف ZIP من خلال إحصاء واحد على الأقل.
التحقّق من التعارض لا يمكن أن تتعارض أسماء ملفات الرموز في ProgressionStatConfig.csv مع RepetitiveStatsConfig.csv.
الصور المكرّرة المرئية يتم وضع علامة على الرموز المكرّرة.

إرشادات رموز الإنجازات

يجب إنشاء الرموز بتنسيق PNG أو JPEG أو JPG بحجم 512 × 512 مع خلفيات شفافة.

يُستخدم الرمز نفسه مع جميع اللغات، لذا ننصحك بعدم تضمين أي نص أو محتوى بلغة معيّنة في الرمز.

مواصفات الوحدة

تتحكّم أعمدة "الوحدة" في كيفية تنسيق قيم الإحصاءات الأولية وتخصيصها للاعبين.

سمات الإحصاءات الرقمية (INT64 وDOUBLE)

Allowed Unit Value مثال على القيمة الأولية
(فارغ) / UNITLESS / NONE 1234567
% / PERCENTAGE / PERCENT 0.857
المسافة/الطول: CENTIMETER وMETER وKILOMETER وFOOT وINCH وMILE وYARD وMILLIMETER وNANOMETER ‫15 (كيلومتر)
السرعة: KILOMETER_PER_HOUR وMETER_PER_SECOND وMILE_PER_HOUR ‫60 (ميل في الساعة)

سمات إحصاءات المدة (DURATION)

قيمة فئة التنسيق القيم المسموح بها للوحدات مثال على القيمة الأولية مثال على الناتج المنسَّق
UNIT_BASED / DURATION مطلوبة: SECOND وMINUTE وHOUR وDAY وWEEK وMONTH وYEAR ‫5,400 ثانية (ساعة) ساعة ونصف
COMPONENT_NUMERIC / HH:MM:SS / CLOCK درجة الدقة (اختيارية، القيمة التلقائية هي WHOLE_SECONDS): WHOLE_MINUTES أو WHOLE_SECONDS أو MILLISECONDS_ONE_DIGIT أو MILLISECONDS_TWO_DIGITS أو MILLISECONDS_THREE_DIGITS ‫3,661 ثانية 01:01:01
COMPONENT_TEXT / TEXT أصغر وحدة (اختيارية، القيمة التلقائية هي SECONDS): SECONDS وMINUTES وHOURS وDAYS وMONTHS وYEARS ‫90,000 ثانية يوم واحد وساعة واحدة

سمات الإحصاءات غير الرقمية (STRING وBOOL)

يجب ترك أعمدة الوحدات فارغة.