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

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

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

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

הערה: אפשר להגדיר עד 50 נתונים סטטיסטיים למשחק.

בתמונה מוצגים הנתונים הסטטיסטיים של המשחק בפרופיל הגיימר בכרטיסייה אני. ממשק המשתמש (UI) בכרטיסייה הדף שלי זמין למטרות בדיקה בלבד. ממשק המשתמש של הנתונים הסטטיסטיים של המשחק יהיה זמין בספטמבר 2026.

הנתונים הסטטיסטיים של המשחק עם רגעי השיא בכרטיסייה "הדף שלי".

סוג צבירה

סוג הצבירה מציין ל-Google Play איך לחשב נתון סטטיסטי מהערכים לכל אירוע שאתם שולחים:

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

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

פעולות במשחק

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

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

אל תשלחו סכומים מצטברים שחושבו מראש.

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

• הטמעה שגויה (לא לעשות את זה): שמירה של סכום המטבעות שנאספו במהלך כל משך החיים של הלקוח או השרת (לדוגמה, `total_coins_collected = 10,450`) והפעלת אירוע עם הסכום שחושב מראש באמצעות צבירת MAX.
• דוגמה להטמעה נכונה: מפעילים אירוע run_completed בסוף כל ריצה עם המאפיין coins_collected = 45 (מטבעות שנאספו בריצה הספציפית הזו) ומגדירים נתון סטטיסטי באמצעות צבירת SUM.

דוגמאות

סוג המשחק	תווית האירוע	רגע במשחק / השלמת אירוע התקדמות / השלמת Game Loop	תוצאה	מאפיינים
משחק חשיבה אינדי עם התקדמות לינארית	chapter_completed	השלמת אירוע התקדמות	לא רלוונטי	מספר הפרק, שם הפרק, מספר הניסיונות, מספר המסכים, מספר המהלכים, תוכן הפרק
	screen_completed	השלמת אירוע התקדמות		מספר הפרק, שם הפרק, מספר הניסיונות, מספר המהלכים, תוכן הפרק
משחק ריצה אינסופית בתלת-ממד	run_completed	השלמת Game Loop	מטבעות שנאספו, ניקוד	משך הריצה, מטבעות שנאספו באמצעות תיק סילון, בוסטר שנעשה בו שימוש בתחילת הריצה, גלשנים שנעשה בהם שימוש, מגנטים שנעשה בהם שימוש, ג'אמפר שנעשה בו שימוש, תיק סילון שנעשה בו שימוש
משחק תפקידים-פעולה בעולם פתוח	areaExplorationProgress	השלמת אירוע התקדמות	אויבים שהובסו, שיקויים שנאספו	מספר האזור, שם האזור, אחוז ההתקדמות
	questCompleted	השלמת Game Loop	לא רלוונטי	שם הקווסט
	weaponUnlocked	רגע במשחק	לא רלוונטי	שם הנשק, רמת הנשק
	chestUnlocked	רגע במשחק	נאספה עפרה לשיפור
משחק חשיבה קליל עם מטא-משחק דקורטיבי	puzzleCompleted	השלמת לולאת משחק / השלמת אירוע התקדמות	מטבעות שנאספו, בוסטרים שנאספו	מספר המהלכים, האם נעשה שימוש במתנה של המשרת?, סוג השלב, מספר השלב, מספר הבוסטרים הצבעוניים שנעשה בהם שימוש, מספר הדינמיטים שנעשה בהם שימוש
	cardsCollected	רגע במשחק	קלפים עם כוכב אחד, קלפים עם 2 כוכבים, קלפים עם 3 כוכבים, סה"כ קלפים	מספר האלבום, שם האלבום
מרוצי ארקייד	raceCompleted	השלמת Game Loop	דירוג, שימוש ב-NOS, זמן_מרוץ	סוג המרוץ, דירוג, המכונית שבה השתמשו
	carUpgraded	רגע במשחק	מאפיין הרכב ששודרג, רמה / ערך ישנים, רמה / ערך חדשים	סוג הרכב, הקומה הנוכחית בחניון
משחק יריות באטל רויאל בגוף שלישי	matchCompleted	השלמת Game Loop	פסילות, פגיעות בראש, ערך כבוד	סוג המשחק, זמן ההישרדות
סימולטור לניהול ספורט אלקטרוני	matchCompleted	השלמת Game Loop	תוצאה, שערים שהובקעו, שערים	שם הקבוצה היריבה, שם הקבוצה המשחקת
	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) של סשנים של משחק, והם משויכים ל-game loop הראשי.

כדי לדעת מתי להשתמש ב-SUM, ב-COUNT או ב-MAX, קראו את המאמר בחירת סוג הצבירה המתאים.

שם המשחק	השם המוצג של הנתון הסטטיסטי של המשחק	מאפיין אירוע	לוגיקת החישוב [aggregation]	סינון
משחק ריצה אינסופי בתלת-ממד	ההרצות הושלמו	כל מאפיין של האירוע run_completed	מספר כולל	כל הערכים [בלי פילטר]
	מטבעות שנאספו	המאפיין Coins_collected של האירוע run_completed	סכום	לא רלוונטי
	מפתחות שנאספו	המאפיין Keys_collected של האירוע run_completed	סכום	לא רלוונטי
	הציון הגבוה ביותר בריצה	מאפיין הניקוד של האירוע run_completed	מקסימום	לא רלוונטי
	השלמת ריצות עם הרבה מטבעות	המאפיין Coins_collected של האירוע run_completed	מספר כולל	ערך > 5,000
משחק חשיבה עם התקדמות לינארית	פרקים שהושלמו	כל מאפיין של האירוע 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	סכום	לא רלוונטי
	מרוצים שהסתיימו עם מוסטנג	המאפיין 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	מספר כולל	Result = "Won"
	סה"כ שערים שהובקעו	המאפיין Goals_scored של האירוע match_completed	סכום	לא רלוונטי
	ניצחונות במשחקים במגרש קשה	מאפיין התוצאה של האירוע hard_match_completed	מספר כולל	Result = "Won"
	הניצחון עם הפרש השערים הגבוה ביותר	המאפיין Goal_difference של האירוע match_completed	מקסימום	Result = "Won"
	מספר תרגילי האימון הכולל	המאפיין Drills_done של האירוע training_completed	סכום	לא רלוונטי
	מספר ההדרכות הכולל שהושלמו	כל מאפיין של האירוע training_completed	מספר כולל	לא רלוונטי

פרטי שילוב

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

מתי צריך לשלוח נתונים

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

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

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

נתיבי שילוב

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

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

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

בקשת HTTP

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

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

פרמטר	סוג נתונים	תיאור
playerId	מחרוזת	מזהה ה-PGS של השחקן.

הרשאה ואימות

קריאות ל-API משרת לשרת פועלות לפי ההנחיות הרגילות של גישה מצד השרת ל-Play Games Services באמצעות OAuth 2.0. הבקשות חייבות לכלול טוקן למוכ"ז (Bearer token) שהורשה באמצעות ההיקף 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: גוף הבקשה

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

אבני דרך

תאריך	שילוב נתונים סטטיסטיים של המשחק API	הגדרות הנתונים הסטטיסטיים של המשחק
ספטמבר 2026	לא רלוונטי	השחקנים מתחילים לראות את הנתונים הסטטיסטיים של המשחק בפרופיל שלהם ב-Play Games.