Google מפתחת ממשק במכשיר שמארגן את האפליקציות של המשתמשים לפי קטגוריות, ומאפשר חוויה חדשה ומרתקת של שימוש בתוכן האפליקציות וחיפוש תוכן מותאם אישית. החוויה הזו במסך מלא מעניקה לשותפים למפתחים הזדמנות להציג את התוכן העשיר הטוב ביותר שלהם בערוץ ייעודי מחוץ לאפליקציה.
המדריך הזה מכיל הוראות לשותפי מפתחות שרוצים לשלב את תוכן הווידאו שלהם, באמצעות Engage SDK כדי לאכלס גם את הממשק החדש וגם את הממשקים הקיימים של Google.
פרטי השילוב
טרמינולוגיה
השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, המשך ומומלץ.
באשכול המלצות מוצגות הצעות בהתאמה אישית לתוכן לצפייה, מפותחות שותף מסוים.
ההמלצות מופיעות במבנה הבא:
אשכול המלצות: תצוגה של ממשק משתמש שמכילה קבוצה של המלצות מאותו מפתח שותף.
ישות: אובייקט שמייצג פריט יחיד באשכול. ישות יכולה להיות סרט, תוכנית טלוויזיה, סדרת טלוויזיה, וידאו בשידור חי ועוד. בקטע איך מספקים נתוני ישות מופיעה רשימה של סוגי הישויות הנתמכים.
באשכול המשך מוצגים סרטונים לא מוגמרים ופרקים רלוונטיים חדשים שפורסמו מאת כמה שותפי פיתוח, בקיבוץ אחד בממשק המשתמש. כל שותף פיתוח יורשה לשדר עד 10 ישויות באשכול Continuation. מחקרים הראו שהמלצות בהתאמה אישית בשילוב עם תוכן 'המשך הסרטון' בהתאמה אישית מעוררות את מידת ההתעניינות הגבוהה ביותר בקרב המשתמשים.
באשכול מומלצים מוצגת מבחר ישויות מכמה שותפי פיתוח במקבץ אחד בממשק המשתמש. יהיה אשכול אחד של המלצות, שיוצג בחלק העליון של ממשק המשתמש וימוקם בעדיפות מעל כל אשכולות ההמלצות. כל שותף מפתחים יורשה לשדר עד 10 ישויות באשכול המומלץ.
עבודה מוקדמת
רמת 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'
}
למידע נוסף, ראו הרשאות גישה לחבילה ב-Android 11.
סיכום
התכנון מבוסס על הטמעה של שירות מוגדר.
הנתונים שלקוח יכול לפרסם כפופים למגבלות הבאות לסוגים שונים של אשכולות:
סוג האשכול | מגבלות של אשכולות | מגבלות מקסימליות של ישויות באשכול |
---|---|---|
אשכולות של המלצות | 5 לכל היותר | 50 לכל היותר |
אשכול המשכיות | 1 לכל היותר | עד 10 |
אשכול מומלץ | 1 לכל היותר | 10 לכל היותר |
שלב 0: העברה משילוב קיים של Media Home 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 הוגדרו ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים באובייקטים הבאים בקטגוריית 'צפייה':
בטבלה הבאה מפורטים המאפיינים והדרישות של כל סוג.
MovieEntity
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך להוסיף לפחות תמונה אחת, וצריך לספק אותה עם יחס גובה-רוחב. (עדיף להשתמש בתמונות בפריסה לאורך, אבל מומלץ לשלוח גם תמונות בפריסה לאורך וגם תמונות בפריסה אנכית בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
URI של הפעלה | חובה |
קישור העומק לאפליקציית הספק כדי להתחיל את הפעלת הסרט. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
ה-URI של דף המידע | אופציונלי |
קישור העומק לאפליקציית הספק כדי להציג פרטים על הסרט. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
תאריך הפצה | חובה | באלפיות שנייה. |
זמינות | חובה | זמין: התוכן זמין למשתמש בלי צורך לבצע פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: כדי לצפות בתוכן, המשתמשים צריכים לרכוש אותו או לשכור אותו. PURCHASED (נרכשו): התוכן נרכש או הושכר על ידי המשתמש. |
מחיר המבצע | אופציונלי | טקסט חופשי |
משך הזמן | חובה | באלפיות שנייה. |
ז'אנר | חובה | טקסט חופשי |
דירוגי תוכן | חובה | טקסט חופשי, בהתאם לסטנדרטים המקובלים בתחום. (דוגמה) |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
TvShowEntity
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לצרף לפחות תמונה אחת, ויש לציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בפורמט אופקי, אבל מומלץ להעביר גם תמונות לאורך וגם תמונות לרוחב בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
ה-URI של דף המידע | חובה |
קישור העומק לאפליקציית הספק כדי להציג את הפרטים של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
URI של הפעלה | אופציונלי |
קישור העומק לאפליקציית הספק כדי להתחיל את ההפעלה של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
תאריך הקרנת הפרק הראשון | חובה | באלפיות שנייה. |
תאריך הקרנת הבכורה של הפרק האחרון | אופציונלי | באלפיות שנייה. |
זמינות | חובה | זמין: התוכן זמין למשתמש בלי צורך לבצע פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: כדי לצפות בתוכן, המשתמשים צריכים לרכוש אותו או לשכור אותו. PURCHASED (נרכשו): התוכן נרכש או הושכר על ידי המשתמש. |
מחיר המבצע | אופציונלי | טקסט חופשי |
מספר העונות | חובה | מספר שלם חיובי |
ז'אנר | חובה | טקסט חופשי |
דירוגי תוכן | חובה | טקסט חופשי, בהתאם לתקן המקובל בתחום. (דוגמה) |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
TvSeasonEntity
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לצרף לפחות תמונה אחת, ויש לציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות בפריסה לאורך, אבל מומלץ לשלוח גם תמונות בפריסה לאורך וגם תמונות בפריסה אנכית בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
ה-URI של דף המידע | חובה |
קישור העומק לאפליקציית הספק כדי להציג את פרטי העונה של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
URI של הפעלה | אופציונלי |
קישור העומק לאפליקציית הספק כדי להתחיל את הצפייה בעונה של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). אפשר לעיין בשאלות הנפוצות האלה |
הצגת מספר העונה |
אופציונלי זמין בגרסה 1.3.1 |
מחרוזת |
תאריך הקרנת הבכורה של הפרק הראשון | חובה | באלפיות שנייה. |
תאריך הקרנת הבכורה של הפרק האחרון | אופציונלי | באלפיות שנייה. |
זמינות | חובה | זמין: התוכן זמין למשתמש בלי צורך לבצע פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: כדי לצפות בתוכן, המשתמשים צריכים לרכוש אותו או לשכור אותו. PURCHASED (נרכשו): התוכן נרכש או הושכר על ידי המשתמש. |
מחיר המבצע | אופציונלי | טקסט חופשי |
מספר הפרקים | חובה | מספר שלם חיובי |
ז'אנר | חובה | טקסט חופשי |
דירוגי תוכן | חובה | טקסט חופשי, בהתאם לסטנדרטים המקובלים בתחום. (דוגמה) |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
TvEpisodeEntity
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך להוסיף לפחות תמונה אחת, וצריך לספק אותה עם יחס גובה-רוחב. (עדיף להשתמש בתמונות בפריסה לאורך, אבל מומלץ לשלוח גם תמונות בפריסה לאורך וגם תמונות בפריסה אנכית בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרטי תמונות. |
URI להפעלה | חובה |
קישור העומק לאפליקציית הספק כדי להתחיל את הפעלת הפרק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
ה-URI של דף המידע | אופציונלי |
קישור העומק לאפליקציית הספק, שבו מוצגים פרטים על הפרק של תוכנית הטלוויזיה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
הצגת מספר הפרק |
אופציונלי זמין בגרסה 1.3.1 |
מחרוזת |
תאריך השידור | חובה | באלפיות שנייה. |
זמינות | חובה | זמין: התוכן זמין למשתמש בלי צורך לבצע פעולה נוספת. FREE_WITH_SUBSCRIPTION: התוכן זמין אחרי שהמשתמש רוכש מינוי. PAID_CONTENT: כדי לצפות בתוכן, המשתמשים צריכים לרכוש אותו או לשכור אותו. PURCHASED (נרכשו): התוכן נרכש או הושכר על ידי המשתמש. |
מחיר המבצע | אופציונלי | טקסט חופשי |
משך הזמן | חובה | הערך חייב להיות חיובי באלפיות שנייה. |
ז'אנר | חובה | טקסט חופשי |
דירוגי תוכן | חובה | טקסט חופשי, בהתאם לסטנדרטים המקובלים בתחום. (דוגמה) |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
LiveStreamingVideoEntity
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לצרף לפחות תמונה אחת, ויש לציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות בפריסה לאורך, אבל מומלץ לשלוח גם תמונות בפריסה לאורך וגם תמונות בפריסה אנכית בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרטי תמונות. |
URI של הפעלה | חובה |
קישור העומק לאפליקציית הספק כדי להתחיל את הפעלת הסרטון. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה |
שדרן | חובה | טקסט חופשי |
שעת התחלה | אופציונלי | באלפיות שנייה. |
שעת סיום | אופציונלי | באלפיות שנייה. |
מספר צפיות | אופציונלי | טקסט חופשי, חייב להיות מותאם לשוק המקומי. |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
VideoClipEntity
האובייקט VideoClipEntity
מייצג ישות וידאו שמגיעה מרשתות חברתיות, כמו TikTok או YouTube.
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לצרף לפחות תמונה אחת, ויש לציין את יחס הגובה-רוחב שלה. (עדיף להשתמש בתמונות בפריסה לאורך, אבל מומלץ לשלוח גם תמונות בפריסה לאורך וגם תמונות בפריסה אנכית בתרחישים שונים).
לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
URI של הפעלה | חובה |
קישור העומק לאפליקציית הספק כדי להתחיל את הפעלת הסרטון. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
שעת יצירה | חובה | בפרק זמן של אלפיות שנייה. |
משך הזמן | חובה | הערך חייב להיות חיובי באלפיות שנייה. |
יוצר/ת | חובה | טקסט חופשי |
תמונת היוצר/ת | אופציונלי | תמונה של הדמות של היוצר/ת |
מספר צפיות | אופציונלי | טקסט חופשי, חייב להיות מותאם לשוק המקומי. |
סוג ההצעה לצפייה | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation, והוא חייב להיות אחד מארבעת הסוגים הבאים: המשך: המשתמש כבר צפה יותר מדקה בתוכן הזה. חדש: המשתמש צפה בכל הפרקים הזמינים של תוכן מסוים שמחולק לפרקים, אבל פרק חדש זמין ועכשיו יש רק פרק אחד שלא צפו בו. התכונה הזו פועלת עבור תוכניות טלוויזיה, הקלטות של משחקי כדורגל בסדרה וכו'. שלב הבא: המשתמש צפה בפרק אחד או יותר מלא של תוכן שבו יש פרקים, אבל יש עוד פרק אחד או יותר או פרק אחד בלבד, והפרק האחרון לא מסומן כ'חדש' ופורסם לפני שהמשתמש התחיל לצפות בתוכן. רשימת צפייה: המשתמש בחר באופן מפורש להוסיף סרט, אירוע או סדרה לרשימת צפייה כדי לבחור ידנית את התוכן הבא שהוא רוצה לצפות בו. |
מועד ההתעניינות האחרון | נדרש באופן מותנה | צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות שנייה של עידן. |
מועד מיקום ההפעלה האחרון | נדרש באופן מותנה | צריך לציין את השדה הזה כשהפריט נמצא באשכול Continuation ו-WatchNextType הוא CONTINUE. באלפיות שנייה. |
מפרט לתמונות
בקטע הבא מפורטים המפרטים הנדרשים לנכסי תמונות:
פורמטים של קבצים
PNG, JPG, GIF סטטי, WebP
גודל קובץ מקסימלי
5,120 KB
המלצות נוספות
- האזור הבטוח לתמונות: התוכן החשוב צריך להופיע ב-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) .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) .build();
שלב 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
אם מסיבה עסקית פנימית כלשהי לא מתפרסם אף אשכולות, מומלץ מאוד לעדכן את סטטוס הפרסום באמצעות updatePublishStatus API. חשוב לציין זאת מהסיבות הבאות:
- חשוב לספק את הסטטוס בכל התרחישים, גם כשהתוכן פורסם (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-developers@google.com.
השלבים הבאים
אחרי השלמת השילוב, עליכם לבצע את השלבים הבאים:
- שולחים אימייל לכתובת engagement-developers@google.com ומצרפים את ה-APK המשולב שמוכן לבדיקה על ידי Google.
- Google מבצעת אימות ובדיקה פנימית כדי לוודא שהשילוב פועל כצפוי. אם יהיו שינויים, Google תיצור איתכם קשר עם הפרטים הנדרשים.
- בסיום הבדיקה, אם לא נדרשים שינויים, Google תצורף אליכם כדי להודיע לכם שתוכלו להתחיל לפרסם את קובץ ה-APK המעודכן והמשולב ב-Play Store.
- אחרי ש-Google תאשר שה-APK המעודכן שלכם פורסם בחנות Play, ייתכן שהאשכולות המלצות, מוצגים והמשך יתפרסמו ויוצגו למשתמשים.