Google יוצרת פלטפורמה במכשיר שמארגנת את המשתמשים אפליקציות לפי ענף ומאפשר חוויה סוחפת חדשה לצריכת תוכן מותאם אישית באפליקציות ועל הגילוי. החוויה הזו במסך מלא מספקת למפתחים לשותפים הזדמנות להציג את התוכן העשיר הטוב ביותר שלהם בערוץ ייעודי באפליקציה שלהם.
המדריך הזה כולל הוראות למפתחים שותפים לשילוב האודיו שלהם באמצעות ה-API של Engage כדי לאכלס את האזור החדש הזה בפלטפורמות השונות של Google.
פרטי השילוב
טרמינולוגיה
השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, המשך ומוצגים.
אשכולות של המלצות מציגים הצעות מותאמות אישית לתוכן שכדאי לקרוא משותף מפתחים יחיד.
ההמלצות שלכם בנויות באופן הבא:
אשכול המלצות: תצוגה של ממשק משתמש שמכילה קבוצה של מאותו מפתח שותף.
איור 1. ממשק משתמש של חבילת הבידור שמציג אשכול המלצות משותף יחיד. ישות: אובייקט שמייצג פריט יחיד באשכול. ישות הם יכולים להיות פלייליסט, ספר אודיו, פודקאסט ועוד. ניתן לעיין ב הקטע 'נתוני ישויות' להצגת רשימה של ישויות נתמכות שונים.
איור 2. ממשק משתמש של חבילת הבידור שמציג סינגל ישות שמופיעה באשכול ההמלצות של שותף יחיד.
באשכול Continueation (המשך) מוצג תוכן אודיו שהמשתמשים הביעו עניין בו לאחרונה. מכמה שותפים של מפתחים בקיבוץ אחד של ממשק המשתמש. כל מפתח השותף יוכל לשדר 10 ישויות לכל היותר אשכול המשך.
איור 3. ממשק משתמש של חבילת הבידור שמציג אשכול המשך עם המלצות לא גמורות מכמה קבוצות שותפים (כרגע מוצגת רק המלצה אחת). באשכול מוצגים מוצגים מבחר פריטים מתוך כמה שותפים למפתחים בקיבוץ יחיד של ממשק משתמש. יהיה סרטון מוצגים אחד שיוצג בחלק העליון של ממשק המשתמש, עם עדיפות מעל לכל אשכולות ההמלצות. לכל שותף מפתחים יהיה מורשה לשדר עד 10 ישויות באשכול המוצג.
איור 4. ממשק משתמש של חבילת הבידור שמציג 'סרטונים מוצגים' אשכול עם המלצות מכמה שותפים (רק אחד מהשותפים) ההמלצה מוצגת כרגע).
הכנה לעבודה
רמת 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 לכל היותר | 50 לכל היותר |
אשכול המשך | 1 לכל היותר | 10 לכל היותר |
אשכול נבחר | 1 לכל היותר | 10 לכל היותר |
שלב 1: מסירת נתוני הישות
ב-SDK הוגדרו ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים הישויות הבאות של קטגוריית ההאזנה:
MusicAlbumEntity
MusicArtistEntity
MusicTrackEntity
MusicVideoEntity
PlaylistEntity
PodcastSeriesEntity
PodcastEpisodeEntity
LiveRadioStationEntity
AudiobookEntity
בתרשימים הבאים מפורטים המאפיינים והדרישות הזמינים לכל סוג.
MusicAlbumEntity
האובייקט MusicAlbumEntity
מייצג אלבום מוזיקה (לדוגמה, Midnights)
מאת טיילור סוויפט).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | השם של אלבום המוזיקה. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI של דף מידע | חובה |
קישור העומק לאפליקציית הספק לקבלת פרטים על אלבום המוזיקה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
אומנים | חובה | רשימת האומנים באלבום המוזיקה. |
URI להפעלה | אופציונלי |
קישור עומק שמפעיל את האלבום באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
מספר השירים | אופציונלי | מספר השירים באלבום המוזיקה. |
ז'אנרים | אופציונלי | רשימת הז'אנרים באלבום המוזיקה. |
פורמט האלבום | אופציונלי |
אלבום (כולל LP ו-LP כפול) מיני-אלבום יחיד מיקסטייפ |
לייבלים של מוזיקה | אופציונלי | רשימת לייבלים של מוזיקה שמשויכים לאלבום. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם הורדתם את אלבום המוזיקה למכשיר. |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
תאריך הפצה | אופציונלי | תאריך הפרסום של האלבום באלפיות שנייה (epoch). |
Duration | אופציונלי | משך הזמן של האלבום באלפיות השנייה. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
אחוז ההתקדמות הושלם | אופציונלי |
מומלץ לפריטים באשכול ההמשך. מספר שלם בין 0 ל-100 |
MusicArtistEntity
האובייקט MusicArtistEntity
מייצג אריסט מוזיקה (לדוגמה, Adele).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | השם של המוזיקאי. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI של דף מידע | חובה |
קישור העומק לאפליקציית הספק לקבלת פרטים על המוזיקה אומן. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI להפעלה | אופציונלי |
קישור העומק שמתחיל את השמעת השירים של האומן אצל הספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
MusicTrackEntity
האובייקט MusicTrackEntity
מייצג טראק מוזיקה (לדוגמה, צהוב של
קולדפליי).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | שם הטראק של המוזיקה. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI להפעלה | חובה |
קישור עומק שמפעיל את טראק המוזיקה דרך הספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI של דף מידע | אופציונלי |
קישור עומק לאפליקציית הספק לקבלת פרטים על הטראק של המוזיקה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
Duration | אופציונלי | משך הזמן של הטראק באלפיות השנייה. |
אלבום | אופציונלי | שם האלבום שאליו השיר שייך. |
אומנים | חובה | רשימת האומנים בטראק המוזיקה. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם בוצעה הורדה של טראק המוזיקה למכשיר. |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
אחוז ההתקדמות הושלם | אופציונלי |
מומלץ לפריטים באשכול ההמשך. מספר שלם בין 0 ל-100 |
MusicVideoEntity
האובייקט MusicVideoEntity
מייצג סרטון מוזיקה (לדוגמה,
The Weeknd – Take My Breath (סרטון מוזיקה רשמי)).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | השם של סרטון המוזיקה. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI להפעלה | חובה |
קישור עומק שמפעיל את סרטון המוזיקה דרך הספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI של דף מידע | אופציונלי |
קישור עומק לאפליקציית הספק לקבלת פרטים על סרטון המוזיקה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
Duration | אופציונלי | משך הסרטון באלפיות השנייה. |
מספר צפיות | אופציונלי | מספר הצפיות בסרטון בפורמט טקסט חופשי. |
אומנים | אופציונלי | רשימת האומנים שמופיעים בסרטון המוזיקה. |
סיווג התוכן | אופציונלי | רשימת סיווגי התוכן של הטראק. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם בוצעה הורדה של סרטון המוזיקה למכשיר. |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
אחוז ההתקדמות הושלם | אופציונלי |
מומלץ לפריטים באשכול ההמשך. מספר שלם בין 0 ל-100 |
PlaylistEntity
האובייקט PlaylistEntity
מייצג פלייליסט של מוזיקה (לדוגמה, הפלייליסט 'US Top'
10 פלייליסטים).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | שם הפלייליסט. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI להפעלה | חובה |
קישור עומק שמפעיל את הפלייליסט של המוזיקה אצל הספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI של דף מידע | אופציונלי |
קישור עומק לאפליקציית הספק לקבלת פרטים על הפלייליסט של המוזיקה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
Duration | אופציונלי | משך הזמן של הפלייליסט באלפיות השנייה. |
מספר השירים | אופציונלי | מספר השירים בפלייליסט של המוזיקה. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם הורדת הפלייליסט בוצעה למכשיר. |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
אחוז ההתקדמות הושלם | אופציונלי |
מומלץ לפריטים באשכול ההמשך. מספר שלם בין 0 ל-100 |
PodcastSeriesEntity
האובייקט PodcastSeriesEntity
מייצג סדרת פודקאסטים (לדוגמה,
American Life).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | השם של סדרת הפודקאסטים. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI של דף מידע | חובה |
קישור עומק לאפליקציית הספק לקבלת פרטים על הפודקאסט סדרות. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI להפעלה | אופציונלי |
קישור עומק שמתחיל להפעיל את סדרת הפודקאסטים באפליקציית הספק. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
מספר הפרקים | אופציונלי | מספר הפרקים בסדרת הפודקאסט. |
שם הפקה | אופציונלי | שם ההפקה של סדרת הפודקאסט. |
מארחים | אופציונלי | רשימת המארחים של סדרת הפודקאסטים. |
ז'אנרים | אופציונלי | רשימת הז'אנרים של סדרת הפודקאסטים. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם הורדת הפודקאסט למכשיר בוצעה. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
PodcastEpisodeEntity
האובייקט PodcastEpisodeEntity
מייצג סדרת פודקאסטים (לדוגמה,
Spark Bird, Episode 754: This American Life).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | שם הפרק בפודקאסט. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI להפעלה | חובה |
קישור עומק שמתחיל להפעיל את פרק הפודקאסט בספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
שם סדרת ההפקות | חובה | השם של סדרת הפודקאסטים שאליה שייך הפרק. |
Duration | חובה | משך הזמן של פרק הפודקאסט באלפיות השנייה. |
תאריך פרסום | חובה | תאריך פרסום הפודקאסט (באלפיות שנייה) |
URI של דף מידע | אופציונלי |
קישור עומק לאפליקציית הספק לקבלת פרטים על פרק הפודקאסט. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
שם הפקה | אופציונלי | שם ההפקה של סדרת הפודקאסט. |
אינדקס הפרקים | אופציונלי | האינדקס של הפרק בסדרה (האינדקס הראשון הוא 1). |
מארחים | אופציונלי | רשימת המארחים של פרק הפודקאסט. |
ז'אנרים | אופציונלי | רשימת הז'אנרים של פרק הפודקאסט. |
ההורדה הושלמה במכשיר | אופציונלי | ערך בוליאני שמציין אם הורדת הפרק של הפודקאסט הושלמה למכשיר. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
פודקאסט וידאו | אופציונלי | ערך בוליאני שמציין אם פרק הפודקאסט כולל תוכן וידאו |
תוכן בוטה | אופציונלי |
ערך בוליאני שמציין אם התוכן בוטה או לא פריטים שמכילים תוכן בוטה או שיש בהם השגחת הורים צריך להגדיר את האזהרה ל-TRUE. פריטים שמכילים תוכן בוטה מופיעים עם האות 'E' התיוג. |
האזנה לסוג הבא | אופציונלי |
מומלץ לפריטים באשכול ההמשך TYPE_Continue – המשך בפריט אודיו לא גמור. TYPE_NEXT - המשך סדרה חדשה מתוך סדרה. TYPE_NEW – גרסה חדשה. |
מועד ההתעניינות האחרונה | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
אחוז ההתקדמות הושלם | אופציונלי |
מומלץ לפריטים באשכול ההמשך. מספר שלם בין 0 ל-100 |
LiveRadioStationEntity
האובייקט LiveRadioStationEntity
מייצג תחנת רדיו בשידור חי (עבור
לדוגמה, 98.1 הברז).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | שם תחנת הרדיו בשידור חי. |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. צפייה הנחיות לגבי מפרטי תמונות. |
URI להפעלה | חובה |
קישור עומק שמפעיל את תחנת הרדיו אצל הספק אפליקציה. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
URI של דף מידע | אופציונלי |
קישור עומק לאפליקציית הספק לקבלת פרטים על תחנת הרדיו. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תדירות | אופציונלי | התדר שבו תחנת הרדיו משודרת (לדוגמה, '98.1 FM'). |
שם התוכנית | אופציונלי | התוכנית הנוכחית שמשודרת בתחנת הרדיו. |
מארחים | אופציונלי | רשימת המארחים של תחנת הרדיו. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
מועד ההתעניינות האחרון | אופציונלי |
מומלץ לפריטים באשכול ההמשך. יכול להיות שימוש עבור דירוג. בפרק זמן של אלפיות שנייה |
AudiobookEntity
האובייקט AudiobookEntity
מייצג ספר אודיו (למשל, ספר האודיו).
של Beving על ידי מישל אובמה).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטר | חובה | יש לספק תמונה אחת לפחות. לעיון בקטע תמונה מפרטים לקבלת הנחיות. |
מחבר | חובה | יש לספק שם מחבר אחד לפחות. |
Narrator | חובה | יש לספק שם אחד לפחות של קריין. |
URI של קישור לפעולה | חובה |
קישור העומק לאפליקציית הספק של ספר האודיו. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תאריך פרסום | אופציונלי | בפרק זמן של אלפיות שנייה, אם צוין. |
תיאור | אופציונלי | האורך המרבי הוא 200 תווים, אם מזינים אותו. |
מחיר | אופציונלי | טקסט חופשי |
Duration | אופציונלי | אם ציינתם ערך, הוא חייב להיות חיובי. |
ז'אנר | אופציונלי | רשימת הז'אנרים המשויכים לספר. |
שם הסדרה | אופציונלי | שם הסדרה שאליה שייך ספר האודיו (למשל, הארי פוטר. |
אינדקס יחידות של סדרה | אופציונלי | אינדקס ספר האודיו בסדרה, כאשר 1 הוא ספר האודיו הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר של Azkaban הוא הספר השלישי בסדרה, וצריך להגדיר אותו ל-3. |
המשך סוג הספר | אופציונלי |
TYPE_TSS – המשך בספר לא גמור. TYPE_NEXT - המשך סדרה חדשה מתוך סדרה. TYPE_NEW – גרסה חדשה. |
מועד האינטראקציה האחרונה | נדרש באופן מותנה | יש לציין כשהפריט נמצא באשכול ההמשך. בפרק זמן של אלפיות שנייה. |
אחוז ההתקדמות הושלם | נדרש באופן מותנה |
יש לציין כשהפריט נמצא באשכול ההמשך. *ספרי אודיו שנרכשו לאחרונה* יכולים להיות חלק מהמשך הקריאה אשכול. הערך צריך להיות גדול מ-0 וקטן מ-100. |
DisplayTimeWindow – הגדרת חלון זמן לתוכן יוצגו בפלטפורמה | ||
חותמת זמן ההתחלה | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן אמור להיות מוצג פלטפורמה. אם המדיניות לא מוגדרת, התוכן יכול להופיע בפלטפורמה. בפרק זמן של אלפיות שנייה. |
חותמת זמן של סיום | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן כבר לא מוצג את פני השטח. אם המדיניות לא מוגדרת, התוכן יכול להופיע בפלטפורמה. בפרק זמן של אלפיות שנייה. |
מפרט לתמונות
המפרטים הנדרשים לנכסי תמונות מפורטים בהמשך:
יחס גובה-רוחב | דרישה | מספר פיקסלים מינימלי | מספר פיקסלים מומלץ |
---|---|---|---|
תמונה ריבועית: (1X1) | חובה | 300x300 | 1,200x1,200 |
תמונה לרוחב (1.91X1) | אופציונלי | 600x314 | 1,200x628 |
לאורך (4x5) | אופציונלי | 480x600 | 960 x 1,200 |
פורמטים של קבצים
PNG, JPG, GIF סטטי, WebP
גודל קובץ מקסימלי
5,120KB
המלצות נוספות
- האזור הבטוח של התמונות: צריך למקם את התוכן החשוב ב-80% המרכזיים של תמונה.
דוגמאות
MusicAlbumEntity musicAlbumEntity =
new MusicAlbumEntity.Builder()
.setName(NAME)
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.setPlayBackUri("https://play.google/album/play")
.setInfoPageUri("https://play.google/album/info")
.setDescription("A description of this album.")
.addArtist("Artist")
.addGenre("Genre")
.addMusicLabel("Label")
.addContentRating("Rating")
.setSongsCount(960)
.setReleaseDateEpochMillis(1633032895L)
.setDurationMillis(1633L)
.build();
AudiobookEntity audiobookEntity =
new AudiobookEntity.Builder()
.setName("Becoming")
.addPosterImage(new Image.Builder()
.setImageUri(Uri.parse("http://www.x.com/image.png"))
.setImageHeightInPixel(960)
.setImageWidthInPixel(408)
.build())
.addAuthor("Michelle Obama")
.addNarrator("Michelle Obama")
.setActionLinkUri(
Uri.parse("https://play.google/audiobooks/1"))
.setDurationMillis(16335L)
.setPublishDateEpochMillis(1633032895L)
.setDescription("An intimate, powerful, and inspiring memoir")
.setPrice("$16.95")
.addGenre("biography")
.build();
שלב 2: מספקים נתוני אשכול
מומלץ לבצע את משימת פרסום התוכן ברקע (לדוגמה, באמצעות WorkManager) והם מתוזמנים על בסיס קבוע או על בסיס אירוע (לדוגמה, בכל פעם שהמשתמש פותח את האפליקציה או רק כשהוא הוסיף משהו לעגלת הקניות).
AppEngagePublishClient
אחראי לפרסום אשכולות. כבר במעקב
ממשקי API זמינים ב-Client:
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("Trending music") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Trending music") .build()) .build());
כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בתוך עסקה אחת:
- הנתונים הקיימים של
RecommendationCluster
מהשותף למפתחים יוסרו. - הנתונים מהבקשה מנותחים ונשמרים בהמלצה המעודכנת אשכול.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים מתוחזקת.
publishFeaturedCluster
ה-API הזה משמש לפרסום רשימה של FeaturedCluster
אובייקטים.
Kotlin
client.publishFeaturedCluster( PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( FeaturedCluster.Builder() ... .build()) .build())
Java
client.publishFeaturedCluster( new PublishFeaturedClusterRequest.Builder() .setFeaturedCluster( new FeaturedCluster.Builder() ... .build()) .build());
כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בתוך עסקה אחת:
- הנתונים הקיימים של
FeaturedCluster
מהשותף למפתחים יוסרו. - הנתונים מהבקשה מנותחים ונשמרים באשכול המעודכן.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים מתוחזקת.
publishContinuationCluster
ה-API הזה משמש לפרסום אובייקט ContinuationCluster
.
Kotlin
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
Java
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .build()) .build())
כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בתוך עסקה אחת:
- הנתונים הקיימים של
ContinuationCluster
מהשותף למפתחים יוסרו. - נתונים מהבקשה מנותחים ונשמרים במצב המשך המעודכן אשכול.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים מתוחזקת.
publishUserAccountManagementRequest
ממשק ה-API הזה משמש לפרסום כרטיס כניסה . פעולת הכניסה מפנה משתמשים אל דף הכניסה של האפליקציה, כדי שהאפליקציה תוכל לפרסם תוכן (או לספק עוד תוכן בהתאמה אישית)
המטא-נתונים הבאים הם חלק מכרטיס הכניסה –
מאפיין | דרישה | תיאור |
---|---|---|
URI של פעולה | חובה | קישור עומק לפעולה (כלומר מעבר לדף הכניסה לאפליקציה) |
תמונה | אופציונלי – אם לא מציינים כותרת, יש להזין כותרת |
תמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16x9 עם רזולוציה של 1264x712 |
כותרת | אופציונלי – אם לא צוין תמונה, יש לספק תמונה | כותרת על הכרטיס |
טקסט פעולה | אופציונלי | טקסט שמוצג בקריאה לפעולה (כלומר, כניסה לחשבון) |
כותרת משנה | אופציונלי | כתוביות אופציונליות בכרטיס |
Kotlin
var SIGN_IN_CARD_ENTITY = SignInCardEntity.Builder() .addPosterImage( Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build() client.publishUserAccountManagementRequest( PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Java
SignInCardEntity SIGN_IN_CARD_ENTITY = new SignInCardEntity.Builder() .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build(); client.publishUserAccountManagementRequest( new PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
כשהשירות מקבל את הבקשה, הפעולות הבאות מתרחשות בתוך עסקה אחת:
- הנתונים הקיימים של
UserAccountManagementCluster
מהשותף למפתחים הם הוסר. - נתונים מהבקשה מנותחים ונשמרים אשכול אשכול UserAccountManagement.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים מתוחזקת.
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.
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים אשכול UserAccountManagement. במקרה של שגיאה, הבקשה כולה נדחה והמצב הקיים נשמר.
deleteClusters
ה-API הזה משמש למחיקת התוכן של סוג אשכול נתון.
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build())
Java
client.deleteClusters( new DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_FEATURED) .addClusterType(ClusterType.TYPE_RECOMMENDATION) ... .build());
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מכל אשכולות שתואמים לסוגי האשכולות שצוינו. הלקוחות יכולים לבחור להעביר הרבה סוגים של אשכולות. במקרה של שגיאה, הבקשה כולה נדחית המצב הקיים נשמר.
טיפול בשגיאות
מומלץ מאוד להאזין לתוצאת המשימה מממשקי ה-API לפרסום, שניתן לבצע פעולת המשך כדי לשחזר משימה מוצלחת ולשלוח אותה מחדש.
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
עם הסיבה
קוד שגיאה.
קוד שגיאה | הערה |
---|---|
SERVICE_NOT_FOUND |
השירות לא זמין במכשיר הנתון. |
SERVICE_NOT_AVAILABLE |
השירות זמין במכשיר הנתון, אבל הוא לא זמין בזמן השיחה (לדוגמה, האפשרות מושבתת באופן מפורש). |
SERVICE_CALL_EXECUTION_FAILURE |
ביצוע המשימה נכשל עקב בעיות בשרשור. במקרה הזה, יכול להיות ניסיון חוזר. |
SERVICE_CALL_PERMISSION_DENIED |
המתקשר לא מורשה לבצע את שיחת השירות. |
SERVICE_CALL_INVALID_ARGUMENT |
הבקשה מכילה נתונים לא חוקיים (לדוגמה, יותר מהמותר מספר האשכולות). |
SERVICE_CALL_INTERNAL |
יש שגיאה בצד השירות. |
SERVICE_CALL_RESOURCE_EXHAUSTED |
הקריאה לשירות מתבצעת לעיתים קרובות מדי. |
שלב 3: טיפול בכוונות שידור
בנוסף לביצוע קריאות לפרסום Content API באמצעות משימה, מדובר גם
נדרשות כדי להגדיר
BroadcastReceiver
כדי לקבל
את הבקשה לפרסום תוכן.
המטרה של כוונות שידור היא בעיקר הפעלה מחדש של האפליקציה ואילוץ נתונים לסנכרן כוונת שידור לא מיועדת לשליחה בתדירות גבוהה מאוד. זה רק מופעלות כאשר שירות Engage קובע שהתוכן עשוי להיות מיושן (עבור למשל, לפני שבוע). כך, יש יותר ביטחון שהמשתמש יכול לספק חוויית תוכן חדשה, גם אם האפליקציה לא הופעלה הרבה זמן.
צריך להגדיר את BroadcastReceiver
בשתי הדרכים הבאות:
- רישום באופן דינמי של מופע של המחלקה
BroadcastReceiver
באמצעותContext.registerReceiver()
. כך מתאפשרת תקשורת מאפליקציות שעדיין קיימים בזיכרון.
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
. ההרשאה הזו מאפשרת לאפליקציה לקבל שידור את ה-Intent כאשר הוא לא פועל, וגם מאפשרת לאפליקציה לפרסם את התוכן.
<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>
הכוונות הבאות יישלחו על ידי service:
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, אם יש בזמן תהליך ההטמעה. הצוות שלנו יחזור אליך בהקדם ככל האפשר.
השלבים הבאים
לאחר השלמת השילוב, השלבים הבאים הם:
- שליחת אימייל אל engagement-developers@google.com וצירוף המסמך את ה-APK המשולב שמוכן לבדיקה על ידי Google.
- Google תבצע אימות ותבדוק באופן פנימי כדי לוודא פועל כמצופה. אם יהיה צורך בשינויים, Google תיצור איתך קשר את כל הפרטים הנדרשים.
- לאחר סיום הבדיקה ואין צורך בשינויים, Google תיצור איתך קשר כדי תודיע לך שאתה יכול להתחיל לפרסם את ה-APK המעודכן והמשולב חנות Play.
- לאחר ש-Google אישרה שה-APK המעודכן פורסם חנות Play, המלצה, מוצגת והמשך אשכולות יפורסמו ויהיו גלויים למשתמשים.