נתונים סטטיסטיים מהמשחק

נתונים סטטיסטיים של המשחק הם נתונים מצטברים על המשחק, שהשחקנים יכולים לראות בפרופיל ב-Play Games שלהם. הנתונים הסטטיסטיים האלה מאפשרים לשחקנים לעקוב אחרי ההתקדמות שלהם לאורך זמן, לראות רגעים חשובים ולהשוות את עצמם לשחקנים אחרים. בעתיד הם ישמשו גם להפעלת תכונות של Google Play כמו משימות, אתגרים חברתיים ועוד.

הנתונים הסטטיסטיים מהמשחק צריכים:

• לא מחייב רכישה (לדוגמה, קניית אבנים יקרות). כלומר, הם לא צריכים להתעדכן כתוצאה מרכישה מתוך האפליקציה.
• לא דורש צפייה במודעות, כלומר לא מתעדכן כתוצאה מצפייה במודעה.
• לא מדובר בשימוש כללי במשחק (לדוגמה, פתיחת המשחק, שימוש בהגדרות).
• לא לכלול מידע אישי ורגיש של משתמשים, כפי שמוגדר במדיניות 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: אירועים שקשורים לשחקנים ואירוע מוגדר מראש שקשור לנתוני התקדמות של שחקנים.

בדוגמאות הבאות אפשר לראות איך נראים אירועים של שחקנים בסוגים שונים של משחקים:

אירועים של נגנים

אירועים של שחקנים מוגדרים לפי רגעים ייחודיים במשחק, השלמות של לולאות משחק או אבני דרך בהתקדמות.

• מגדירים אירועים כרגעים ספציפיים במשחק, כהשלמות של לולאות משחק או כאבני דרך בהתקדמות:
  • השלמות של לולאות משחק, כמו משחק או ריצה שהושלמו.
  • אבני דרך בהתקדמות, כמו התקדמות בחקר אזור שמור או השלמת רמה.
  • מכיוון שנתונים סטטיסטיים שחוזרים על עצמם צריכים לייצג באמת פעולות ששחקן יכול לבצע שוב ושוב, האירועים המוגדרים צריכים להיות משויכים למשחק הליבה.
• מוסיפים מאפיינים כדי לספק הקשר לגבי האירוע והתוצאות שלו, כמו מספר הרמה, סוג ההתאמה, סוג הנשק, מספר הנשקים, פגיעות בראש, מטבעות שנאספו, תוצאת המשחק, זמן ההקפה או סוג המכונית.
• שליחת אירועים במהלך סשן המשחק ברגע שהם מתרחשים. לדוגמה, אפשר לשלוח אירוע של סיום לולאת משחק מיד אחרי שהלולאה מסתיימת.

אירוע אחד (progressUpdate)

אם במשחק יש מכניקת התקדמות ראשית, צריך להשתמש באירוע הזה כדי לשלוח את ההתקדמות הנוכחית של השחקן. לאירוע יש מאפיין מוגדר מראש בשם currentProgress, מסוג INT או STRING. אתם אמורים לשלוח את הערך הנוכחי של התקדמות השחקן במנגנון ההתקדמות העיקרי באמצעות המאפיין הזה. אם משתמשים באירוע הזה, צריך לציין את המאפיין המוגדר מראש currentProgress, ולהגדיר באמצעות המאפיין הזה נתון התקדמות.

אתם יכולים לשלוח את הערך הנוכחי של מערכות התקדמות אחרות במשחק, כמו lifetime highest score או current coin balance, כמאפיינים אחרים של האירוע הזה.

השחקנים יכולים להשוות את הפרופילים שלהם לפי ההתקדמות הנוכחית במשחק, ולכן חשוב שלא יהיה עיכוב בקבלת ערך ההתקדמות הנוכחי אחרי השילוב הראשון. כדי להציג לשחקנים את ההתקדמות הנוכחית בצורה מדויקת, צריך לשלוח את האירוע progressUpdate בתחילת כל סשן משחק וגם בכל פעם שיש עדכון בהתקדמות הנוכחית.

הגדרת הנתונים הסטטיסטיים

תצטרכו להגדיר את הנתונים הסטטיסטיים החוזרים ואת נתוני ההתקדמות על ידי הגדרת הלוגיקה של החישוב והגדרת המידע שיוצג לגבי כל נתון סטטיסטי. בהמשך מופיעות דוגמאות לנתונים סטטיסטיים חוזרים מז'אנרים שונים של משחקים. נתונים סטטיסטיים חוזרים הם בדרך כלל נתונים שמתעדכנים שוב ושוב עבור כל שחקן במספר קטן מאוד (3-4) של סשנים במשחק, והם משויכים ללולאת המשחק המרכזית.

פרטי שילוב

נקודות הקצה של ה-API וה-SDK זמינות לקבלת משוב מוקדם, ויהיו זמינות לכולם (GA) החל מאוגוסט 2026. ציר הזמן

בקטע הזה מוסבר איך ליצור אירועים ולשלוח אותם בשילובים מצד הלקוח ומצד השרת.

מתי כדאי לשלוח נתונים

אירועים שקשורים לשחקן מייצגים פעולות במשחק שקשורות להשלמות של לולאות משחק או לרגעים ספציפיים במשחק. שליחת האירועים האלה ברגע שהם מתרחשים. לדוגמה, כדאי לשלוח את אירוע השלמת ה-Game Loop ברגע שהלולאה מסתיימת.

‫progressUpdate Event מייצג את רמת ההתקדמות הנוכחית של השחקן. צריך לשלוח את הנתונים של סטטוס ההתקדמות באמצעות האירוע הזה במצבים הבאים:

1. בכל פעם שיש עדכון להתקדמות הנוכחית, צריך לשלוח את הערך העדכני ביותר באופן מיידי
2. בכל פעם ששחקן מפעיל את המשחק, כדי לוודא שהנתון הזה קיים עבור השחקן בכל רגע.

נתיבי שילוב

יש שני מסלולים לשילוב – בצד הלקוח ובצד השרת.

שילוב שרת-אל-שרת

נקודת קצה ציבורית של API מאפשרת לשלוח אירועים במטען הייעודי (payload) של הבקשה באמצעות ההגדרות הבאות:

פרמטרים של נתיב

הרשאה ואימות

קריאות API משרת-לשרת פועלות לפי ההנחיות הרגילות של גישה מצד השרת ל-Play Games Services באמצעות OAuth 2.0. הבקשות חייבות לכלול אסימון Bearer עם הרשאה בהיקף https://www.googleapis.com/auth/games.

אירועים: גוף הבקשה

ל-API של השרת העורפי יש מגבלות מחמירות על אימות המבנה:

• גודל האצווה: מקסימום 30 אירועים לכל BatchRecordEventsRequest.
• מספר הנכסים: עד 25 נכסים מותאמים אישית לכל PlayerGameEvent.
• מגבלות אורך: שם האירוע (עד 100 תווים), מפתחות הנכס (עד 100 תווים) וערכי המחרוזת של הנכס (עד 1,024 תווים).
• מזהה האירוע: חייב להיות מחרוזת UUID עם 36 תווים.
• ניסיון חוזר ושימוש במטמון: אם ה-API נכשל, מומלץ להימנע משמירת נתונים במטמון או משמירה של יותר מדי אירועים באופן מקומי, כי ניסיונות חוזרים לשליחת מנות של יותר מ-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 event: Request Body

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++‎

אבני דרך