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

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

פרטי השילוב

טרמינולוגיה

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

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

    • אשכול המלצות יכול להיות מורכב מ-ArticleEntity, מ-PersonEntity או מ-EventEntity, אבל לא משילוב של סוגי ישויות שונים.

    ההמלצות מופיעות במבנה הבא:

    • אשכול המלצות: תצוגת ממשק משתמש שמכילה קבוצה של המלצות מאותו שותף פיתוח.

    • ישות: אובייקט שמייצג פריט יחיד באשכול. השילוב הזה מציע כמה ישויות שיוצגו באמצעות אשכול ההמלצות:

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

        איור 1: ממשק המשתמש שמוצג בו ישות אחת של ArticleEntity באשכול ההמלצות.

      • PersonEntity: רכיב PersonEntity מייצג אדם. ההמלצות יכולות להיות להדגיש מאמן או כל אדם שקשור לבריאות ולכושר וכו'.

        איור 2: ממשק משתמש שבו מוצג אובייקט PersonEntity יחיד בתוך אשכול ההמלצות.

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

        איור 3: ממשק משתמש שבו מוצג אובייקט EventEntity יחיד בתוך אשכול ההמלצות.

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

    תוכן ההמשך יכול להיות במבנה הבא:

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

      איור 6. ממשק משתמש שבו מוצג אובייקט ArticleEntity יחיד בתוך אשכול Continuation.

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

      איור 8. ממשק משתמש שבו מוצג אובייקט EventReservationEntity יחיד בתוך אשכול Continuation.

  • באשכול מומלצים מוצגת מבחר ישויות מכמה שותפי פיתוח במקבץ אחד בממשק המשתמש. יהיה אשכול אחד של תכנים נבחרים, שיוצג בחלק העליון של ממשק המשתמש במיקום בעל עדיפות מעל כל אשכולות ההמלצות. כל שותף מפתחים יורשה לשדר עד 10 ישויות באשכול המומלץ.

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

      איור 12: ממשק משתמש שמציג כרטיס Hero אחד GeneralFeaturedEntity בתוך אשכול סרטונים מוצגים

עבודה מוקדמת

רמת 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,‏ PersonEntity או EventEntity)
אשכול המשכיות 1 לכל היותר אחד לפחות עד 10 (ArticleEntity או EventReservationEntity)
אשכול מומלץ 1 לכל היותר לפחות 1 10 לכל היותר (GenericFeaturedEntity)

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

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

  1. GenericFeaturedEntity
  2. ArticleEntity
  3. PersonEntity
  4. EventEntity
  5. EventReservationEntity

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

GenericFeaturedEntity

מאפיין דרישה תיאור פורמט
URI של פעולה חובה

קישור עומק לישות באפליקציית הספק.

הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה

URI
תמונות של פוסטרים חובה

אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9

הערה: אם סופק תג, יש לוודא שהמקום הבטוח של התמונה בחלק העליון והתחתון של 24dps הוא של 24dps.

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

טקסט חופשי

גודל טקסט מומלץ: 50 תווים
תיאור אופציונלי

פסקה אחת של טקסט לתיאור הישות.

הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.

טקסט חופשי

גודל טקסט מומלץ: 180 תווים
רשימת כתוביות אופציונלי

עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט.

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

טקסט חופשי

גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים אופציונלי

כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.

טיפול מיוחד בחוויית המשתמש מעל התמונה או הסרטון, למשל בתור תג שכבת-על בתמונה

  • 'עדכון בזמן אמת'
  • משך הקריאה של המאמר
תג – טקסט אופציונלי

שם התג

הערה: חובה להוסיף טקסט או תמונה לתג

טקסט חופשי

גודל טקסט מומלץ: עד 15 תווים
תג – תמונה אופציונלי

תמונה קטנה

טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון.

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

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

רשימת Enums

אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

ArticleEntity

מאפיין דרישה תיאור פורמט
URI של פעולה חובה

קישור עומק לישות באפליקציית הספק.

הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה

URI
כותרת חובה שם הישות.

טקסט חופשי

גודל טקסט מומלץ: 50 תווים לכל היותר
תמונות של פוסטרים אופציונלי

אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9

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

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

טקסט חופשי

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

פסקה אחת של טקסט לתיאור הישות.

הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.

טקסט חופשי

גודל טקסט מומלץ: 180 תווים
רשימת כתוביות אופציונלי

עד 3 כתוביות, כאשר כל כתוביות היא שורה אחת של טקסט.

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

טקסט חופשי

גודל הטקסט המומלץ לכל כתוביות: 50 תווים לכל היותר
תגים אופציונלי

כל תג הוא טקסט חופשי (עד 15 תווים) או תמונה קטנה.

טיפול מיוחד בחוויית המשתמש מעל התמונה או הסרטון, למשל בתור תג שכבת-על בתמונה

  • 'עדכון בזמן אמת'
  • משך הקריאה של המאמר
תג – טקסט אופציונלי

שם התג

הערה: חובה להוסיף טקסט או תמונה לתג

טקסט חופשי

גודל טקסט מומלץ: עד 15 תווים
תג – תמונה אופציונלי

תמונה קטנה

טיפול מיוחד בחוויית המשתמש, למשל כשכבת-על של תג על התמונה הממוזערת או הסרטון.

הערה: חובה להוסיף טקסט או תמונה לתג

לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מועד פרסום התוכן אופציונלי זוהי חותמת הזמן של התקופה (epoch) באלפיות השנייה שבה התוכן פורסם או עודכן באפליקציה. חותמת זמן של מערכת Unix באלפיות השנייה
מועד האינטראקציה האחרונה נדרש באופן מותנה

חותמת הזמן של עידן (epoch) באלפיות השנייה, מהרגע שבו המשתמש קיים אינטראקציה עם הישות הזו בפעם האחרונה.

הערה: השדה הזה נדרש אם הישות הזו היא חלק מאשכול ההמשך.

 חותמת זמן של תקופה מסוימת באלפיות השנייה
אחוז התקדמות נדרש באופן מותנה

האחוז מהתוכן המלא שהמשתמש צרך עד היום.

הערה: השדה הזה נדרש אם הישות הזו היא חלק מאשכול ההמשך.

 ערך int בין 0 ל-100, כולל.
קטגוריות תוכן אופציונלי מתארים את הקטגוריה של התוכן בתוך הישות.

רשימת Enums

אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

PersonEntity

מאפיין דרישה תיאור פורמט
URI של פעולה חובה

קישור עומק לישות באפליקציית הספק.

הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה

URI
פרופיל – שם חובה שם הפרופיל, המזהה או הכינוי שלו, למשל 'ישראלי', ' @TeamPixel' וכו'

מחרוזת

גודל טקסט מומלץ: 50 תווים לכל היותר
פרופיל – דמות חובה

תמונת הפרופיל או תמונת הדמות של המשתמש.

הערה: חייבת להיות תמונה ריבועית ביחס גובה-רוחב של 1:1.

 לקבלת הנחיות, אפשר לעיין במפרטי תמונות.
פרופיל – טקסט נוסף אופציונלי טקסט חופשי, כמו הכינוי של הפרופיל.

טקסט חופשי

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

אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9

הערה: מומלץ מאוד להוסיף תמונה. אם סופק תג, יש לוודא שיש מקום בטוח של 24dps בחלק העליון ובתחתית התמונה

 לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
פופולריות – מספר אופציונלי

מציינים את מספר העוקבים או את ערך הפופולריות, לדוגמה: ‎"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

אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

EventEntity

מאפיין דרישה תיאור פורמט
URI של פעולה חובה

קישור עומק לישות באפליקציית הספק.

הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. כדאי לעיין בשאלות הנפוצות האלה

URI
כותרת חובה שם הישות.

מחרוזת

גודל טקסט מומלץ: 50 תווים לכל היותר
שעת התחלה חובה

חותמת הזמן של שעת ההתחלה הצפויה של האירוע.

הערה: הערך הזה יוצג באלפיות שנייה.

 חותמת זמן של מערכת Unix באלפיות השנייה
מצב אירוע חובה

שדה לציון אם האירוע יהיה וירטואלי, פיזי או שניהם.

 Enum:‏ VIRTUAL,‏ IN_PERSON או HYBRID
תמונות של פוסטרים חובה

אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9

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

 לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
מיקום – מדינה נדרש באופן מותנה

המדינה שבה האירוע מתרחש.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – עיר נדרש באופן מותנה

העיר שבה מתקיים האירוע.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת לתצוגה נדרש באופן מותנה

הכתובת או שם המקום שבו יתקיים האירוע, שצריך להופיע למשתמש.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב אופציונלי שם הרחוב (אם רלוונטי) של המיקום שבו מתארח האירוע.

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה אופציונלי המדינה (State) או המחוז (אם רלוונטי) שבהם האירוע מתארח.

טקסט חופשי

גודל טקסט מומלץ: עד כ-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_FITENESS (דוגמה – שיעור יוגה)
  • TYPE_EDUCATION (דוגמה – כיתה)
  • TYPE_SPORTS (דוגמה – משחק כדורגל)
  • TYPE_DATING (דוגמה - מפגש)

אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

EventReservationEntity

מאפיין דרישה תיאור פורמט
URI של פעולה חובה

קישור עומק לישות באפליקציית הספק.

הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. כדאי לעיין בשאלות הנפוצות האלה

URI
כותרת חובה שם הישות.

מחרוזת

גודל טקסט מומלץ: 50 תווים לכל היותר
שעת התחלה חובה

חותמת הזמן של שעת ההתחלה הצפויה של האירוע.

הערה: הערך הזה יוצג באלפיות שנייה.

 חותמת זמן של מערכת Unix באלפיות השנייה
מצב אירוע חובה

שדה לציון אם האירוע יהיה וירטואלי, פיזי או שניהם.

 Enum:‏ VIRTUAL,‏ IN_PERSON או HYBRID
מיקום – מדינה נדרש באופן מותנה

המדינה שבה האירוע מתרחש.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – עיר נדרש באופן מותנה

העיר שבה מתקיים האירוע.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – כתובת לתצוגה נדרש באופן מותנה

הכתובת או שם המקום שבו יתקיים האירוע, שצריך להופיע למשתמש.

הערה: השדה הזה נדרש לאירועים מסוג IN_PERSON או HYBRID

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – רחוב אופציונלי שם הרחוב (אם רלוונטי) של המיקום שבו מתארח האירוע.

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מדינה אופציונלי המדינה (State) או המחוז (אם רלוונטי) שבהם האירוע מתארח.

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
מיקום – מיקוד אופציונלי המיקוד (אם רלוונטי) של המיקום שבו מתארח האירוע.

טקסט חופשי

גודל טקסט מומלץ: עד 20 תווים
מיקום – שכונה אופציונלי השכונה (אם רלוונטי) שבה מתקיים האירוע.

טקסט חופשי

גודל טקסט מומלץ: עד כ-20 תווים
תמונות של פוסטר אופציונלי

אם תספקו כמה תמונות, נציג רק תמונה אחת. יחס הגובה-רוחב המומלץ הוא 16:9

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

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

חותמת הזמן של שעת הסיום הצפויה של האירוע.

הערה: הערך הזה יוצג באלפיות שנייה.

 חותמת זמן של מערכת Unix באלפיות השנייה
ספק שירות – שם אופציונלי

השם של ספק השירות.

הערה: חובה להוסיף טקסט או תמונה לספק השירות.

טקסט חופשי. לדוגמה, שם מארגן האירוע/הסיור
ספק שירות – תמונה אופציונלי

הלוגו או התמונה של ספק השירות.

הערה: ספק השירות צריך לכלול טקסט או תמונה.

לקבלת הנחיות, אפשר לעיין במפרט לתמונות.
תיאור אופציונלי

פסקה אחת של טקסט לתיאור הישות.

הערה: המשתמש יראה רק את התיאור או את רשימת הכתוביות, ולא את שניהם.

טקסט חופשי

גודל טקסט מומלץ: 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_FITENESS (דוגמה – שיעור יוגה)
  • TYPE_EDUCATION (דוגמה – כיתה)
  • TYPE_SPORTS (דוגמה – משחק כדורגל)
  • TYPE_DATING (דוגמה – פגישה)

אפשר לעיין בהנחיות בקטע קטגוריית תוכן.

מפרט לתמונות

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

יחס גובה-רוחב מספר פיקסלים מינימלי מספר פיקסלים מומלץ

ריבוע (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 תוכל לגשת אליהן.

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

  1. יש ישויות כמו ArticleEntity ו-GenericFeaturedEntity שיכולות להשתמש בכל אחת מקטגוריות התוכן. ישויות אחרות, כמו EventEntity,‏ EventReservationEntity ו-PersonEntity, יכולות לקבל נתונים רק מחלק מהקטגוריות האלה. לפני שמאכלסים את הרשימה, צריך לבדוק את רשימת הקטגוריות שמתאימות לסוג ישות מסוים.

  2. כדאי להשתמש בסוג הישות הספציפי לקטגוריות תוכן מסוימות במקום בשילוב של הישות הגנרית ושל ContentCategory:

    • TYPE_MOVIES_AND_TV_SHOWS – עיינו בישויות במדריך השילוב של צפייה לפני שתשתמשו בישויות הגנריות.
    • TYPE_BOOKS – לפני שמשתמשים בישויות הכלליות, כדאי לעיין ב-EbookEntity.
    • TYPE_AUDIOBOOKS – לפני שמשתמשים בישויות הכלליות, כדאי לעיין ב-AudiobookEntity.
    • TYPE_SHOPPING – לפני שמשתמשים בישויות הכלליות, כדאי לעיין ב-ShoppingEntity.
    • TYPE_FOOD_AND_DRINK – לפני שמשתמשים בישויות הכלליות, כדאי לעיין בישויות שמפורטות במדריך לשילוב נתוני מזון.

  3. השדה ContentCategory הוא אופציונלי, וצריך להשאיר אותו ריק אם התוכן לא שייך לאף אחת מהקטגוריות שצוינו למעלה.

  4. אם מציינים כמה קטגוריות תוכן, צריך לציין אותן לפי רמת הרלוונטיות לתוכן, כאשר קטגוריית התוכן הרלוונטית ביותר מופיעה בראש הרשימה.

שלב 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 מהשותף המפתח יוסרו.
  • הנתונים מהבקשה מנותחים ונשמרים באשכול Continuation המעודכן.

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

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 SDK

יצירת קשר

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

השלבים הבאים

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

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