آمار بازی

«آمار بازی» آمار تجمعی مربوط به بازی شما است که بازیکنان می‌توانند آن را در نمایه بازیکن خود مشاهده کنند. این آمار به بازیکنان امکان می‌دهد روند پیشرفت خود را در طول زمان ردگیری کنند، لحظات برجسته را ببینند، و عملکردشان را با بازیکنان دیگر مقایسه کنند. این آمار همچنین می‌تواند در آینده ویژگی‌های Google Play مانند «مأموریت‌ها»، «چالش‌های اجتماعی»، و غیره را بهبود دهد.

آمار بازی باید:

  • نیازی به خرید نداشته باشد (برای مثال، خرید جواهرات) یعنی نباید درنتیجه هیچ خرید درون‌برنامه‌ای به‌روز شود.
  • نیازی به تماشای آگهی نداشته باشد، یعنی نباید درنتیجه تماشای آگهی به‌روز شود.
  • استفاده عمومی از بازی نباشد (برای مثال، باز کردن بازی؛ استفاده از تنظیمات).
  • نباید حاوی «داده‌های شخصی و حساس کاربر» (طبق تعریف «خط‌مشی Play») باشد، ازجمله شناسه‌های کاربر، گذرواژه‌ها، داده‌های دقیق مکان یا سلامت، یا هرگونه محتوای توهین‌آمیز، ناسزا، محتوای صریح جنسی، خشونت‌آمیز، یا تنفرآمیز.
  • برای همه کاربران دردسترس باشد (برای مثال، کنش مختص تیم نباشد یا فقط برای کاربران سطح خاصی دردسترس باشد یا به عملیات زنده با زمان محدود و غیره محدود باشد)

تصویر «آمار بازی» را در «نمایه بازیکن» در برگه شما نشان می‌دهد. این میانای کاربر (UI) در برگه شما فقط برای اهداف آزمایشی دردسترس است. رابط کاربری «آمار بازی» در سپتامبر ۲۰۲۶ دردسترس قرار خواهد گرفت.

«آمار بازی» در برگه «شما»
«آمار بازی» با برگزیده‌ها در برگه «شما».

نوع انبوهش

نوع انبوهش به Google Play می‌گوید که چگونه یک آمار را از مقادیر هر رویداد که ارسال می‌کنید محاسبه کند:

  • SUM: برای آمار تجمعی (مانند کل سکه‌های جمع‌آوری‌شده، کل آسیب واردشده) استفاده کنید. بازی باید مقدار مجزای کسب‌شده درطول هر نمونه رویداد را ارسال کند.
  • COUNT: برای آماری که نشان‌دهنده تعداد دفعات وقوع یک رویداد است استفاده می‌شود (مانند بازی‌های انجام‌شده، بازی‌های برده‌شده). بازی باید نمونه‌های وقوع رویداد گسسته را ارسال کند.
  • MAX: فقط برای دستاوردهای اوج تک‌رخدادی استفاده کنید (مانند بالاترین امتیاز در یک دور، حداکثر رگه ترکیبی، یا بالاترین آسیب در یک مسابقه). از MAX به‌عنوان راه‌حل موقت برای نمایش مجموع کل طول عمر از مقادیر جاری ازپیش محاسبه‌شده استفاده نکنید.

الزامات پیاده‌سازی مهم برای آمار تکراری

  • ارسال مقادیر هر رویداد: برای هر رویداد، فقط آنچه را در آن رویداد اتفاق افتاده است ارسال کنید، مثلاً سکه‌های جمع‌آوری‌شده در یک دور بازی. سپس نوع انبوهش را، مثل «مجموع» یا «تعداد»، در پیکربندی آمار تنظیم کنید. این کار تضمین می‌کند که آمار تکراری در مکانیک‌های تعامل قابل‌استفاده مجدد باشد و به Google Play اجازه می‌دهد تجربه‌های مناسبی برای بازیکن ایجاد کند.
  • مجموع مادام‌العمر را ارسال نکنید: برای مثال، کل سکه‌هایی را که بازیکن در کلاینت یا سرور بازی شما جمع‌آوری کرده است ردیابی نکنید و آن مجموع را با انبوهش MAX ارسال نکنید. این آمار همچنان در واسط کاربری «نمایه بازیکن» نشان داده خواهد شد، اما Google Play نمی‌تواند از آن‌ها برای تقویت ویژگی‌های پاداش‌دهی مانند لیگ‌ها، مأموریت‌ها، و سرعت‌ها برای بهبود تجربه بازیکن و ایجاد تأثیر برای بازی شما استفاده کند.

برای دستورالعمل‌ها و نمونه‌های مدل‌سازی صحیح رویداد، به رویدادهای بازیکن و پیکربندی آمار مراجعه کنید.

مراحل یکپارچه‌سازی

داده‌ها را بااستفاده از Game Stats API به‌عنوان رویدادهای بازیکن برای آمار تکراری و رویداد ازپیش تعریف‌شده progressUpdate برای آمار پیشرفت ارسال کنید. همچنین باید منطق محاسبه آماری را که در نمایه «بازیکن» و اطلاعات نمایشی آن ظاهر می‌شود پیکربندی کنید.

رویدادهای بازیکن نشان‌دهنده لحظات متمایز درون بازی، تکمیل حلقه‌های بازی، یا نقاط عطف پیشرفت هستند.

رویداد بازیکن به‌صورت زیر تعریف و مدل‌سازی می‌شود:

  1. رویداد با کنش خاصی که بازیکن انجام می‌دهد نشان داده می‌شود، مثلاً تکمیل مسابقه، تمام کردن دویدن، باز کردن صندوقچه، یا ذخیره کردن پیشرفت در یک منطقه.
  2. هر کنش به نتایج خاصی منجر می‌شود یا ویژگی‌های خاصی دارد که آن کنش را تعریف می‌کند. این‌ها به‌عنوان ویژگی‌های رویداد مدل‌سازی می‌شوند که بافت رویداد و نتایج خاص آن را ارائه می‌دهند (برای مثال، نوع مسابقه، سکه‌های جمع‌آوری‌شده درطول آن اجرا، نتیجه مسابقه، یا تعداد شلیک به سر).

ادغام شامل مراحل زیر است:

  • تعریف طرح‌واره داده‌های خام: رویدادهای بازیکن را بااستفاده از بارگذاری CSV در «کنسول Play» تعریف کنید. ایجاد رویداد را ببینید.
  • ادغام با Game Stats API: داده‌های خام بازیکن را در قالب اعلام‌شده برای رویدادهای بازیکن و رویداد progressUpdate ارسال کنید.
    • همه رویدادهای تعریف‌شده را بااستفاده از ادغام سمت کارخواه یا سمت سرور ارسال کنید. برای اطلاعات بیشتر، نمونه‌های رویدادهای بازیکن و رویداد progressUpdate را ببینید.
  • بارگذاری فایل ZIP: ۳ فایل CSV و همه فایل‌های تصویری نماد را که ۵ آمار تکراری و ۱ سطح پیشرفت بازیکن را تعریف می‌کنند ارائه دهید. برای اطلاعات بیشتر، رهنمودهای فایل ZIP را ببینید. جزئیات زیر را اضافه کنید:
    • فایل CSV برای آمار تکراری:
      • شناسه یکتا برای آمار.
      • برچسب رویداد را برای استفاده در محاسبه آمار مشخص کنید. نمی‌توانید از برچسب رویداد progressUpdate در اینجا استفاده کنید.
        • برچسب دارایی را برای استفاده در محاسبه آمار مشخص کنید. این باید دارایی رویداد مشخص‌شده باشد.
        • نوع انبوهش (مجموع، بیشینه، کمینه، یا تعداد) را مشخص کنید تا نحوه محاسبه آمار در برچسب دارایی انتخاب‌شده تعیین شود.
        • شرط فیلتر اختیاری را مشخص کنید تا منطق فقط زمانی محاسبه شود که شرط برآورده شده باشد. برچسب رویداد و ویژگی، اپراتور (=، <، <=، >=، یا >)، و مقدار آستانه را تعریف کنید.
      • پرچم بولی اضافه کنید تا نشان دهد آیا می‌توان از آمار برای ویژگی‌های رقابتی استفاده کرد یا نه.
      • اگر از این ویژگی بتوان برای ویژگی‌های رقابتی استفاده کرد، دراین‌صورت حدود ساعتی کمینه و بیشینه برای بازیکن واقعی. از این اطلاعات برای شناسایی بازیکنانی استفاده می‌کنیم که ممکن است هنگام شرکت در ویژگی‌هایی مثل لیگ‌ها و چالش‌های اجتماعی سوءاستفاده کنند.
      • نام نمایشی یکتایی برای آمار ارائه دهید که بازیکنان می‌بینند.
      • نوشتار منحصربه‌فردی برای توصیف آمار ارائه دهید. این شرح باید جزئیاتی درباره نحوه کسب آن توسط بازیکن ارائه دهد و در واسط کاربر «نمایه بازیکن» به بازیکنان نشان داده خواهد شد.
      • با وارد کردن نام دقیق فایل نماد در فایل CSV، نماد یکتایی برای نمایش آمار ارائه دهید.
      • ورودی اختیاری‌ای ارائه دهید که نشان دهد آیا مقدار افزایشی یا مقدار کاهشی برای بازیکن خوب است. این ورودی برای جشن گرفتن حرکات بازیکن استفاده خواهد شد.
      • واحد اندازه‌گیری اختیاری برای آمار ارائه دهید، مثلاً کیلومتر، مایل، و ثانیه.
    • فایل CSV برای آمار پیشرفت بازیکن:
      • نام نمایشی یکتایی برای پیشرفت بازیکن ارائه دهید که بازیکنان آن را ببینند.
      • نماد یکتایی برای نمایش آمار ارائه دهید.
      • شرحی برای آمار پیشرفت ارائه دهید.
      • ورودی اختیاری‌ای ارائه دهید که نشان دهد آیا مقدار افزایشی یا مقدار کاهشی برای بازیکن خوب است. این ورودی فقط زمانی برای جشن گرفتن حرکات بازیکن استفاده می‌شود که ویژگی currentProgress از نوع INT باشد.
      • واحد اندازه‌گیری اختیاری برای آمار ارائه دهید، مثلاً کیلومتر، مایل، ثانیه.
    • فایل CSV برای بومی‌سازی: نام‌های نمایشی بومی‌سازی‌شده را برای همه آمارها ارائه دهید.
      • برای هر بومی‌سازی یک ردیف اضافه کنید.
      • از رشته نام نمایشی آمار که در CSV قبلی اضافه شده است استفاده کنید تا آمار را به‌طور یکتا در مقابل بومی‌سازی‌ای که اضافه می‌شود شناسایی کنید.
      • زبان را از فهرست کدهای زبان مشخص کنید.
      • بومی‌سازی را برای نام نمایشی به زبان مشخص‌شده اضافه کنید.
      • بومی‌سازی را برای شرح آمار به زبان مشخص‌شده اضافه کنید.

طرح‌واره را برنامه‌ریزی کنید

بااستفاده از Game Stats API می‌توانید دو نوع داده ارسال کنید: رویدادهای بازیکن و رویداد ازپیش‌تعریف‌شده برای آمار پیشرفت بازیکن.

مثال‌های زیر نشان می‌دهند که رویدادهای بازیکن در انواع مختلف بازی چگونه به‌نظر می‌رسند:

رویدادهای بازیکن

«رویدادهای بازیکن» با لحظات متمایز درون بازی، تکمیل حلقه‌های بازی، یا نقاط عطف پیشرفت تعریف می‌شوند.

  • رویدادها را به‌عنوان لحظات خاص درون بازی، تکمیل حلقه‌های بازی، یا نقاط عطف پیشرفت تعریف کنید:
    • تکمیل حلقه بازی، مثل مسابقه یا اجرای تکمیل‌شده.
    • نقاط عطف پیشرفت، مانند پیشرفت کاوش منطقه ذخیره‌شده یا سطح تکمیل‌شده.
    • ازآنجایی‌که آمار تکرارشونده باید واقعاً نشان‌دهنده کنش‌های تکرارپذیر بازیکن باشد، رویدادهای تعریف‌شده باید با شیوه بازی اصلی مرتبط باشد.
  • ویژگی‌هایی اضافه کنید تا زمینه‌ای درباره رویداد و نتایج آن ارائه دهید، مانند شماره سطح، نوع مسابقه، نوع سلاح، تعداد سلاح‌ها، شلیک به سر، سکه‌های جمع‌آوری‌شده، نتیجه مسابقه، زمان دور، یا نوع خودرو.
  • رویدادها را درطول جلسه بازی به‌محض وقوع ارسال کنید. برای مثال، بلافاصله پس‌از تکمیل حلقه بازی، رویداد تکمیل حلقه بازی را ارسال کنید.
مثال‌ها
نوع بازی برچسب رویداد لحظه درون‌بازی / تکمیل رویداد پیشرفت / تکمیل حلقه بازی نتیجه خصوصیات
بازی جورچین مستقل با پیشرفت خطی chapter_completed تکمیل رویداد پیشرفت موجود نیست شماره فصل، نام فصل، تعداد تلاش‌ها، تعداد صفحه‌ها، تعداد حرکت‌ها، محتوای فصل
screen_completed تکمیل رویداد پیشرفت شماره فصل، نام فصل، تعداد تلاش‌ها، تعداد حرکت‌ها، محتوای فصل
دونده بی‌پایان سه‌بعدی run_completed تکمیل حلقه بازی سکه‌های جمع‌آوری‌شده، امتیاز مدت زمان دویدن، سکه‌های جمع‌آوری‌شده از جت‌پک، تقویت‌کننده استفاده‌شده در شروع دویدن، تخته‌های موج‌سواری استفاده‌شده، آهنرباهای استفاده‌شده، جامپر استفاده‌شده، جت‌پک استفاده‌شده
بازی نقش‌آفرینی اکشن دنیای باز areaExplorationProgress تکمیل رویداد پیشرفت دشمنان شکست خوردند، معجون‌ها جمع‌آوری شدند شماره منطقه، نام منطقه، درصد پیشرفت
questCompleted تکمیل حلقه بازی موجود نیست نام مأموریت
weaponUnlocked لحظه درون‌بازی موجود نیست Weapon Name, Weapon Level
chestUnlocked لحظه درون‌بازی سنگ معدن بهبود جمع‌آوری شد
پازل معمولی با متا تزئینی puzzleCompleted تکمیل حلقه بازی / تکمیل رویداد پیشرفت سکه‌های جمع‌آوری‌شده، تقویت‌کننده‌های جمع‌آوری‌شده تعداد حرکت‌ها، از هدیه پیشخدمت استفاده شده است؟، نوع سطح، شماره سطح، تقویت‌کننده‌های رنگ استفاده‌شده، دینامیت‌های استفاده‌شده
کارت‌های جمع‌آوری‌شده لحظه درون‌بازی کارت‌های ۱ ستاره، کارت‌های ۲ ستاره، کارت‌های ۳ ستاره، کل کارت‌ها شماره آلبوم، نام آلبوم
مسابقه آرکید raceCompleted تکمیل حلقه بازی رتبه، NOS استفاده‌شده، race_time نوع مسابقه، رده‌بندی، car_used
carUpgraded لحظه درون‌بازی ویژگی خودرو که ارتقا یافته است، سطح / مقدار قدیمی، سطح / مقدار جدید نوع خودرو، سطح گاراژ فعلی
تیرانداز نبرد سلطنتی سوم شخص matchCompleted تکمیل حلقه بازی حذفی، عکس سر، مقدار افتخاری نوع مسابقه، زمان بقا
شبیه‌سازی مدیریت ورزش‌های الکترونیک matchCompleted تکمیل حلقه بازی نتیجه، گل‌های زده‌شده، گل‌ها نام تیم حریف، نام تیم بازی‌کننده
trainingCompleted لحظه درون‌بازی Drills done, 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`
بازی جورچین پیشرفت خطی Current Chapter Number Or Level Number
دونده بی‌پایان سه‌بعدی امتیاز بالا، موجودی فعلی افزاینده‌ها
جورچین تفننی شماره سطح فعلی، تعداد بردهای اولین تلاش، تعداد مناطق تکمیل‌شده، تعداد مجموعه‌های تکمیل‌شده
مسابقه آرکید شماره سطح فعلی، موجودی ارز
بازی نقش‌آفرینی اکشن دنیای باز رتبه فعلی شخصیت، شماره سطح فعلی
تیرانداز سوم شخص شماره سطح فعلی
شبیه‌سازی ورزش الکترونیک Manager Level number, Club Level number

پیکربندی آمار

باید آمار تکراری و پیشرفت خود را با تعریف منطق محاسباتی و نمایش اطلاعات مربوط به هر آمار پیکربندی کنید. نمونه‌هایی از آمار تکراری از ژانرهای مختلف بازی در زیر آورده شده است. آمار تکراری معمولاً آماری است که به‌طور مکرر برای هر بازیکن در تعداد بسیار کمی (۳ تا ۴) جلسه بازی به‌روز می‌شود و با حلقه اصلی بازی مرتبط است.

برای آشنایی با زمان استفاده از SUM،‏ COUNT، یا MAX، انتخاب نوع انبوهش مناسب را ببینید.

نام بازی نام نمایشی آمار بازی ویژگی رویداد منطق محاسبه [انبوهش] فیلتر
دونده بی‌پایان سه‌بعدی اجراها تکمیل شد هر ویژگی رویداد run_completed شمارش همه مقادیر [بدون فیلتر]
سکه‌های جمع‌آوری‌شده خصوصیت Coins_collected از رویداد run_completed مجموع موجود نیست
کلیدهای جمع‌آوری‌شده ویژگی Keys_collected از رویداد run_completed مجموع موجود نیست
بالاترین امتیاز ران خصوصیت امتیاز رویداد run_completed حداکثر موجود نیست
اجراهای با سکه زیاد تکمیل شد خصوصیت Coins_collected رویداد run_completed شمارش مقدار > ۵۰۰۰
بازی جورچین پیشرفت خطی فصل‌های تکمیل‌شده هر ویژگی رویداد 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 شمارش مقدار = ۱۰۰
قفل شمشیرها باز شد ویژگی Weapon_type از رویداد weapon_unlocked شمارش مقدار = «شمشیر»
دشمنان شکست‌خورده خصوصیت Enemies_defeated از رویداد area_exploration_progress مجموع موجود نیست
معجون‌های سلامتی جمع‌آوری‌شده خصوصیت Enhancement_ores رویداد chest_unlocked مجموع موجود نیست
جورچین تفننی سطوح تکمیل‌شده هر ویژگی از رویداد level_completed شمارش همه مقادیر [بدون فیلتر]
سطوح تکمیل‌شده در اولین تلاش خصوصیت Num_try رویداد level_completed شمارش مقدار = ۱
تقویت‌کننده‌های رنگ استفاده‌شده ویژگی Color_booster_used از رویداد level_completed مجموع موجود نیست
تقویت‌کننده‌های بمب استفاده‌شده ویژگی Bomb_booster_used از رویداد level_completed مجموع موجود نیست
کارت‌های جمع‌آوری‌شده ویژگی Total_cards از رویداد cards_collected مجموع موجود نیست
مسابقه آرکید مسابقه برده ویژگی رتبه رویداد race_completed شمارش مقدار = ۱
سریع‌ترین مسابقه خصوصیت race_time از رویداد race_completed حداقل موجود نیست
NOS استفاده‌شده خصوصیت NOS_used از رویداد race_completed مجموع موجود نیست
مسابقات به‌پایان‌رسیده با Mustang ویژگی Car_type از رویداد race_completed شمارش Value = "Mustang"
ارتقای خودرو هر ویژگی رویداد car_upgraded شمارش همه مقادیر [بدون فیلتر]
تیرانداز نبرد سلطنتی سوم شخص مسابقات برده‌شده هر ویژگی رویداد match_completed شمارش Match_result = TRUE
کل حذفی‌ها خصوصیت Eliminations (حذف‌ها) برای رویداد match_completed (مسابقه_تکمیل_شد) مجموع موجود نیست
بیشترین زمان بقا خصوصیت Survival_time رویداد match_completed حداکثر موجود نیست
تعداد کل عکس‌های چهره ویژگی Headshots رویداد match_completed مجموع موجود نیست
ارزش کل مهارت ویژگی Skill_value رویداد match_completed مجموع موجود نیست
شبیه‌سازی مدیریت ورزش‌های الکترونیک مسابقات برده‌شده خصوصیت نتیجه رویداد match_completed شمارش نتیجه = «برنده»
مجموع گل‌های زده‌شده ویژگی Goals_scored از رویداد match_completed مجموع موجود نیست
مسابقات سخت برده‌شده خصوصیت نتیجه رویداد hard_match_completed شمارش نتیجه = «برنده»
برد با بیشترین تفاضل گل خصوصیت Goal_difference رویداد match_completed حداکثر نتیجه = «برنده»
کل تمرین‌های آموزشی خصوصیت Drills_done از رویداد training_completed مجموع موجود نیست
مجموع آموزش‌های تکمیل‌شده هر ویژگی رویداد training_completed شمارش موجود نیست

جزئیات یکپارچه‌سازی

این بخش نشان می‌دهد که چگونه رویدادها را بسازید و آن‌ها را در ادغام‌های سمت کارخواه و سمت سرور ارسال کنید.

چه زمانی باید داده ارسال کنید

رویدادهای بازیکن نشان‌دهنده کنش‌های درون‌بازی مربوط به تکمیل حلقه‌های بازی یا لحظات خاص درون‌بازی است. این رویدادها را به‌محض وقوع ارسال کنید. برای مثال، رویداد تکمیل حلقه بازی را به‌محض تکمیل حلقه ارسال کنید.

progressUpdate رویداد نشان‌دهنده سطح پیشرفت فعلی بازیکن است. داده‌های آمار پیشرفت باید بااستفاده از این رویداد در شرایط زیر ارسال شود:

  1. هرزمان که به‌روزرسانی‌ای برای پیشرفت فعلی وجود دارد، آخرین مقدار را فوراً ارسال کنید
  2. هرزمان که بازیکن بازی را راه‌اندازی می‌کند تا از وجود این آمار برای بازیکن در همه زمان‌ها اطمینان حاصل شود.

مسیرهای یکپارچه‌سازی

دو مسیر برای ادغام وجود دارد - کارخواه و سرور به سرور.

ادغام سرور به سرور

یک نقطه پایانی API عمومی به شما امکان می‌دهد رویدادها را در محموله درخواست بااستفاده از پیکربندی‌های زیر ارسال کنید:

درخواست HTTP

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

پارامترهای مسیر
پارامتر نوع داده شرح
playerId رشته شناسه «خدمات بازی‌های Play» بازیکن.

صدور مجوز و اصالت‌سنجی

فراخوانی‌های میانای برنامه‌سازی کاربردی سرور به سرور از دستورالعمل‌های استاندارد دسترسی سمت سرور به «سرویس‌های بازی‌های Play» بااستفاده از OAuth 2.0 پیروی می‌کنند. درخواست‌ها باید شامل رمزیاب دارنده مجاز با دامنه https://www.googleapis.com/auth/games باشد.

رویدادها: متن درخواست

میانای برنامه‌سازی کاربردی باطن محدودیت‌های اعتبارسنجی ساختاری سخت‌گیرانه‌ای دارد:

  • اندازه دسته: حداکثر ۳۰ رویداد در هر BatchRecordEventsRequest.
  • تعداد ویژگی: حداکثر ۲۵ ویژگی سفارشی برای هر PlayerGameEvent.
  • محدودیت‌های طول: نام رویداد (حداکثر ۱۰۰ نویسه)، کلیدهای دارایی (حداکثر ۱۰۰ نویسه)، و مقادیر رشته دارایی (حداکثر ۱۰۲۴ نویسه).
  • شناسه رویداد: باید رشته UUID معتبر ۳۶ نویسه‌ای باشد.
  • امتحان مجدد و ذخیره در حافظه نهان: اگر API ناموفق بود، از ذخیره در حافظه نهان یا انباشتن رویدادهای بیش‌ازحد به‌صورت محلی خودداری کنید، زیرا امتحان مجدد دسته‌ای که بیش‌از ۳۰ رویداد باشد رد خواهد شد. همیشه تلاش‌های مجدد را تکه‌تکه کنید تا محدودیت اندازه دسته رعایت شود.

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
      }
    }
  ]
}

پیاده‌سازی‌های کارخواه

برای آشنایی با پیاده‌سازی کارخواه «آمار بازی» برای پلاتفرمتان، منابع زیر را ببینید:

نقاط عطف

تاریخ ادغام Game Stats API پیکربندی «آمار بازی»
سپتامبر ۲۰۲۶ موجود نیست بازیکنان آمار بازی را در «نمایه بازیکن» خود می‌بینند.