דף זה תורגם על ידי Cloud Translation API.

מעורבות ב-SDK תחומים אחרים: הוראות לשילוב טכני של צד שלישי

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

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

פרטי השילוב

טרמינולוגיה

השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, מומלצים והמשך.

באשכולות Recommendation יוצגו הצעות בהתאמה אישית של מפתח שותף. זוהי תצוגה של ממשק המשתמש שמכילה קבוצה של המלצות מאותו שותף פיתוח.
- ArticleEntity: ArticleEntity שמייצג המלצה מבוססת-טקסט לתוכן שרלוונטי ליותר מקטגוריית תוכן אחת. הפריט ArticleEntity מאפשר למפתחים לספק מגוון תוכן של טקסט ותמונות עם יותר מטא-נתונים כדי להבהיר את המידע למשתמשים, בהשוואה ל-GenericFeaturedEntity. דוגמה: תוכן שיווקי, קטע מידע חדשותי
  
  תרשים 1: ממשק משתמש שבו מוצג אובייקט ArticleEntity יחיד באשכול ההמלצות.
- EventEntity: רכיב EventEntity מייצג אירוע שיתרחש בעתיד. שעת ההתחלה של האירוע היא פרט קריטי שצריך להעביר למשתמשים.
  
  איור 2: ממשק משתמש שבו מוצג אובייקט EventEntity יחיד באשכול ההמלצות.
- LodgingEntity: LodgingEntity מייצג מקום לינה, כמו מלון, דירה, בית נופש להשכרה לטווח קצר ולטווח ארוך.
  
  איור 3: ממשק משתמש שבו מוצגת ישות LodgingEntity אחת באשכול ההמלצות.
- StoreEntity: הנכס StoreEntity מייצג חנות, מסעדה, בית קפה וכו'. הוא מדגיש תוכן שבו מקום אוכל או חנות הם פרטי המידע החשובים ביותר שצריך להעביר למשתמשים.
  
  איור 4: ממשק משתמש שבו מוצג אובייקט StoreEntity יחיד בתוך אשכול ההמלצות.
- PointOfInterestEntity: ה-PointOfInterestEntity מייצג נקודת עניין, כמו תחנת דלק, מקום אירוע, פארק שעשועים, מוזיאון, אטרקציה תיירותית, שביל הליכה וכו'. הוא מדגיש תוכן שבו המיקום הוא פריט מידע קריטי שצריך להעביר למשתמשים. אין להשתמש בו ללינה, לחנות או לחדר אוכל.
  
  איור 5: ממשק משתמש שבו מוצג אובייקט PointOfInterestEntity יחיד באשכול ההמלצות.
- PersonEntity: רכיב PersonEntity מייצג אדם. ההמלצות יכולות להיות להדגיש אדם בקטגוריות כמו בריאות וכושר, ספורט, דייטינג וכו'.
  
  איור 5: ממשק משתמש שבו מוצג אובייקט PersonEntity יחיד בתוך אשכול ההמלצות.
באשכול Continuation מוצג תוכן של משתמשים מכמה מפתחים שהצטרפו לאחרונה לקבוצה אחת של ממשק משתמש. כל שותף מפתח יוכל לשדר עד 10 ישויות באשכול Continuation.

תוכן ההמשך יכול להיות במבנה הבא:
- ArticleEntity: ArticleEntity שמייצג המלצה מבוססת-טקסט לתוכן שרלוונטי ליותר מקטגוריית תוכן אחת. אפשר להשתמש בישות הזו כדי לייצג כתבות חדשותיות או תוכן אחר שהמשתמש רוצה להמשיך לצרוך מהמקום שבו הוא יצא. דוגמה: תוכן שיווקי, קטע מידע חדשותי
  
  איור 6. ממשק משתמש שבו מוצג אובייקט ArticleEntity יחיד בתוך אשכול Continuation.
- RestaurantReservationEntity: הישות RestaurantReservationEntity מייצגת הזמנה למסעדה או לבית קפה, ומאפשרת למשתמשים לעקוב אחרי הזמנות קיימות או עתידיות למסעדות.
  
  איור 7. ממשק משתמש שמוצגת בו ישות אחת הזמנת מקום בתוך אשכול המשך.
- EventReservationEntity: ה-EventReservationEntity מייצג הזמנה לאירוע, ועוזר למשתמשים לעקוב אחרי הזמנות לאירועים קרובים או מתמשכים. האירועים יכולים לכלול, בין היתר:
  - אירועי ספורט, כמו הזמנה למשחק כדורגל
  - אירועי גיימינג כמו הזמנת מקום לספורט אלקטרוני
  - אירועי בידור, כמו הזמנה לסרט בקולנוע, הופעה, הצגה בתיאטרון, חתימה על ספר
  - הזמנות לנסיעות או למקומות מעניינים, כמו סיורים מודרכים וכרטיסים למוזיאונים
  - הזמנות לרשתות חברתיות / לקורס / כנסים
  - הזמנות של סשנים של הדרכה או לימוד
  איור 8. ממשק משתמש שבו מוצגת ישות אחת מסוג EventOrderEntity באשכול המשך.
- LodgingReservationEntity: LodgingEntityReservation מייצג הזמנה למקום לינה בנסיעה, ומאפשר למשתמשים לעקוב אחרי הזמנות קיימות או עתידיות של מלונות או יחידות אירוח.
  
  איור 9. ממשק משתמש שבו מוצג אובייקט LodgingReservationEntity יחיד באשכול Continuation.
- TransportationReservationEntity: ‏TransportationReservationEntity מייצג הזמנה לתחבורה בכל אמצעי, ומאפשר למשתמשים לעקוב אחרי הזמנות לטיסה, למעבורת, לרכבת, לאוטובוס, לנסיעה במונית שירות או לשייט קרובות או מתמשכות.
  
  איור 10. ממשק משתמש שבו מוצגת ישות אחת של Transport ReservationEntity בתוך אשכול המשך.
- VehicleRentalReservationEntity: ה-Entity VehicleRentalReservationEntity מייצג הזמנה להשכרת רכב, ומאפשר למשתמשים לעקוב אחרי הזמנות קיימות או עתידיות להשכרת רכב.
  
  איור 11. ממשק משתמש שבו מוצג אובייקט יחיד מסוג VehicleRentalReservationEntity בתוך אשכול Continuation.
האשכול מומלצים הוא תצוגת ממשק משתמש שבה מוצגים הגיבור שנבחר GenericFeaturedEntity משותפי מפתחים רבים בקיבוץ אחד של ממשק המשתמש. יש אשכול אחד של 'תכנים נבחרים', שמופיע בחלק העליון של ממשק המשתמש, במיקום בעל עדיפות מעל כל אשכולות ההמלצות. כל שותף מפתחים יכול לשדר ישות אחת מסוג נתמך ב'מומלצים', ויש הרבה ישויות (שעשויות להיות מסוגים שונים) ממפתחי אפליקציות מרובים באשכול 'מומלצים'.
- GeneralFeaturedEntity: שונה מפריט ההמלצה בכך שפריט המוצג צריך להיות מיועד לתוכן מוביל אחד מהמפתחים, והוא צריך לייצג את התוכן החשוב ביותר שיהיה מעניין ורלוונטי למשתמשים.
  
  איור 12: ממשק משתמש שבו מוצג כרטיס אחד של GenericFeaturedEntity בתוך אשכול של תכנים נבחרים

הכנה לעבודה

רמת API מינימלית: 19

מוסיפים את הספרייה com.google.android.engage:engage-core לאפליקציה:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.5.2'
}

סיכום

התכנון מבוסס על הטמעה של שירות מחויב.

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

סוג האשכול	מגבלות על אשכולות	מגבלות מינימום על ישויות באשכול	מגבלות מקסימליות של ישויות באשכול
אשכולות של המלצות	5 לכל היותר	לפחות 5	עד 25 (`ArticleEntity`,‏ `EventEntity`,‏ `LodgingEntity`,‏ `StoreEntity`,‏ `PointOfInterestEntity` או `PersonEntity`)
אשכול המשך	1 לכל היותר	אחד לפחות	עד 10 (`ArticleEntity`,‏ `EventReservationEntity`,‏ `LodgingReservationEntity`,‏ `TransportationReservationEntity` או `VehicleRentalReservationEntity`)
אשכול מומלץ	1 לכל היותר	לפחות 1	עד 10 (`GenericFeaturedEntity`)

שלב 1: מספקים נתוני ישות

ב-SDK הוגדרו ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים בישויות הבאות בקטגוריה 'אחר':

GenericFeaturedEntity
ArticleEntity
EventEntity
LodgingEntity
StoreEntity
PointOfInterestEntity
PersonEntity
RestaurantReservationEntity
EventReservationEntity
LodgingReservationEntity
TransportationReservationEntity
VehicleRentalReservationEntity

בטבלאות הבאות מפורטים המאפיינים והדרישות הזמינים לכל סוג.

`GenericFeaturedEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
תמונות של פוסטרים	חובה	נציג רק תמונה אחת אם יסופקו כמה תמונות. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: אם סופק תג, יש לוודא שהמקום הבטוח הוא 24dps בחלק העליון וגם בחלק התחתון של התמונה	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
כותרת	אופציונלי	שם הישות.	טקסט חופשי גודל טקסט מומלץ: 50 תווים
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים	אופציונלי	כל תג יכול להיות טקסט חופשי (עד 15 תווים) או תמונה קטנה. טיפול מיוחד בחוויית המשתמש מעל לתמונה או לסרטון, למשל, כשכבת-על של תג על התמונה "עדכון בזמן אמת" משך הקריאה של המאמר
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת טיפוסים בני מנייה (enum) אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

`ArticleEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	טקסט חופשי גודל טקסט מומלץ: 50 תווים לכל היותר
תמונות של פוסטרים	אופציונלי	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: מומלץ מאוד להוסיף תמונה. אם מצורפת תג, צריך לוודא שיש מרווח בטוח של 24 דפים לשעה בחלק העליון ובחלק התחתון של התמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מקור – שם	אופציונלי	השם של המחבר, הארגון או הכתב	טקסט חופשי גודל טקסט מומלץ: פחות מ-25 תווים
מקור – תמונה	אופציונלי	תמונה של המקור, כמו המחבר, הארגון או הכתב	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים	אופציונלי	כל תג יכול להיות טקסט חופשי (עד 15 תווים) או תמונה קטנה. טיפול מיוחד בחוויית המשתמש מעל התמונה או הסרטון, למשל בתור תג שכבת-על בתמונה 'עדכון בזמן אמת' משך הקריאה של המאמר
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מועד פרסום התוכן	אופציונלי	זוהי חותמת הזמן של תחילת המילניום (epoch) במילישניות, שבה התוכן פורסם או עודכן באפליקציה.	חותמת זמן של מערכת Unix באלפיות השנייה
מועד האינטראקציה האחרונה	נדרש באופן מותנה	חותמת הזמן של עידן (epoch) באלפיות השנייה, מהרגע שבו המשתמש קיים אינטראקציה עם הישות הזו בפעם האחרונה. הערה: השדה הזה נדרש אם הישות הזו היא חלק מאשכול ההמשך.	חותמת זמן של מערכת Unix באלפיות השנייה
אחוז ההתקדמות	נדרש באופן מותנה	אחוז התוכן המלא שהמשתמש צפה בו עד היום. הערה: השדה הזה נדרש אם הישות הזו היא חלק מאשכול ההמשך.	ערך int בין 0 ל-100, כולל.
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת Enums אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

`EventEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
שעת התחלה	חובה	חותמת הזמן של שעת ההתחלה הצפויה של האירוע. הערה: הערך הזה יוצג באלפיות שנייה.	חותמת זמן של מערכת Unix באלפיות השנייה
מצב אירוע	חובה	שדה לציון אם האירוע יהיה וירטואלי, פיזי או שניהם.	דוגמאות: VIRTUAL, IN_PERSON או HYBRID
תמונות של פוסטרים	חובה	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: מומלץ מאוד להוסיף תמונה. אם קיים תג, יש לוודא שהמקום הבטוח הוא 24dps בחלק העליון והתחתון של התמונה	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מיקום – מדינה	נדרש באופן מותנה	המדינה שבה מתרחש האירוע. הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	נדרש באופן מותנה	העיר שבה מתקיים האירוע. הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	נדרש באופן מותנה	הכתובת או שם המקום שבו יתקיים האירוע, שצריכים להיות מוצגים למשתמש. הערה: המאפיין הזה נדרש לאירועים IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של המיקום שבו מתארח האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם מתקיים האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של המיקום שבו האירוע מתארח.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) שבה מתקיים האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
שעת סיום	אופציונלי	חותמת הזמן של התקופה שבה האירוע צפוי להסתיים. הערה: הערך הזה יוצג באלפיות שנייה.	חותמת זמן של מערכת Unix באלפיות השנייה
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים	אופציונלי	כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
Price - CurrentPrice	נדרש באופן מותנה	המחיר הנוכחי של הכרטיס לאירוע. חובה לציין אם צוין מחיר מקווקו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של הכרטיס לאירוע.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת מספרים שעומדים בדרישות TYPE_MOVIES_AND_TV_SHOWS (דוגמה – קולנוע) TYPE_DIGITAL_GAMES (דוגמה – eSports) TYPE_MUSIC (לדוגמה – הופעה) TYPE_TRAVEL_AND_LOCAL (לדוגמה: סיור, פסטיבל) TYPE_HEALTH_AND_FITEANCE (דוגמה - שיעור יוגה) TYPE_EDUCATION (דוגמה – כיתה) TYPE_SPORTS (דוגמה – משחק כדורגל) TYPE_DATING (דוגמה – פגישה) אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

`LodgingEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
תמונות של פוסטרים	חובה	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: אם אתם מספקים תג, חשוב לוודא שיש מרווח בטוח של 24 דפים לשנייה בחלק העליון ובחלק התחתון של התמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מיקום – מדינה	חובה	המדינה שבה מתבצעת הלינה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	חובה	העיר שבה מתקיימים המלון.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	חובה	הכתובת של המקום לינה שתוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של מקום הלינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם נמצא המקום לינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מקום הלינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) של המקום לינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
תגים	אופציונלי	כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ לכל כותרת משנה: 50 תווים לכל היותר
AvailabilityTimeWindow - Start Time	אופציונלי	חותמת הזמן של תחילת המילניום (epoch) באלפיות השנייה, שבה המלון צפוי להיות פתוח או זמין.	חותמת זמן של מערכת Unix באלפיות השנייה
AvailabilityTimeWindow - End Time	אופציונלי	חותמת הזמן של תחילת המילניום באלפיות השנייה, עד למועד שבו צפוי שהבקשה תהיה פתוחה או זמינה.	חותמת זמן של תקופה מסוימת באלפיות השנייה
דירוג – ערך מקסימלי	אופציונלי	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	אופציונלי	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של המקום לינה. הערה: יש לציין את השדה הזה אם האפליקציה שלכם קובעת איך המספר יוצג למשתמשים. להשתמש במחרוזת תמציתית. לדוגמה, אם המספר הוא 1,000,000, כדאי להשתמש בקיצור כמו 1M כדי שהמספר לא יקוצר במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של המקום לינה. הערה: אם אתם לא מטפלים בעצמכם בלוגיקת הקיצורים לתצוגה, עליכם להזין את השדה הזה. אם גם Count וגם Count Value נמצאים במודל, הערך של Count יוצג למשתמשים.	ארוך
מחיר – מחיר נוכחי	נדרש באופן מותנה	המחיר הנוכחי של המלון. חובה לציין אם צוין מחיר מקווקו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של האירוח, שיוצג עם קו חוצה בממשק המשתמש.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)

`StoreEntity`

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

מאפיין	דרישה	תיאור	פורמט
תמונות של פוסטרים	חובה	צריך לספק לפחות תמונה אחת.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה	URI
כותרת	אופציונלי	שם החנות.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
מיקום	אופציונלי	המיקום של החנות.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
הסבר	אופציונלי	קריאה להצגת קידום מכירות, אירוע או עדכון בחנות, אם הם זמינים.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
האותיות הקטנות של יתרונות מרכזיים	אופציונלי	טקסט של האותיות הקטנות בנכס היתרונות המרכזיים.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (בטקסט ארוך מדי עשויות להופיע שלוש נקודות)
תיאור	אופציונלי	תיאור של החנות.	טקסט חופשי גודל טקסט מומלץ: פחות מ-90 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
דירוג – ערך מקסימלי	אופציונלי	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	אופציונלי	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של המקום לינה. הערה: יש לציין את השדה הזה אם רוצים לקבוע באפליקציה איך המידע הזה יוצג למשתמשים. יש לציין את המחרוזת המקוצרת שאפשר להציג למשתמש. לדוגמה, אם המספר הוא 1,000,000, כדאי להשתמש בקיצורים כמו 1M כדי שהוא לא ייחתך במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של המקום לינה. הערה: יש לספק את השדה הזה אם אתם לא רוצים לטפל בעצמכם בלוגיקה של קיצורי התצוגה. אם גם Count וגם Count Value נמצאים, המערכת תשתמש ב-Count כדי להציג למשתמשים	ארוך

`PointOfInterestEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
תמונות של פוסטרים	חובה	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: מומלץ מאוד להוסיף תמונה. אם מצורפת תג, צריך לוודא שיש מרווח בטוח של 24 דפים לשעה בחלק העליון ובחלק התחתון של התמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מיקום – מדינה	חובה	המדינה שבה מתרחשת נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	חובה	העיר שבה מתרחשת נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	חובה	הכתובת של נקודת העניין שתוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם נמצא נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) של נקודת העניין.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
AvailabilityTimeWindow - Start Time	אופציונלי	חותמת הזמן של תחילת המילניום (epoch) במיליוניות השנייה, שבה נקודת העניין צפויה להיות פתוחה או זמינה.	חותמת זמן של מערכת Unix באלפיות השנייה
AvailabilityTimeWindow - End Time	אופציונלי	חותמת הזמן של התקופה באלפיות השנייה שבה נקודת העניין צפויה להיות פתוחה או זמינה.	חותמת זמן של מערכת Unix באלפיות השנייה
תגים	אופציונלי	כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
דירוג – ערך מקסימלי	אופציונלי	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	אופציונלי	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של נקודת העניין. הערה: יש לציין את השדה הזה אם האפליקציה שלכם קובעת איך המספר יוצג למשתמשים. להשתמש במחרוזת תמציתית. לדוגמה, אם המספר הוא 1,000,000, כדאי להשתמש בקיצור כמו 1M כדי שהמספר לא יקוצר במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של נקודת העניין. הערה: יש לציין את השדה הזה אם אתם לא מטפלים בעצמכם בלוגיקה של קיצורי הדרך להצגה. אם גם ערך הספירה וגם ערך הספירה מוצגים, המשתמשים יכולים לראות את הספירה	ארוך
מחיר – מחיר נוכחי	נדרש באופן מותנה	המחיר הנוכחי של הכרטיסים או הכרטיס לכניסה לנקודת העניין. יש לציין אם צוין מחיר עם קו חוצה.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של הכרטיסים או הכרטיס לכניסה לנקודת העניין.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל הטקסט המומלץ: עד 45 תווים (בטקסט ארוך מדי עשויות להופיע שלוש נקודות)
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת טיפוסים בני מנייה שעומדים בדרישות TYPE_TRAVEL_AND_LOCAL TYPE_MOVIES_AND_TV_SHOWS (דוגמה – תיאטרון) TYPE_MEDICAL (דוגמה – בית חולים) TYPE_EDUCATION (דוגמה – בית ספר) TYPE_SPORTS (לדוגמה – אצטדיון) הנחיות מופיעות בקטע 'קטגוריית תוכן'.

`PersonEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. כדאי לעיין בשאלות הנפוצות האלה	URI
פרופיל – שם	חובה	שם הפרופיל, המזהה או הכינוי, למשל 'יוסי לוי', '@TeamPixel' וכו'.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
פרופיל – דמות	חובה	תמונת הפרופיל או תמונת דמות של המשתמש. הערה: חייבת להיות תמונה ריבועית ביחס גובה-רוחב של 1:1.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
פרופיל – טקסט נוסף	אופציונלי	טקסט חופשי, כמו הכינוי של הפרופיל.	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
פרופיל – תמונה נוספת	אופציונלי	תמונה קטנה כמו תג אימות.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תמונת כותרת	אופציונלי	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: מומלץ מאוד להוסיף תמונה. אם מצורפת תג, צריך לוודא שיש מרווח בטוח של 24 דפים לשעה בחלק העליון ובחלק התחתון של התמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
פופולריות – מספר	אופציונלי	יש לציין את מספר העוקבים או את ערך הפופולריות, לדוגמה – '3.7 M'. הערה: אם מציינים גם את Count וגם את Count Value, המערכת משתמשת ב-Count.	מחרוזת גודל טקסט מומלץ: עד 20 תווים לסה"כ של המספר והתוויות
פופולריות – ערך ספירה	אופציונלי	מספר העוקבים או ערך הפופולריות. הערה: צריך לספק את ערך המספר אם לא רוצים שהאפליקציה לטפל בלוגיקה של אופטימיזציה של מספר גדול למסכים בגדלים שונים. אם מציינים גם את Count וגם את Count Value, המערכת תשתמש ב-Count.	ארוך
פופולריות – תווית	אופציונלי	מציינים את שם התווית של המדד 'פופולריות'. לדוגמה, 'לייקים'.	מחרוזת גודל טקסט מומלץ: עד 20 תווים לסה"כ של המספר והתווית
פופולריות – תוכן ויזואלי	אופציונלי	מציינים למה מיועדת האינטראקציה. לדוגמה – תמונה שמציגה את סמל הלייקים ואמוג'י. אפשר לספק יותר מתמונה אחת, אבל יכול להיות שלא כולן יוצגו בכל גורמי הצורה. הערה: התמונה חייבת להיות ריבועית ביחס של 1:1	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
דירוג – ערך מקסימלי	חובה	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	חובה	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של הישות. הערה: יש לציין את השדה הזה אם רוצים לקבוע באפליקציה איך המידע הזה יוצג למשתמשים. יש לציין את המחרוזת המקוצרת שאפשר להציג למשתמש. לדוגמה, אם המספר הוא 1,000,000, כדאי להשתמש בקיצורים כמו 1M כדי שהוא לא ייחתך במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של הישות. הערה: הוסיפו את השדה הזה אם אתם לא רוצים לטפל בעצמכם בלוגיקת הקיצור של התצוגה. אם גם Count וגם Count Value נמצאים, המערכת תשתמש ב-Count כדי להציג למשתמשים	ארוך
מיקום – מדינה	אופציונלי	המדינה שבה האדם נמצא או משרת.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	אופציונלי	העיר שבה האדם נמצא או משרת.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת לתצוגה	אופציונלי	הכתובת שבה האדם נמצא או משרת תוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) שבו האדם נמצא או מספק שירות.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה (אם רלוונטי) שבה האדם נמצא או מספק שירות.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) שבו האדם נמצא או שבו הוא משרת.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) שבה האדם נמצא או נותן שירות.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
תגים	אופציונלי	כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: כדי לקבל את התג צריך להזין טקסט או תמונה	לקבלת הנחיות, אפשר לעיין במפרטי תמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת טיפוסים בני מנייה שעומדים בדרישות TYPE_HEALTH_AND_FITENESS (דוגמה – מאמן יוגה/כושר) TYPE_HOME_AND_AUTO (דוגמה – אינסטלטור) TYPE_SPORTS (דוגמה – שחקן) TYPE_DATING אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

`RestaurantReservationEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
שעת ההתחלה של ההזמנה	חובה	חותמת הזמן של תחילת המועדון, באלפיות השנייה, שבה ההזמנה אמורה להתחיל.	חותמת זמן של מערכת Unix באלפיות השנייה
מיקום – מדינה	חובה	המדינה שבה נמצאת המסעדה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	חובה	העיר שבה נמצאת המסעדה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	חובה	הכתובת של המסעדה שתוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של המסעדה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם המסעדה נמצאת.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של המסעדה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) של המסעדה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
תמונות של פוסטרים	אופציונלי	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
גודל הטבלה	אופציונלי	מספר האנשים בקבוצת ההזמנה	מספר שלם > 0

`EventReservationEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	שם הישות.	מחרוזת גודל טקסט מומלץ: 50 תווים לכל היותר
שעת התחלה	חובה	חותמת הזמן של שעת ההתחלה הצפויה של האירוע. הערה: הערך הזה יוצג באלפיות שנייה.	חותמת זמן של מערכת Unix באלפיות השנייה
מצב אירוע	חובה	שדה לציון אם האירוע יהיה וירטואלי, פיזי או שניהם.	Enum:‏ VIRTUAL,‏ IN_PERSON או HYBRID
מיקום – מדינה	נדרש באופן מותנה	המדינה שבה מתרחש האירוע. הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	נדרש באופן מותנה	העיר שבה מתקיים האירוע. הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	נדרש באופן מותנה	הכתובת או שם המקום שבו יתקיים האירוע, שצריכים להיות מוצגים למשתמש. הערה: המאפיין הזה נדרש לאירועים IN_PERSON או HYBRID	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של המיקום שבו מתארח האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם מתקיים האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של המיקום שבו האירוע מתארח.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) שבה מתקיים האירוע.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
תמונות של פוסטרים	אופציונלי	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: מומלץ מאוד להוסיף תמונה. אם קיים תג, יש לוודא שהמקום הבטוח הוא 24dps בחלק העליון והתחתון של התמונה	לקבלת הנחיות, אפשר לעיין במפרטי תמונות.
שעת סיום	אופציונלי	חותמת הזמן של התקופה שבה האירוע צפוי להסתיים. הערה: הערך הזה יוצג באלפיות שנייה.	חותמת זמן של תקופה מסוימת באלפיות השנייה
ספק שירות – שם	אופציונלי	השם של ספק השירות. הערה: חובה להוסיף טקסט או תמונה לספק השירות.	טקסט חופשי. לדוגמה, השם של מארגן האירוע או הסיור שלו
ספק שירות – תמונה	אופציונלי	הלוגו או התמונה של ספק השירות. הערה: ספק השירות צריך לכלול טקסט או תמונה.	לקבלת הנחיות, אפשר לעיין במפרטי תמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים	אופציונלי	כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.
תג – טקסט	אופציונלי	שם התג הערה: חובה להוסיף טקסט או תמונה לתג	טקסט חופשי גודל טקסט מומלץ: עד 15 תווים
תג – תמונה	אופציונלי	תמונה קטנה טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון. הערה: חובה להוסיף טקסט או תמונה לתג	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מזהה ההזמנה	אופציונלי	מזהה ההזמנה של האירוע.	טקסט חופשי
Price - CurrentPrice	נדרש באופן מותנה	המחיר הנוכחי של הכרטיס לאירוע. חובה לציין אם צוין מחיר מקווקו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של הכרטיס לאירוע.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)
דירוג – ערך מקסימלי	אופציונלי	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	אופציונלי	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של האירוע. הערה: יש לציין את השדה הזה אם רוצים לקבוע באפליקציה איך המידע הזה יוצג למשתמשים. יש לציין את המחרוזת המקוצרת שאפשר להציג למשתמש. לדוגמה, אם המספר הוא 1,000,000, מומלץ להשתמש בקיצור כמו 1M כדי שהוא לא ייחתך במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של האירוע. הערה: יש לספק את השדה הזה אם אתם לא רוצים לטפל בעצמכם בלוגיקה של קיצורי התצוגה. אם גם Count וגם Count Value נמצאים, המערכת תשתמש ב-Count כדי להציג למשתמשים	ארוך
קטגוריות תוכן	אופציונלי	מתארים את הקטגוריה של התוכן בתוך הישות.	רשימת מספרים שעומדים בדרישות TYPE_MOVIES_AND_TV_SHOWS (דוגמה – קולנוע) TYPE_DIGITAL_GAMES (דוגמה – eSports) TYPE_MUSIC (לדוגמה – הופעה) TYPE_TRAVEL_AND_LOCAL (לדוגמה: סיור, פסטיבל) TYPE_HEALTH_AND_FITEANCE (דוגמה - שיעור יוגה) TYPE_EDUCATION (דוגמה – כיתה) TYPE_SPORTS (דוגמה – משחק כדורגל) TYPE_DATING (דוגמה – פגישה) אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

`LodgingReservationEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	השם של הישות.	טקסט חופשי. לדוגמה, 'השהייה שלך מ-12 בדצמבר' גודל טקסט מומלץ: 50 תווים לכל היותר
שעת הצ'ק-אין	חובה	חותמת הזמן של תחילת המילניום באלפיות השנייה, שמייצגת את שעת הצ'ק אין של ההזמנה.	חותמת זמן של תקופה מסוימת באלפיות השנייה
שעת צ'ק-אאוט	חובה	חותמת הזמן של תחילת המילניום באלפיות השנייה, שמייצגת את מועד היציאה מהמלון.	חותמת זמן של תקופה מסוימת באלפיות השנייה
מיקום – מדינה	חובה	המדינה שבה נמצא המקום לינה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום – עיר	חובה	העיר שבה המלון נמצא.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת להצגה	חובה	הכתובת של המקום לינה שתוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב	אופציונלי	הרחוב (אם רלוונטי) של מקום הלינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) שבהם נמצא המקום לינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מקום הלינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום – שכונה	אופציונלי	השכונה (אם רלוונטי) של המקום לינה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
תמונות של פוסטרים	אופציונלי	נציג רק תמונה אחת אם יסופקו כמה תמונות. יחס הגובה-רוחב המומלץ הוא 16:9 הערה: אם סופק תג, חשוב לוודא שהמקום הבטוח הוא 24 dps בחלק העליון ובתחתית של התמונה	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
מזהה ההזמנה	אופציונלי	מזהה ההזמנה של הלינה.	טקסט חופשי
דירוג – ערך מקסימלי	אופציונלי	הערך המקסימלי בסולם הדירוג. חובה לציין אם צוין גם ערך הדירוג הנוכחי.	מספר >= 0.0
דירוג – ערך נוכחי	אופציונלי	הערך הנוכחי של סולם הדירוג. חובה לציין את הערך הזה אם צוין גם הערך המקסימלי של הדירוג.	מספר >= 0.0
דירוג – מספר	אופציונלי	מספר הדירוגים של המקום לינה. הערה: יש לציין את השדה הזה אם רוצים לקבוע באפליקציה איך המידע הזה יוצג למשתמשים. יש לציין את המחרוזת המקוצרת שאפשר להציג למשתמש. לדוגמה, אם המספר הוא 1,000,000, כדאי להשתמש בקיצורים כמו 1M כדי שהוא לא ייחתך במסכים קטנים יותר.	מחרוזת
דירוג - ערך ספירה	אופציונלי	מספר הדירוגים של המקום לינה. הערה: יש לספק את השדה הזה אם אתם לא רוצים לטפל בעצמכם בלוגיקה של קיצורי התצוגה. אם גם Count וגם Count Value נמצאים, המערכת תשתמש ב-Count כדי להציג למשתמשים	ארוך
מחיר – מחיר נוכחי	נדרש באופן מותנה	המחיר הנוכחי של המלון. חובה לציין אם צוין מחיר מקווקו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של האירוח, שיוצג עם קו חוצה בממשק המשתמש.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל הטקסט המומלץ: עד 45 תווים (בטקסט ארוך מדי עשויות להופיע שלוש נקודות)

`TransportationReservationEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	השם של הישות.	טקסט חופשי. לדוגמה, 'SFO אל SAN' גודל טקסט מומלץ: 50 תווים לכל היותר
סוג התחבורה	חובה	אמצעי התחבורה או סוג התחבורה של ההזמנה.	Enum: FLIGHT,‏ TRAIN,‏ BUS או FERRY
שעת המראה	חובה	חותמת הזמן של תחילת המרוץ באלפיות השנייה שמייצגת את שעת היציאה.	חותמת זמן של מערכת Unix באלפיות השנייה
שעת הגעה	חובה	חותמת הזמן של תחילת המרוץ באלפיות השנייה שמייצגת את זמן ההגעה.	חותמת זמן של מערכת Unix באלפיות השנייה
מיקום המוצא – מדינה	אופציונלי	מדינת המוצא.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מקום המוצא – עיר	אופציונלי	עיר המוצא.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום היציאה – כתובת להצגה	אופציונלי	מיקום היציאה שיוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום היציאה – רחוב	אופציונלי	הרחוב (אם רלוונטי) של מיקום היציאה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום המוצא – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) של מיקום היציאה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מקום המוצא – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מיקום היציאה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום המוצא – שכונה	אופציונלי	השכונה (אם רלוונטי) של מיקום היציאה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום הנחיתה – מדינה	אופציונלי	המדינה של היעד.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום ההגעה – עיר	אופציונלי	העיר של היעד.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
מיקום הגעתו – כתובת להצגה	אופציונלי	מיקום ההגעה שיוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום ההגעה – רחוב	אופציונלי	הרחוב (אם רלוונטי) של מיקום הגעתו.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום הגעה – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) של מיקום ההגעה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום הגעתו – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מיקום ההגעה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
מיקום הגעה – שכונה	אופציונלי	השכונה (אם רלוונטי) של מיקום הגעתו.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
ספק שירות – שם	אופציונלי	השם של ספק השירות. הערה: חובה להוסיף טקסט או תמונה לספק השירות.	טקסט חופשי. לדוגמה, שם חברת התעופה
ספק שירות – תמונה	אופציונלי	הלוגו או התמונה של ספק השירות. הערה: ספק השירות צריך לכלול טקסט או תמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תמונות של פוסטרים	אופציונלי	אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9	לקבלת הנחיות, אפשר לעיין במפרטי תמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
מזהה ההזמנה	אופציונלי	מזהה ההזמנה של הנסיעה.	טקסט חופשי
Price - CurrentPrice	נדרש באופן מותנה	המחיר הנוכחי של ההזמנה. אם צוין מחיר עם קו חוצה, חובה לספק אותו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של ההזמנה, שיוצג עם קו חוצה בממשק המשתמש.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל הטקסט המומלץ: עד 45 תווים (בטקסט ארוך מדי עשויות להופיע שלוש נקודות)
מספר תחבורה	חובה	מספר הטיסה, מספר האוטובוס, מספר הרכבת או מספר המעבורת/הקרוז.	טקסט חופשי
שעת עלייה למטוס	חובה	חותמת הזמן של התקופה שמייצגת את זמן העלייה למטוס עבור ההזמנה (אם רלוונטי)	חותמת זמן של מערכת Unix באלפיות השנייה

`VehicleRentalReservationEntity`

מאפיין	דרישה	תיאור	פורמט
URI של פעולה	חובה	קישור עומק לישות באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה	URI
כותרת	חובה	השם של הישות.	טקסט חופשי. לדוגמה, "Avis Union Square SF" גודל טקסט מומלץ: 50 תווים לכל היותר
שעת האיסוף	חובה	חותמת הזמן מתחילת הזמן (epoch) שמייצגת את מועד האיסוף של ההזמנה.	חותמת זמן של מערכת Unix באלפיות השנייה
זמן ההחזרה	אופציונלי	חותמת הזמן של תחילת המילניום שמייצגת את מועד היציאה מהמלון.	חותמת זמן של מערכת Unix באלפיות השנייה
כתובת האיסוף – מדינה	אופציונלי	המדינה של נקודת האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת האיסוף – עיר	אופציונלי	העיר שבה נמצא מקום האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת האיסוף – הכתובת שמוצגת	אופציונלי	מיקום האיסוף שיוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
כתובת לאיסוף – רחוב	אופציונלי	הרחוב (אם רלוונטי) של מיקום האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת איסוף – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) של מיקום האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת האיסוף – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מיקום האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת האיסוף – השכונה	אופציונלי	השכונה (אם רלוונטי) של נקודת האיסוף.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
כתובת להחזרה – מדינה	אופציונלי	המדינה של מיקום ההחזרה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת להחזרת מוצרים – עיר	אופציונלי	העיר שבה מחזירים את המיקום.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
כתובת להחזרת מוצרים – כתובת לצורכי תצוגה	אופציונלי	מיקום ההחזרה שיוצג למשתמש.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת להחזרה – רחוב	אופציונלי	הרחוב (אם רלוונטי) של המיקום להחזרת המוצר.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת להחזרת מוצרים – מדינה	אופציונלי	המדינה או המחוז (אם רלוונטי) של מיקום ההחזרה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת להחזרת מוצרים – מיקוד	אופציונלי	המיקוד (אם רלוונטי) של מיקום ההחזרה.	טקסט חופשי גודל טקסט מומלץ: עד כ-20 תווים
כתובת להחזרת מוצרים – שכונה	אופציונלי	השכונה (אם רלוונטי) של מיקום ההחזרה.	טקסט חופשי גודל טקסט מומלץ: עד 20 תווים
ספק שירות – שם	אופציונלי	השם של ספק השירות. הערה: חובה להוסיף טקסט או תמונה לספק השירות.	טקסט חופשי. לדוגמה, "השכרת רכב של Avis"
ספק שירות – תמונה	אופציונלי	הלוגו או התמונה של ספק השירות. הערה: ספק השירות צריך לכלול טקסט או תמונה.	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תמונות של פוסטרים	אופציונלי	נציג רק תמונה אחת אם יסופקו כמה תמונות. יחס הגובה-רוחב המומלץ הוא 16:9	לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור	אופציונלי	פסקה אחת של טקסט לתיאור הישות. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל טקסט מומלץ: 180 תווים
רשימת כתוביות	אופציונלי	עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט. הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.	טקסט חופשי גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
מזהה האישור	אופציונלי	מזהה האישור של הזמנת הרכב השכור.	טקסט חופשי
Price - CurrentPrice	נדרש באופן מותנה	המחיר הנוכחי של ההזמנה. אם צוין מחיר עם קו חוצה, חובה לספק אותו.	טקסט חופשי
מחיר – StrikethroughPrice	אופציונלי	המחיר המקורי של ההזמנה, שיוצג עם קו חוצה בממשק המשתמש.	טקסט חופשי
הסבר על המחיר	אופציונלי	הודעה על מחיר עם מבצע, אירוע או הנחה למנויים, אם יש כאלה.	טקסט חופשי גודל טקסט מומלץ: פחות מ-45 תווים (טקסט ארוך מדי עשוי לכלול שלוש נקודות)

מפרט לתמונות

המפרטים הנדרשים לנכסי תמונות מפורטים בטבלה הזו:

יחס גובה-רוחב	מספר פיקסלים מינימלי	מספר פיקסלים מומלץ
ריבוע (1x1) מועדף	300x300	1,200x1,200
לרוחב (1.91x1)	600x314	1,200x628
לאורך (4x5)	480x600	960x1200

יחס גובה-רוחב

מספר פיקסלים מינימלי

מספר פיקסלים מומלץ

ריבוע (1x1)

מועדף

300x300

1,200x1,200

לרוחב (1.91x1)

600x314

1,200x628

לאורך (4x5)

480x600

960x1200

התמונות צריכות להיות מתארחות ברשתות CDN ציבוריות כדי ש-Google תהיה לה גישה אליהן.

פורמטים של קבצים

PNG, JPG, GIF סטטי, WebP

גודל קובץ מקסימלי

‎5,120 KB

המלצות נוספות

האזור הבטוח לתמונות: התוכן החשוב צריך להופיע ב-80% המרכזיים של התמונה.
כדאי להשתמש ברקע שקוף כדי שהתמונה תוצג בצורה תקינה בהגדרות של העיצוב הכהה והבהיר.

קטגוריית תוכן

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

TYPE_EDUCATION
TYPE_SPORTS
TYPE_MOVIES_AND_TV_SHOWS
TYPE_BOOKS
TYPE_AUDIOBOOKS
TYPE_MUSIC
TYPE_DIGITAL_GAMES
TYPE_TRAVEL_AND_LOCAL
TYPE_HOME_AND_AUTO
TYPE_BUSINESS
TYPE_NEWS
TYPE_FOOD_AND_DRINK
TYPE_SHOPPING
TYPE_HEALTH_AND_FITENESS
TYPE_MEDICAL
TYPE_PARENTING
TYPE_DATING

התמונות צריכות להיות מתארחות ברשתות CDN ציבוריות כדי ש-Google תהיה לה גישה אליהן.

הנחיות לשימוש בקטגוריות התוכן

ישויות מסוימות כמו ArticleEntity ו-GeneralFeaturedEntity כשירות להשתמש בכל אחת מקטגוריות התוכן. ישויות אחרות, כמו EventEntity,‏ EventReservationEntity ו-PointOfInterestEntity, יכולות לקבל את התכונה רק אם הן שייכות לקבוצת משנה של הקטגוריות האלה. לפני שאתם מאכלסים את הרשימה, כדאי לבדוק את רשימת הקטגוריות שזמינות לסוג הישות.
כדאי להשתמש בסוג הישות הספציפי לקטגוריות תוכן מסוימות במקום בשילוב של הישות הגנרית ושל ContentCategory:
- TYPE_MOVIES_AND_TV_SHOWS – לפני שמשתמשים בישויות הכלליות, כדאי לעיין בישויות שמפורטות במדריך לשילוב עם Watch.
- TYPE_BOOKS - כדאי לעיין ב-EbookEntity לפני השימוש בישויות הגנריות.
- TYPE_AUDIOBOOKS – לפני שמשתמשים בישויות הכלליות, כדאי לעיין ב-AudiobookEntity.
- TYPE_SHOPPING – לפני שמשתמשים בישויות הכלליות, כדאי לעיין ב-ShoppingEntity.
- TYPE_FOOD_AND_DRINK – לפני שמשתמשים בישויות הכלליות, כדאי לעיין בישויות שמפורטות במדריך לשילוב נתוני מזון.
השדה ContentCategory הוא אופציונלי, וצריך להשאיר אותו ריק אם התוכן לא שייך לאף אחת מהקטגוריות שצוינו למעלה.
אם תספקו כמה קטגוריות תוכן, צריך לציין אותן לפי סדר הרלוונטיות שלהן לתוכן, וקטגוריית התוכן הרלוונטית ביותר תופיע קודם ברשימה.

שלב 2: מסירת נתוני האשכולות

מומלץ להגדיר את משימת פרסום התוכן ברקע (למשל, באמצעות WorkManager) ולתזמן אותה על בסיס קבוע או על בסיס אירוע (למשל, בכל פעם שהמשתמש פותח את האפליקציה או כשהוא רק הוסיף משהו לעגלת הקניות).

AppEngagePublishClient אחראי לפרסום אשכולות.

כדי לפרסם אשכולות בלקוח, אפשר להשתמש בממשקי ה-API הבאים:

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

ה-API הזה משמש כדי לבדוק אם השירות זמין לשילוב ואם אפשר להציג את התוכן במכשיר.

Kotlin

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

Java

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

`publishRecommendationClusters`

ה-API הזה משמש לפרסום רשימה של RecommendationCluster אובייקטים.

Kotlin

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

Java

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:

הנתונים הקיימים של RecommendationCluster מהשותף למפתחים יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול ההמלצות המעודכן.

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

`publishFeaturedCluster`

ה-API הזה משמש לפרסום רשימה של FeaturedCluster אובייקטים.

Kotlin

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:

הנתונים הקיימים של FeaturedCluster מהשותף למפתחים יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול המעודכן.

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

`publishContinuationCluster`

ה-API הזה משמש לפרסום אובייקט ContinuationCluster.

Kotlin

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

Java

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:

הנתונים הקיימים של ContinuationCluster מהשותף למפתחים יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול ההמשך המעודכן.

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

`publishUserAccountManagementRequest`

ה-API הזה משמש לפרסום כרטיס כניסה. פעולת הכניסה מפנה את המשתמשים לדף הכניסה של האפליקציה כדי שהאפליקציה תוכל לפרסם תוכן (או לספק תוכן מותאם אישית יותר).

המטא-נתונים הבאים הם חלק מכרטיס הכניסה:

מאפיין	דרישה	תיאור
URI של פעולה	חובה	קישור עומק לפעולה (כלומר, ניווט לדף הכניסה לאפליקציה)
תמונה	אופציונלי – אם לא מציינים אותו, צריך לציין כותר	התמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16x9 עם רזולוציה של 1264x712
כותרת	אופציונלי – אם לא יצוין, חובה לציין תמונה	השם בכרטיס
טקסט של פעולה	אופציונלי	טקסט שמוצג בקריאה לפעולה (כלומר, כניסה לחשבון)
כותרת משנה	אופציונלי	כותרת משנה אופציונלית בכרטיס

Kotlin

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

Java

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בעסקה אחת:

הנתונים הקיימים של UserAccountManagementCluster מהשותף המפתח יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול המעודכן UserAccountManagementCluster.

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

`updatePublishStatus`

אם אף אחד מהאשכולות לא פורסם מסיבה עסקית פנימית כלשהי, מומלץ מאוד לעדכן את סטטוס הפרסום באמצעות ה-API updatePublishStatus. חשוב לציין זאת מהסיבות הבאות:

חשוב לציין את הסטטוס בכל התרחישים, גם אם התוכן פורסם (STATUS == PUBLISHED) כדי לאכלס מרכזי בקרה שמשתמשים בסטטוס הבוטה הזה כדי להעביר את התקינות ומדדים אחרים של השילוב.
אם לא פורסם תוכן אבל סטטוס השילוב תקין (STATUS == NOT_PUBLISHED), Google יכולה להימנע מהפעלת התראות בלוחות הבקרה של בריאות האפליקציה. הוא מאשר שהתוכן לא פורסם בגלל מצב צפוי מנקודת המבט של הספק.
הוא עוזר למפתחים להבין מתי הנתונים מתפרסמים ומתי לא.
Google עשויה להשתמש בקודי המצב כדי לעודד את המשתמש לבצע פעולות מסוימות באפליקציה, כדי שיוכל לראות את תוכן האפליקציה או להתגבר עליו.

רשימת קודי הסטטוס של פרסום שעומדים בדרישות:

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

אם התוכן לא יפורסם כי המשתמש לא נכנס לחשבון, Google תמליץ לפרסם את כרטיס הכניסה. אם מסיבה כלשהי הספקים לא יכולים לפרסם את כרטיס הכניסה, מומלץ לבצע קריאה ל-API‏ updatePublishStatus עם קוד הסטטוס NOT_PUBLISHED_REQUIRES_SIGN_IN.

Kotlin

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

Java

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

`deleteRecommendationClusters`

ממשק ה-API הזה משמש למחיקת התוכן של אשכולות ההמלצות.

Kotlin

client.deleteRecommendationClusters()

Java

client.deleteRecommendationClusters();

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

`deleteFeaturedCluster`

ממשק ה-API הזה משמש למחיקת התוכן של 'אשכול מומלץ'.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

`deleteContinuationCluster`

ממשק ה-API הזה משמש למחיקת התוכן של אשכול ההמשך.

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

`deleteUserManagementCluster`

ממשק ה-API הזה משמש למחיקת התוכן של UserAccountManagement Cluster.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מהאשכול UserAccountManagement. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.

`deleteClusters`

ה-API הזה משמש למחיקת התוכן של סוג אשכול נתון.

Kotlin

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

Java

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

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

טיפול בשגיאות

מומלץ מאוד להאזין לתוצאת המשימה מממשקי ה-API לפרסום, כדי שתוכלו לבצע פעולה נוספת כדי לשחזר ולשלוח מחדש משימה שהצליחה.

Kotlin

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

Java

client.publishRecommendationClusters(
              new PublishRecommendationClustersRequest.Builder()
                  .addRecommendationCluster(...)
                  .build())
          .addOnCompleteListener(
              task -> {
                if (task.isSuccessful()) {
                  // do something
                } else {
                  Exception exception = task.getException();
                  if (exception instanceof AppEngageException) {
                    @AppEngageErrorCode
                    int errorCode = ((AppEngageException) exception).getErrorCode();
                    if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
                      // do something
                    }
                  }
                }
              });

השגיאה מוחזרת כ-AppEngageException, והסיבה כלולה כקוד שגיאה.

קוד שגיאה	שם השגיאה	הערה
`1`	`SERVICE_NOT_FOUND`	השירות לא זמין במכשיר הנתון.
`2`	`SERVICE_NOT_AVAILABLE`	השירות זמין במכשיר הנתון, אבל הוא לא זמין בזמן השיחה (לדוגמה, הוא מושבת באופן מפורש).
`3`	`SERVICE_CALL_EXECUTION_FAILURE`	ביצוע המשימה נכשל בגלל בעיות בשרשור. במקרה כזה, אפשר לנסות שוב.
`4`	`SERVICE_CALL_PERMISSION_DENIED`	למתקשר אין הרשאה לבצע את קריאת השירות.
`5`	`SERVICE_CALL_INVALID_ARGUMENT`	הבקשה מכילה נתונים לא חוקיים (לדוגמה, יותר ממספר האשכולות המותר).
`6`	`SERVICE_CALL_INTERNAL`	יש שגיאה בצד השירות.
`7`	`SERVICE_CALL_RESOURCE_EXHAUSTED`	קריאת השירות מתבצעת בתדירות גבוהה מדי.

שלב 3: טיפול בכוונות שידור

בנוסף לקריאות ל-Content API לפרסום תוכן דרך משימה, צריך גם להגדיר BroadcastReceiver כדי לקבל את הבקשה לפרסום התוכן.

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

צריך להגדיר את BroadcastReceiver בשתי הדרכים הבאות:

רישום דינמי של מופע של הכיתה BroadcastReceiver באמצעות Context.registerReceiver(). כך אפשר לתקשר עם אפליקציות שעדיין נמצאות בזיכרון.

Kotlin

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
  // is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received
  // Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
  // received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION))
}

Java

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger continuation cluster publish when PUBLISH_CONTINUATION broadcast is
// received
}

public static void registerBroadcastReceivers(Context context) {

context = context.getApplicationContext();

// Register Recommendation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_RECOMMENDATION));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}

מגדירים באופן סטטי הטמעה באמצעות התג <receiver> בקובץ AndroidManifest.xml. כך האפליקציה יכולה לקבל בקשות שידור כשהיא לא פועלת, והיא גם יכולה לפרסם את התוכן.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_CONTINUATION" />
      </intent-filter>
   </receiver>
</application>

השירות שולח את הכוונות הבאות:

com.google.android.engage.action.PUBLISH_RECOMMENDATION מומלץ להתחיל שיחת publishRecommendationClusters כשמקבלים את הכוונה הזו.
com.google.android.engage.action.PUBLISH_FEATURED מומלץ להתחיל קריאת publishFeaturedCluster כאשר מקבלים את הכוונה הזו.
com.google.android.engage.action.PUBLISH_CONTINUATION מומלץ להתחיל שיחת publishContinuationCluster כשמקבלים את הכוונה הזו.

תהליך העבודה של השילוב

במדריך המפורט תהליך השילוב של Engage למפתחים מוסבר איך לאמת את השילוב אחרי שהוא הושלם.

שאלות נפוצות

שאלות נפוצות על Engage SDK

יצירת קשר

אם יש לכם שאלות במהלך תהליך השילוב, תוכלו לפנות אל engage-developers@google.com.

השלבים הבאים

אחרי השלמת השילוב, עליכם לבצע את השלבים הבאים:

שולחים אימייל לכתובת engage-developers@google.com ומצרפים את קובץ ה-APK המשולב שעומד בקריטריונים לבדיקה על ידי Google.
Google מבצעת אימות ובדיקות פנימיות כדי לוודא שההטמעה פועלת כצפוי. אם יהיו שינויים, Google תיצור איתכם קשר עם הפרטים הנדרשים.
בסיום הבדיקה, אם לא נדרשים שינויים, Google תצורף אליכם כדי להודיע לכם שתוכלו להתחיל לפרסם את קובץ ה-APK המעודכן והמשולב ב-Play Store.
אחרי ש-Google תאשר שה-APK המעודכן שלכם פורסם ב-Play Store, יכול להיות שהאשכולות המלצות, מומלצות והמשך יפורסמו ויוצגו למשתמשים.