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

חשוב: Engage SDK החליף את Media Home, שהוצא משימוש. אם כבר יש לכם שילוב עם Media Home, אתם יכולים לפעול לפי ההוראות במדריכים האלה כדי להעביר את התוכן שלכם ל-Engage SDK, וכך לפרסם את התוכן שלכם ביותר מכשירים וגורמי צורה. אם יש לך שאלות, אפשר לפנות אל [e-mail].

כדי להגביר את ההתעניינות באפליקציה, כדאי להגיע למשתמשים במקומות שבהם הם נמצאים. אפשר להגדיר שילוב עם Engage SDK כדי להציג תוכן להמשך צפייה והמלצות אישיות ישירות למשתמשים בכמה פלטפורמות במכשיר: אוספים, חבילת הבידור וחנות Play. השילוב מוסיף פחות מ-50KB (דחוס) ל-APK הממוצע, ולרוב האפליקציות נדרש בערך שבוע של זמן פיתוח. מידע נוסף זמין באתר העסקי שלנו.

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

הערה: במדריך לשילוב בטלוויזיה מוסבר בהרחבה על חוויית השימוש בתכונה "המשך צפייה" ב-Google TV.

תמיכה בקטגוריות ופלטפורמות

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

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

מיומנויות ב-Android

הצגת הקוד ב-GitHub

שילוב של Engage SDK

כדי לשלב את Engage SDK, לנפות באגים ולפתור בעיות בהטמעה, אתם יכולים להשתמש במיומנות Android.

כדי להתקין את המיומנות מ-Android CLI, מריצים את הפקודה:

android skills add engage-sdk-integration

פרטי השילוב

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

הסברים על המונחים

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

• אשכולות של המלצות מציגים הצעות מותאמות אישית לתוכן לצפייה משותף פיתוח ספציפי.

  ההמלצות מוצגות במבנה הבא:

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

    

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

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

    

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

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

  

  איור 3. ממשק המשתמש של Entertainment Space שבו מוצג אוסף המשכים עם המלצות לא גמורות מכמה שותפים (רק המלצה אחת גלויה כרגע).

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

  

  איור 4. ממשק המשתמש של Entertainment Space שבו מוצג אשכול מומלצים עם המלצות מכמה שותפים (רק המלצה אחת גלויה כרגע).

הכנה מראש

רמת 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.6.0'
}

מידע נוסף זמין במאמר הרשאות גישה לחבילה ב-Android 11.

סיכום

העיצוב מבוסס על הטמעה של שרת מאגד (bound service).

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

סוג האשכול	מגבלות על אשכולות	מגבלות מקסימליות על ישויות באשכול
אשכולות של המלצות	עד 7	עד 50
אוסף ההמשכים	לכל היותר 1	עד 20
אשכול מומלץ	לכל היותר 1	עד 20

חשוב: Engage SDK החליף את Media Home, שהוצא משימוש. אם כבר יש לכם שילוב עם Media Home, פעלו לפי ההוראות בשלב 0 כדי להעביר את התוכן ל-Engage SDK, וכך לפרסם אותו במכשירים ובגורמי צורה נוספים. צריך לפנות אל [e-mail]. אם אין לכם שילוב קיים של Media Home, דלגו לשלב 1.

שלב 0: מעבר משילוב קיים של Media Home SDK

בקטע הזה מוסבר איך להעביר את מודלי הנתונים והקריאות ל-API הקיימים של Media Home SDK אל Engage SDK.

מיפוי מודלים של נתונים משילוב קיים

אם אתם עוברים משילוב קיים של Media Home, הטבלה הבאה מתארת איך למפות מודלים של נתונים בערכות SDK קיימות ל-Engage SDK החדש:

שילוב שווה ערך ל-MediaHomeVideoContract	שילוב שווה ערך של Engage SDK
com.google.android.mediahome.video.PreviewChannel	com.google.android.engage.common.datamodel.RecommendationCluster
com.google.android.mediahome.video.PreviewChannel.Builder	com.google.android.engage.common.datamodel.RecommendationCluster.Builder
com.google.android.mediahome.video.PreviewChannelHelper	com.google.android.engage.video.service.AppEngageVideoClient
com.google.android.mediahome.video.PreviewProgram	מחולק לכיתות נפרדות: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.PreviewProgram.Builder	מחולק ל-builders במחלקות נפרדות: EventVideo, LiveStreamingVideo, Movie, TvEpisode, TvSeason, TvShow, VideoClipEntity
com.google.android.mediahome.video.VideoContract	כבר אין לי צורך בפגישה.
com.google.android.mediahome.video.WatchNextProgram	מחולק למאפיינים במחלקות נפרדות: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity
com.google.android.mediahome.video.WatchNextProgram.Builder	מחולק למאפיינים במחלקות נפרדות: EventVideoEntity, LiveStreamingVideoEntity, MovieEntity, TvEpisodeEntity, TvSeasonEntity, TvShowEntity, VideoClipEntity

פרסום אשכולות ב-Media Home SDK בהשוואה ל-Engage SDK

ב-Media Home SDK, אשכולות וישויות פורסמו באמצעות ממשקי API נפרדים:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

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

Kotlin

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

Java

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

שלב 1: מסירת נתוני הישות

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

1. MovieEntity
2. TvShowEntity
3. TvSeasonEntity
4. TvEpisodeEntity
5. LiveStreamingVideoEntity
6. VideoClipEntity

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

MovieEntity

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של ההפעלה	חובה בנייד	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את הסרט. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מזהי URI להפעלה ספציפיים לפלטפורמה	אופציונלי לנייד, חובה ל-Google TV	קישורי עומק ספציפיים לפלטפורמה שמובילים לאפליקציה של הספק כדי להתחיל להפעיל את הסרט.
‫URI של דף המידע	אופציונלי	קישור העומק לאפליקציה של הספק שבה מוצגים פרטים על הסרט. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
תאריך הפצה	אופציונלי	באלפיות השנייה של התקופה.
זמינות	אופציונלי	‫AVAILABLE: התוכן זמין למשתמש בלי שנדרשת פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: המשתמש צריך לרכוש או לשכור את התוכן. PURCHASED: המשתמש רכש או שכר את התוכן.
מחיר המבצע	אופציונלי	טקסט חופשי
משך	חובה	באלפיות השנייה.
ז'אנר	אופציונלי	טקסט חופשי
דירוגי תוכן	אופציונלי	טקסט חופשי, בהתאם לסטנדרט המקובל בתחום. (דוגמה)
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

TvShowEntity

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של דף המידע	חובה	קישור העומק לאפליקציה של הספק שבה מוצגים הפרטים של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
‫URI של ההפעלה	אופציונלי	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מזהי URI להפעלה ספציפיים לפלטפורמה	אופציונלי לנייד, חובה ל-Google TV	קישורי עומק ספציפיים לפלטפורמה שמובילים לאפליקציה של הספק כדי להתחיל להפעיל את תוכנית הטלוויזיה.
תאריך הקרנת הבכורה של הפרק הראשון	אופציונלי	באלפיות השנייה של התקופה.
תאריך השידור של הפרק האחרון	אופציונלי	באלפיות השנייה של התקופה.
זמינות	אופציונלי	‫AVAILABLE: התוכן זמין למשתמש בלי שנדרשת פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: המשתמש צריך לרכוש או לשכור את התוכן. PURCHASED: המשתמש רכש או שכר את התוכן.
מחיר המבצע	אופציונלי	טקסט חופשי
מספר העונות	אופציונלי	מספר שלם חיובי
ז'אנר	אופציונלי	טקסט חופשי
דירוגי תוכן	אופציונלי	טקסט חופשי, בהתאם לסטנדרט המקובל בתחום. (דוגמה)
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

TvSeasonEntity

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של דף המידע	חובה	קישור העומק לאפליקציה של הספק שבה מוצגים הפרטים של העונה של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
‫URI של ההפעלה	אופציונלי	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את העונה של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מספר העונה שמוצג	אופציונלי זמין בגרסה 1.3.1	מחרוזת
תאריך הקרנת הבכורה של הפרק הראשון	אופציונלי	באלפיות השנייה של התקופה.
תאריך השידור של הפרק האחרון	אופציונלי	באלפיות השנייה של התקופה.
זמינות	אופציונלי	‫AVAILABLE: התוכן זמין למשתמש בלי שנדרשת פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: המשתמש צריך לרכוש או לשכור את התוכן. PURCHASED: המשתמש רכש או שכר את התוכן.
מחיר המבצע	אופציונלי	טקסט חופשי
מספר הפרקים	אופציונלי	מספר שלם חיובי
ז'אנר	אופציונלי	טקסט חופשי
דירוגי תוכן	אופציונלי	טקסט חופשי, בהתאם לסטנדרט המקובל בתחום. (דוגמה)
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

TvEpisodeEntity

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של ההפעלה	חובה בנייד	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את הפרק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מזהי URI להפעלה ספציפיים לפלטפורמה	אופציונלי לנייד, חובה ל-Google TV	קישורי עומק ספציפיים לפלטפורמה שמובילים לאפליקציה של הספק כדי להתחיל להפעיל את הפרק.
‫URI של דף המידע	אופציונלי	קישור העומק לאפליקציה של הספק שבה מוצגים פרטים על הפרק בתוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
שם התוכנית	אופציונלי לנייד; חובה ל"המשך צפייה" ב-Google TV	שם תוכנית הטלוויזיה שהפרק שייך אליה.
מספר עונה	אופציונלי לנייד; חובה ל"המשך צפייה" ב-Google TV	מחרוזת
הצגת מספר הפרק	אופציונלי לנייד; חובה ל"המשך צפייה" ב-Google TV זמין בגרסה 1.3.1	מחרוזת
תאריך השידור	אופציונלי	באלפיות השנייה של התקופה.
זמינות	אופציונלי	‫AVAILABLE: התוכן זמין למשתמש בלי שנדרשת פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: המשתמש צריך לרכוש או לשכור את התוכן. PURCHASED: המשתמש רכש או שכר את התוכן.
מחיר המבצע	אופציונלי	טקסט חופשי
משך	חובה	הערך חייב להיות חיובי באלפיות השנייה.
ז'אנר	אופציונלי	טקסט חופשי
דירוגי תוכן	אופציונלי	טקסט חופשי, בהתאם לסטנדרט המקובל בתחום. (דוגמה)
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

LiveStreamingVideoEntity

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של ההפעלה	חובה בנייד	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את הסרטון. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מזהי URI להפעלה ספציפיים לפלטפורמה	אופציונלי לנייד, חובה ל-Google TV	קישורי עומק ספציפיים לפלטפורמה שמובילים לאפליקציה של הספק כדי להתחיל להפעיל את הסרטון.
שדרן	אופציונלי	טקסט חופשי
שעת התחלה	אופציונלי	באלפיות השנייה של התקופה.
שעת סיום	אופציונלי	באלפיות השנייה של התקופה.
מספר צפיות	אופציונלי	טקסט חופשי, צריך להיות מותאם לשוק המקומי.
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

VideoClipEntity

האובייקט VideoClipEntity מייצג ישות של סרטון שמגיע מרשתות חברתיות, כמו טיקטוק או YouTube.

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת, ולציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות לרוחב, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב לתרחישים שונים). כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
‫URI של ההפעלה	חובה בנייד	קישור העומק לאפליקציה של הספק כדי להתחיל להפעיל את הסרטון. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
מזהי URI להפעלה ספציפיים לפלטפורמה	אופציונלי לנייד, חובה ל-Google TV	קישורי עומק ספציפיים לפלטפורמה שמובילים לאפליקציה של הספק כדי להתחיל להפעיל את הסרטון.
שעת יצירה	אופציונלי	באלפיות השנייה של התקופה.
משך	חובה	הערך חייב להיות חיובי באלפיות השנייה.
יוצר	אופציונלי	טקסט חופשי
תמונה של היוצר/ת	אופציונלי	תמונה של דמות היוצר
מספר צפיות	אופציונלי	טקסט חופשי, צריך להיות מותאם לשוק המקומי.
טקסט של קריאה לפעולה	אופציונלי	טקסט חופשי שיוצג כקריאה לפעולה.
תגים	אופציונלי	רשימת התגים שמשויכים לישות.
סוג ההצעות לצפייה	חובה בתנאים מסוימים	חובה לספק את המאפיין הזה כשהפריט נמצא באשכול ההמשך, והוא חייב להיות אחד מארבעת הסוגים הבאים: CONTINUE: המשתמש כבר צפה ביותר מדקה אחת מהתוכן הזה. NEW: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש הפך לזמין ויש בדיוק פרק אחד שלא נצפה. האפשרות הזו מתאימה לתוכן אפיזודי כמו תוכניות טלוויזיה או משחקי כדורגל מוקלטים בסדרה. הבא: המשתמש צפה בפרק אחד או יותר של תוכן מסוים, אבל נשארו עוד פרקים או שנשאר פרק אחד בדיוק, והפרק האחרון הוא לא "חדש" ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת הצפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת הצפייה כדי לאסוף באופן ידני את התכנים שהוא רוצה לצפות בהם בהמשך.
מועד האינטראקציה האחרונה	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
הזמן של מיקום ההפעלה האחרון	חובה בתנאים מסוימים	חובה לציין את הפרמטר הזה כשהפריט נמצא באוסף ההמשכים והערך של WatchNextType הוא CONTINUE. באלפיות השנייה של התקופה.

מפרט לתמונות

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

פורמט קובץ

‫PNG, ‏ JPG, ‏ GIF סטטי, WebP

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

5,120KB

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

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

דוגמה

Kotlin

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .setCallToActionText("Watch Now")
    .addTag("Action")
    .build()

Java

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .setCallToActionText("Watch Now")
                  .addTag("Action")
                  .build();

שלב 2: ציון נתונים של אוסף ההמשכים

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

‫AppEngagePublishClient אחראי לפרסום של אשכולות. ממשקי ה-API הבאים זמינים בלקוח:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

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

ל-Engage SDK מגרסה 1.6.0 ואילך (מומלץ)

מיומנויות ב-Android

הצגת הקוד ב-GitHub

שילוב של Engage SDK

כדי להתקין את המיומנות מ-Android CLI, מריצים את הפקודה:

android skills add engage-sdk-integration

אם הצוות שלכם משתמש בכלי תכנות מבוססי-AI (כמו Gemini ב-Android Studio), אתם יכולים להפוך את ההעברה הזו לאוטומטית על ידי הנחיה של העוזר האישי מבוסס-AI:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

אתם יכולים לבדוק את זמינות השירות לכל סוג אשכול שאתם מתכוונים לפרסם. ‫isServiceAvailable API מקבל אובייקט בקשה, ServiceAvailabilityRequest, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ערכי ה-enum של ClusterType שנדרשים ל-ServiceAvailabilityRequest.

סוג האשכול	קבוע של סוג האשכול	ערך של מספר שלם
לא ידוע	TYPE_UNKNOWN	0
אשכול המלצות	TYPE_RECOMMENDATION	1
אשכול מומלץ	TYPE_FEATURED	2
אוסף ההמשכים	TYPE_CONTINUATION	3
אשכול ניהול משתמשים	TYPE_ENGAGEMENT	8
אשכול מינויים	TYPE_SUBSCRIPTION	12

Kotlin

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

Java

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

תכונה: זמינות מותנית של שירותים

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

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

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

אם הגדרת ברירת המחדל הזו לא מתאימה לצרכים שלכם, אתם יכולים לפנות לכתובת [e-mail].

לגרסאות SDK שקודמות לגרסה 1.6.0 (הוצאה משימוש)

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.
    }
});

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

publishRecommendationClusters

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

חשוב: ממשקי ה-API לפרסום הם ממשקי API לעדכון או להוספה (upsert). הם מחליפים את התוכן הקיים. אל תשלחו קריאות לממשקי ה-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה.

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.

חשוב: ממשקי ה-API לפרסום הם ממשקי API לעדכון או להוספה (upsert). הם מחליפים את התוכן הקיים. אל תשלחו קריאות לממשקי ה-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה.

Kotlin

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

Java

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

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

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

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

publishContinuationCluster

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

חשוב: ממשקי ה-API לפרסום הם ממשקי API לעדכון או להוספה (upsert). הם מחליפים את התוכן הקיים. אל תשלחו קריאות לממשקי ה-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה.

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 של פעולה	חובה	קישור עומק לפעולה (למשל, מעבר לדף הכניסה לאפליקציה)
תמונה	אופציונלי – אם לא מציינים את המאפיין הזה, צריך לציין את מאפיין שם הפריט	התמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16:9 וברזולוציה של 1,264x712
כותרת	אופציונלי – אם לא מספקים את השדה הזה, צריך לספק את השדה Image	השם שמופיע בכרטיס
טקסט פעולה	אופציונלי	הטקסט שמוצג ב-CTA (למשל, "כניסה")
כותרת משנה	אופציונלי	כותרת משנה אופציונלית בכרטיס

חשוב: ממשקי ה-API לפרסום הם ממשקי API לעדכון או להוספה (upsert). הם מחליפים את התוכן הקיים. אל תשלחו קריאות לממשקי ה-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה.

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());

deleteRecommendationsClusters

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

חשוב: צריך להפעיל ממשקי API למחיקה רק כשאין תוכן לפרסום. אל תשלחו קריאות ל-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה. פנו אל [e-mail] לפני שתשתמשו בממשקי API למחיקה.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

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

הערה: ה-API הזה זמין מגרסה 1.1.0 ואילך.

deleteFeaturedCluster

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

חשוב: צריך להפעיל ממשקי API למחיקה רק כשאין תוכן לפרסום. אל תשלחו קריאות ל-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה. פנו אל [e-mail] לפני שתשתמשו בממשקי API למחיקה.

Kotlin

client.deleteFeaturedCluster()

Java

client.deleteFeaturedCluster();

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

הערה: ה-API הזה זמין מגרסה 1.1.0 ואילך.

deleteContinuationCluster

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

חשוב: צריך להפעיל ממשקי API למחיקה רק כשאין תוכן לפרסום. אל תשלחו קריאות ל-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה. לפני שמשתמשים בממשקי API למחיקה, צריך לפנות אל [e-mail].

Kotlin

client.deleteContinuationCluster()

Java

client.deleteContinuationCluster();

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

הערה: ה-API הזה זמין מגרסה 1.1.0 ואילך.

deleteUserManagementCluster

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

חשוב: צריך להפעיל ממשקי API למחיקה רק כשאין תוכן לפרסום. אל תשלחו קריאות ל-API למחיקה ולפרסום כדי להחליף את התוכן, כי ממשקי ה-API לפרסום עושים את זה באופן מובנה. פנו אל [e-mail] לפני שתשתמשו בממשקי API למחיקה.

Kotlin

client.deleteUserManagementCluster()

Java

client.deleteUserManagementCluster();

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

הערה: ה-API הזה זמין מגרסה 1.1.0 ואילך.

deleteClusters

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

חשוב: צריך להפעיל ממשקי API למחיקה רק כשאין תוכן לפרסום. אל תשלחו קריאות ל-API של מחיקה ופרסום כדי להחליף את התוכן, כי ממשקי ה-API של הפרסום עושים את זה באופן מובנה. לפני שמשתמשים בממשקי API למחיקה, צריך לפנות אל [e-mail].

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: טיפול בכוונות שידור

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

המטרה של כוונות שידור היא בעיקר להפעיל מחדש את האפליקציה ולאלץ סנכרון נתונים. כוונות שידור לא נועדו להישלח בתדירות גבוהה מאוד. הוא מופעל רק כששירות 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),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

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

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      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>

השירות שולח את ה-intent הבא:

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

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

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

שאלות נפוצות

שאלות נפוצות לגבי Engage SDK

יצירת קשר

אם יש לכם שאלות במהלך תהליך השילוב, אתם יכולים לפנות אל [e-mail].

השלבים הבאים

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

• שולחים אימייל לכתובת [e-mail] ומצרפים את קובץ ה-APK המשולב שמוכן לבדיקה על ידי Google.
• ‫Google מבצעת אימות ובדיקות פנימיות כדי לוודא שהשילוב פועל כצפוי. אם צריך לבצע שינויים, Google תפנה אליכם עם הפרטים הנדרשים.
• כשהבדיקה מסתיימת ולא נדרשים שינויים, Google יוצרת איתכם קשר כדי להודיע לכם שאתם יכולים להתחיל לפרסם את ה-APK המעודכן והמשולב בחנות Play.
• אחרי ש-Google תאשר שקובץ ה-APK המעודכן פורסם בחנות Play, יכול להיות שאשכולות ההמלצות, התוכן המוצג וההמשך יפורסמו ויוצגו למשתמשים.