آمار بازی

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

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

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

مراحل ادغام

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

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

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

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

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

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

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

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

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

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

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

• رویدادها را به عنوان لحظات خاص درون بازی، تکمیل حلقه بازی یا نقاط عطف پیشرفت تعریف کنید :
  • تکمیل حلقه‌های بازی، مانند یک مسابقه یا اجرای کامل.
  • نقاط عطف پیشرفت، مانند پیشرفت در کاوش منطقه ذخیره شده یا تکمیل یک مرحله.
  • از آنجایی که آمار تکراری باید واقعاً نشان‌دهنده‌ی اقدامات تکرارپذیر یک بازیکن باشند، رویدادهای تعریف‌شده باید با گیم‌پلی اصلی مرتبط باشند.
• ویژگی‌هایی را برای ارائه زمینه در مورد رویداد و نتایج آن اضافه کنید ، مانند شماره سطح، نوع مسابقه، نوع سلاح، تعداد سلاح‌ها، شلیک به سر، سکه‌های جمع‌آوری‌شده، نتیجه مسابقه، زمان دور یا نوع ماشین.
• رویدادهای درون جلسه گیم‌پلی را به محض وقوع ارسال کنید . برای مثال، رویداد تکمیل حلقه بازی را بلافاصله پس از اتمام حلقه ارسال کنید.

رویداد progressUpdate

اگر بازی شما یک مکانیزم پیشرفت اولیه دارد، از این رویداد برای ارسال پیشرفت فعلی بازیکن استفاده کنید. این رویداد یک ویژگی از پیش تعریف شده به نام "currentProgress" از نوع INT یا STRING دارد. انتظار می‌رود که با استفاده از این ویژگی، مقدار فعلی پیشرفت بازیکن در مکانیزم پیشرفت اولیه را ارسال کنید. اگر از این رویداد استفاده می‌کنید، ویژگی از پیش تعریف شده "currentProgress" باید وجود داشته باشد و یک وضعیت پیشرفت باید با استفاده از این ویژگی تعریف شود.

شما می‌توانید ارزش فعلی سایر سیستم‌های پیشرفت در بازی خود مانند lifetime highest score یا current coin balance به عنوان سایر ویژگی‌های این رویداد ارسال کنید.

از آنجایی که بازیکنان می‌توانند پروفایل‌های خود را با پیشرفت فعلی در بازی مقایسه کنند، مهم است که پس از اولین ادغام، هیچ تأخیری در دریافت مقدار پیشرفت فعلی وجود نداشته باشد. برای نمایش دقیق پیشرفت فعلی به بازیکنان، باید رویداد progressUpdate را در ابتدای هر جلسه بازی و همچنین هر زمان که به‌روزرسانی در پیشرفت فعلی وجود دارد، ارسال کنید.

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

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

جزئیات ادغام

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

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

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

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

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

مسیرهای ادغام

دو مسیر ادغام وجود دارد - کلاینت و سرور به سرور.

یکپارچه‌سازی سرور به سرور

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

درخواست HTTP

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

پارامترهای مسیر

مجوز و احراز هویت

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

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

API بک‌اند محدودیت‌های اعتبارسنجی ساختاری دقیقی دارد:

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

درخواست رویدادهای دسته‌ای

به درخواست BatchRecordEventsRequest مراجعه کنید.

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (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").
}

ارزش ملک

// 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 : بدنه درخواست

درخواست رویدادهای دسته‌ای

{
  "packageName": string,
  "requestTime": string,
  "events": [
    {
      object (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 خالی برمی‌گرداند.

مثال بدنه درخواست

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

{
  "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 برای پلتفرم خود، به منابع زیر مراجعه کنید:

• اندروید
• وحدت
• سی++

نقاط عطف