Google מפתחת ממשק במכשיר שמארגן את האפליקציות של המשתמשים לפי קטגוריות, ומאפשר חוויה חדשה ומרתקת של שימוש בתוכן האפליקציות וחיפוש תוכן מותאם אישית. חוויית הצפייה במסך מלא מספקת לשותפי הפיתוח הזדמנות להציג את התוכן העשיר והטוב ביותר שלהם בערוץ ייעודי מחוץ לאפליקציה.
במדריך הזה מוסבר לשותפי מפתחים איך לשלב את התוכן שלהם לקריאה באמצעות Engage SDK, כדי לאכלס את הממשק החדש הזה ואת הממשקים הקיימים של Google.
פרטי השילוב
טרמינולוגיה
השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, המשך ומומלץ.
באשכול המלצות מוצגות הצעות מותאמות אישית לתוכן לקריאה של שותף פיתוח ספציפי.
ההמלצות מופיעות במבנה הבא:
אשכול המלצות: תצוגת ממשק משתמש שמכילה קבוצה של המלצות ממפתח שותף אחד.
איור 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.5.2'
}
סיכום
התכנון מבוסס על הטמעה של שירות מוגדר.
הנתונים שלקוח יכול לפרסם כפופים למגבלות הבאות לסוגים שונים של אשכולות:
סוג האשכול | מגבלות על אשכולות | מגבלות מקסימליות של ישויות באשכול |
---|---|---|
אשכולות של המלצות | עד 7 | 50 לכל היותר |
אשכול המשכיות | 1 לכל היותר | עד 20 |
אשכול מומלץ | 1 לכל היותר | עד 20 |
שלב 1: מציינים את נתוני הישות
ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים בישויות הבאות בקטגוריה 'קריאה':
EbookEntity
AudiobookEntity
BookSeriesEntity
בטבלאות הבאות מפורטים המאפיינים והדרישות הזמינים לכל סוג.
EbookEntity
האובייקט EbookEntity
מייצג ספר דיגיטלי (לדוגמה, הספר הדיגיטלי של Becoming מאת מישל אובמה).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לספק לפחות תמונה אחת. לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
מחבר | חובה | צריך לציין לפחות שם אחד של מחבר. |
ה-URI של הקישור לפעולה | חובה |
קישור העומק לאפליקציית הספק של האלבום הדיגיטלי. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תאריך פרסום | אופציונלי | באלפיות שנייה לפי ראשית זמן יוניקס (epoch), אם צוין. |
תיאור | אופציונלי | אם מציינים שם, הוא חייב להכיל עד 200 תווים. |
מחיר | אופציונלי | טקסט חופשי |
מספר עמודים | אופציונלי | אם מציינים ערך, הוא חייב להיות מספר שלם חיובי. |
ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
שם הסדרה | אופציונלי | שם הסדרה שאליה הספר האלקטרוני שייך (לדוגמה, Harry Potter). |
אינדקס היחידה בסדרה | אופציונלי | האינדקס של הספר הדיגיטלי בסדרה, כאשר 1 הוא הספר הדיגיטלי הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, צריך להגדיר את הערך הזה כ-3. |
סוג האלבום להמשך | אופציונלי |
TYPE_CONTINUE – המשך קריאה בספר שלא הושלם. TYPE_NEXT – המשך לפריט חדש בסדרה. TYPE_NEW – גרסה חדשה. |
מועד האינטראקציה האחרונה | נדרש באופן מותנה |
צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. ספרים אלקטרוניים *חדשים* שנרכשו יכולים להיכלל באשכול 'המשך קריאה'. באלפיות השנייה של עידן. |
אחוז ההתקדמות | נדרש באופן מותנה |
צריך לספק את הערך הזה כשהפריט נמצא באשכול Continuation. הערך צריך להיות גדול מ-0 וקטן מ-100. |
DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן במכשיר | ||
חותמת הזמן של ההתחלה | אופציונלי |
חותמת הזמן של תחילת המאה (epoch) שאחרי שתוקף התוכן יוצג בממשק. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
חותמת זמן של סיום | אופציונלי |
חותמת הזמן של עידן (epoch) שאחרי שתוקף התוכן יפוג. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
AudiobookEntity
האובייקט AudiobookEntity
מייצג ספר אודיו (לדוגמה, ספר האודיו של Becoming מאת מישל אובמה).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לספק לפחות תמונה אחת. לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
מחבר | חובה | צריך לציין לפחות שם אחד של מחבר. |
Narrator | חובה | צריך לציין לפחות שם של קריין אחד. |
ה-URI של הקישור לפעולה | חובה |
קישור העומק לאפליקציית הספק של האודיו-ספר. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
תאריך פרסום | אופציונלי | באלפיות שנייה לפי ראשית זמן יוניקס (epoch), אם צוין. |
תיאור | אופציונלי | אם מציינים שם, הוא חייב להכיל עד 200 תווים. |
מחיר | אופציונלי | טקסט חופשי |
משך הזמן | אופציונלי | אם מציינים ערך, הוא חייב להיות חיובי. |
ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
שם הסדרה | אופציונלי | שם הסדרה שאליה שייך אודיו הספר (לדוגמה, Harry Potter). |
אינדקס היחידה בסדרה | אופציונלי | האינדקס של ספרי האודיו בסדרה, כאשר 1 הוא ספרי האודיו הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, צריך להגדיר את הערך הזה כ-3. |
סוג האלבום להמשך | אופציונלי |
TYPE_CONTINUE – המשך קריאה בספר שלא הושלם. TYPE_NEXT – המשך לפריט חדש בסדרה. TYPE_NEW – גרסה חדשה. |
מועד האינטראקציה האחרונה | נדרש באופן מותנה | צריך לציין את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות השנייה של עידן. |
אחוז ההתקדמות | נדרש באופן מותנה |
צריך לציין את הערך הזה כשהפריט נמצא באשכול Continuation. ספרי אודיו *חדשים* שנרכשו יכולים להיכלל באשכול 'המשך קריאה'. הערך צריך להיות גדול מ-0 וקטן מ-100. |
DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן במכשיר | ||
חותמת הזמן של ההתחלה | אופציונלי |
חותמת הזמן של תחילת המאה (epoch) שאחרי שתוקף התוכן יוצג בממשק. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
חותמת זמן של סיום | אופציונלי |
חותמת הזמן של עידן (epoch) שאחרי שתוקף התוכן יפוג. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
BookSeriesEntity
האובייקט BookSeriesEntity
מייצג סדרת ספרים (לדוגמה, סדרת הספרים הארי פוטר, שמכילה 7 ספרים).
מאפיין | דרישה | הערות |
---|---|---|
שם | חובה | |
תמונות של פוסטרים | חובה | צריך לספק לפחות תמונה אחת. לקבלת הנחיות, אפשר לעיין במפרט לתמונות. |
מחבר | חובה | צריך להופיע לפחות שם אחד של מחבר. |
ה-URI של הקישור לפעולה | חובה |
קישור העומק לאפליקציית הספק של ספר האודיו או הספר הדיגיטלי. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך. אפשר לעיין בשאלות הנפוצות האלה |
מספר הספרים | חובה | מספר הספרים בסדרה. |
תיאור | אופציונלי | אם מציינים שם, הוא חייב להכיל עד 200 תווים. |
ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
סוג האלבום להמשך | אופציונלי |
TYPE_CONTINUE – המשך קריאה בספר שלא הושלם. TYPE_NEXT – המשך לפריט חדש בסדרה. TYPE_NEW – גרסה חדשה. |
מועד האינטראקציה האחרונה | נדרש באופן מותנה | צריך לציין את הערך הזה כשהפריט נמצא באשכול Continuation. באלפיות השנייה של עידן. |
אחוז ההתקדמות | נדרש באופן מותנה | צריך לציין את הערך הזה כשהפריט נמצא באשכול Continuation. סדרות ספרים *חדשות* שנרכשו יכולות להיכלל באשכול 'המשך קריאה'. הערך צריך להיות גדול מ-0 וקטן מ-100. |
DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן במכשיר | ||
חותמת הזמן של ההתחלה | אופציונלי |
חותמת הזמן של תחילת המאה (epoch) שאחרי שתוקף התוכן יוצג בממשק. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
חותמת זמן של סיום | אופציונלי |
חותמת הזמן של עידן (epoch) שאחרי שתוקף התוכן יפוג. אם המדיניות לא מוגדרת, התוכן עומד בדרישות להצגה בממשק. באלפיות השנייה של עידן. |
מפרט לתמונות
המפרטים הנדרשים לנכסי תמונות מפורטים בהמשך:
יחס גובה-רוחב | דרישה | מספר פיקסלים מינימלי | מספר פיקסלים מומלץ |
---|---|---|---|
ריבוע (1x1) | חובה | 300x300 | 1,200x1,200 |
לרוחב (1.91x1) | אופציונלי | 600x314 | 1,200x628 |
לאורך (4x5) | אופציונלי | 480x600 | 960x1200 |
פורמטים של קבצים
PNG, JPG, GIF סטטי, WebP
גודל קובץ מקסימלי
5,120 KB
המלצות נוספות
- האזור הבטוח לתמונות: התוכן החשוב צריך להופיע במרכז התמונה, על פני 80% ממנה.
דוגמה
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 הבאים זמינים בלקוח:
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("Reconnect with yourself") .build()) .build())
Java
client.publishRecommendationClusters( new PublishRecommendationClustersRequest.Builder() .addRecommendationCluster( new RecommendationCluster.Builder() .addEntity(entity1) .addEntity(entity2) .setTitle("Reconnect with yourself") .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(book_entity1) .addEntity(book_entity2) .build()) .build())
Java
client.publishContinuationCluster( PublishContinuationClusterRequest.Builder() .setContinuationCluster( ContinuationCluster.Builder() .addEntity(book_entity1) .addEntity(book_entity2) .build()) .build())
כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:
- הנתונים הקיימים של
ContinuationCluster
מהשותף המפתח יוסרו. - הנתונים מהבקשה מנותחים ונשמרים באשכול Continuation המעודכן.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
publishUserAccountManagementRequest
ה-API הזה משמש לפרסום כרטיס כניסה . פעולת הכניסה מפנה את המשתמשים לדף הכניסה של האפליקציה כדי שהאפליקציה תוכל לפרסם תוכן (או לספק תוכן מותאם אישית יותר).
המטא-נתונים הבאים הם חלק מכרטיס הכניסה:
מאפיין | דרישה | תיאור |
---|---|---|
URI של פעולה | חובה | קישור עומק לפעולה (כלומר, ניווט לדף הכניסה לאפליקציה) |
תמונה | אופציונלי – אם לא מציינים אותו, צריך לציין את השם |
התמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16x9 ברזולוציה של 1264x712 |
כותרת | אופציונלי – אם לא מציינים אותו, צריך לציין את Image | השם בכרטיס |
טקסט הפעולה | אופציונלי | הטקסט שמוצג בקריאה לפעולה (למשל 'כניסה') |
כותרת משנה | אופציונלי | כתוביות אופציונליות בכרטיס |
Kotlin
var SIGN_IN_CARD_ENTITY = SignInCardEntity.Builder() .addPosterImage( Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build() client.publishUserAccountManagementRequest( PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
Java
SignInCardEntity SIGN_IN_CARD_ENTITY = new SignInCardEntity.Builder() .addPosterImage( new Image.Builder() .setImageUri(Uri.parse("http://www.x.com/image.png")) .setImageHeightInPixel(500) .setImageWidthInPixel(500) .build()) .setActionText("Sign In") .setActionUri(Uri.parse("http://xx.com/signin")) .build(); client.publishUserAccountManagementRequest( new PublishUserAccountManagementRequest.Builder() .setSignInCardEntity(SIGN_IN_CARD_ENTITY) .build());
כשהבקשה מתקבלת בשירות, מתבצעות הפעולות הבאות בעסקה אחת:
- הנתונים הקיימים של
UserAccountManagementCluster
מהשותף המפתח יוסרו. - הנתונים מהבקשה מנותחים ונשמרים באשכול המעודכן UserAccountManagementCluster.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
updatePublishStatus
אם אף אחד מהאשכולות לא פורסם מסיבה עסקית פנימית כלשהי, מומלץ מאוד לעדכן את סטטוס הפרסום באמצעות ה-API updatePublishStatus. חשוב לציין זאת מהסיבות הבאות :
- חשוב לספק את הסטטוס בכל התרחישים, גם כשהתוכן פורסם (STATUS == PUBLISHED), כדי לאכלס מרכזי בקרה שמשתמשים בסטטוס המפורש הזה כדי להעביר את סטטוס התקינות ומדדים אחרים של השילוב.
- אם לא פורסם תוכן אבל סטטוס השילוב תקין (STATUS == NOT_PUBLISHED), Google יכולה להימנע מהפעלת התראות בלוחות הבקרה של בריאות האפליקציה. הוא מאשר שהתוכן לא פורסם בגלל מצב צפוי מנקודת המבט של הספק.
- היא עוזרת למפתחים לספק תובנות לגבי הזמנים שבהם הנתונים מתפרסמים, לעומת הזמנים שבהם הם לא מתפרסמים.
- Google עשויה להשתמש בקודי המצב כדי לעודד את המשתמש לבצע פעולות מסוימות באפליקציה, כדי שיוכל לראות את תוכן האפליקציה או להתגבר עליו.
רשימת קודי הסטטוס של פרסום שעומדים בדרישות :
// Content is published
AppEngagePublishStatusCode.PUBLISHED,
// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,
// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,
// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,
// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,
// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,
// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,
// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,
// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER
אם התוכן לא פורסם כי המשתמש לא מחובר לחשבון, Google ממליצה לפרסם את כרטיס הכניסה. אם מסיבה כלשהי הספקים לא יכולים לפרסם את כרטיס הכניסה, מומלץ לבצע קריאה ל-API updatePublishStatus עם קוד הסטטוס NOT_PUBLISHED_REQUIRES_SIGN_IN.
Kotlin
client.updatePublishStatus( PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build())
Java
client.updatePublishStatus( new PublishStatusRequest.Builder() .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN) .build());
deleteRecommendationClusters
ממשק ה-API הזה משמש למחיקת התוכן של אשכולות ההמלצות.
Kotlin
client.deleteRecommendationClusters()
Java
client.deleteRecommendationClusters();
כשהבקשה מתקבלת בשירות, הנתונים הקיימים מוסרים מאשכולות ההמלצות. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
deleteFeaturedCluster
ממשק ה-API הזה משמש למחיקת התוכן של 'אוסף פריטים נבחרים'.
Kotlin
client.deleteFeaturedCluster()
Java
client.deleteFeaturedCluster();
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מהאשכול הנבחר. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
deleteContinuationCluster
ממשק ה-API הזה משמש למחיקת התוכן של אשכול ההמשך.
Kotlin
client.deleteContinuationCluster()
Java
client.deleteContinuationCluster();
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מאשכול ההמשך. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
deleteUserManagementCluster
ממשק ה-API הזה משמש למחיקת התוכן של UserAccountManagement Cluster.
Kotlin
client.deleteUserManagementCluster()
Java
client.deleteUserManagementCluster();
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מהאשכול UserAccountManagement. במקרה של שגיאה, הבקשה כולה תידחה והמצב הקיים יישמר.
deleteClusters
ממשק ה-API הזה משמש למחיקת התוכן של סוג אשכול נתון.
Kotlin
client.deleteClusters( DeleteClustersRequest.Builder() .addClusterType(ClusterType.TYPE_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
, והסיבה כלולה כקוד שגיאה.
קוד שגיאה | שם השגיאה | הערה |
---|---|---|
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()
. כך אפשר לתקשר עם אפליקציות שעדיין נמצאות בזיכרון.
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
It is recommended to start a
publishContinuationCluster` כשמקבלים את הכוונה הזו.
תהליך העבודה של השילוב
במדריך המפורט תהליך השילוב של Engage למפתחים מוסבר איך מאמתים את השילוב אחרי שהוא הושלם.
שאלות נפוצות
איש/אשת הקשר
אם יש לכם שאלות במהלך תהליך השילוב, תוכלו לפנות לכתובת engage-developers@google.com. הצוות שלנו ישיב בהקדם האפשרי.
השלבים הבאים
אחרי השלמת השילוב, עליכם לבצע את השלבים הבאים:
- שולחים אימייל לכתובת engage-developers@google.com ומצרפים את קובץ ה-APK המשולב שעומד בקריטריונים לבדיקה על ידי Google.
- Google תבצע אימות ובדיקה פנימית כדי לוודא שהשילוב פועל כצפוי. אם יהיה צורך בשינויים, Google תיצור איתכם קשר עם הפרטים הנדרשים.
- בסיום הבדיקה, אם לא נדרשים שינויים, Google תיצור איתכם קשר כדי להודיע לכם שתוכלו להתחיל לפרסם את קובץ ה-APK המעודכן והמשולב ב-Play Store.
- אחרי ש-Google תאשר שה-APK המעודכן שלכם פורסם ב-Play Store, האשכולות המלצות, מומלצות והמשך יפורסמו ויוצגו למשתמשים.