כדי להגביר את רמת העניין באפליקציה, כדאי להגיע למשתמשים במקומות שבהם הם נמצאים. אפשר לשלב את Engage SDK כדי להציג המלצות מותאמות אישית ותוכן המשך ישירות למשתמשים בכמה פלטפורמות במכשיר, כמו אוספים, חבילת הבידור וחנות Play. השילוב מוסיף פחות מ-50KB (לאחר דחיסה) לקובץ ה-APK הממוצע, וברוב האפליקציות הוא דורש כשבוע של עבודת פיתוח. מידע נוסף זמין באתר העסקי שלנו.
המדריך הזה מכיל הוראות לשותפים מפתחים להעברת תוכן קריאה (ספרים דיגיטליים, ספרי אודיו, קומיקס ומאנגה) אל ממשקי תוכן של Engage.
פרטי השילוב
הסברים על המונחים
השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, המשך ומומלץ.
באשכולות המלצות מוצגות הצעות מותאמות אישית לתוכן לקריאה ממפתח שותף ספציפי.
ההמלצות שלכם בנויות באופן הבא:
אשכול המלצות: תצוגת ממשק משתמש שמכילה קבוצה של המלצות משותף פיתוח אחד.
איור 1. ממשק המשתמש של חבילת הבידור שבו מוצגות המלצות של שותף יחיד. ישות: אובייקט שמייצג פריט יחיד באשכול. ישות יכולה להיות ספר דיגיטלי, ספר אודיו, סדרת ספרים ועוד. רשימה של סוגי ישויות נתמכים מופיעה בקטע הוספת נתוני ישויות.
איור 2. ממשק המשתמש של חבילת הבידור שבו מוצגות ישות אחת בתוך קבוצת המלצות של שותף אחד.
אוסף ההמשכים מציג ספרים שלא סיימתם לקרוא מכמה שותפים מפתחים בקבוצה אחת בממשק המשתמש. כל שותף מפתח יוכל לשדר עד 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.6.0'
}
סיכום
העיצוב מבוסס על הטמעה של שירות קשור.
הנתונים שלקוח יכול לפרסם כפופים למגבלות הבאות עבור סוגים שונים של אשכולות:
| סוג האשכול | מגבלות על אשכולות | מגבלות מקסימליות של ישויות באשכול |
|---|---|---|
| אשכולות של המלצות | עד 7 | עד 50 |
| אשכול המשכיות | עד 1 | עד 20 |
| אשכול מוצג | עד 1 | עד 20 |
שלב 1: הזנת נתוני הישות
ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים בישויות הבאות בקטגוריה 'קריאה':
EbookEntityAudiobookEntityBookSeriesEntity
בתרשימים הבאים מפורטים המאפיינים הזמינים והדרישות לכל סוג.
EbookEntity
אובייקט EbookEntity מייצג ספר דיגיטלי (לדוגמה, הספר הדיגיטלי Becoming של מישל אובמה).
| מאפיין | דרישה | הערות |
|---|---|---|
| שם | חובה | |
| תמונות פוסטר | חובה | צריך לספק לפחות תמונה אחת. הנחיות זמינות במאמר בנושא מפרטים של תמונות. |
| מחבר | חובה | צריך לציין לפחות שם מחבר אחד. |
| URI של קישור לפעולה | חובה |
קישור העומק לאפליקציה לבעלי מקצוע לספר הדיגיטלי. הערה: אפשר להשתמש בקישורי עומק לשיוך (Attribution). אפשר לעיין בשאלות הנפוצות |
| תאריך פרסום | אופציונלי | באמצעות אלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch), אם צוין. |
| תיאור | אופציונלי | אם מציינים את התיאור, הוא צריך לכלול עד 200 תווים. |
| מחיר | אופציונלי | טקסט חופשי |
| מספר עמודים | אופציונלי | אם מציינים ערך, הוא חייב להיות מספר שלם חיובי. |
| ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
| שם הסדרה | אופציונלי | שם הסדרה שאליה הספר הדיגיטלי שייך (לדוגמה, Harry Potter). |
| אינדקס יחידות של סדרות | אופציונלי | האינדקס של הספר הדיגיטלי בסדרה, כאשר 1 הוא הספר הדיגיטלי הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, הערך צריך להיות 3. |
| המשך סוג הספר | אופציונלי |
TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בספר חדש בסדרה. TYPE_NEW – חדש. |
| מועד האינטראקציה האחרונה | חובה באופן מותנה |
חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. ספרים דיגיטליים שנרכשו *לאחרונה* יכולים להיכלל בקבוצת הספרים 'המשך קריאה'. באפוקה באלפיות השנייה. |
| אחוז ההתקדמות שהושלם | חובה באופן מותנה |
חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. הערך חייב להיות גדול מ-0 וקטן מ-100. |
| DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה | ||
| חותמת זמן של התחלה | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן צריך להיות מוצג במשטח. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
| חותמת זמן של סיום | אופציונלי |
חותמת הזמן של העידן שאחריה התוכן לא מוצג יותר בפלטפורמה. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
AudiobookEntity
אובייקט AudiobookEntity מייצג ספר אודיו (לדוגמה, ספר האודיו של Becoming מאת מישל אובמה).
| מאפיין | דרישה | הערות |
|---|---|---|
| שם | חובה | |
| תמונות פוסטר | חובה | צריך לספק לפחות תמונה אחת. הנחיות זמינות במאמר בנושא מפרטים של תמונות. |
| מחבר | חובה | צריך לציין לפחות שם מחבר אחד. |
| URI של קישור לפעולה | חובה |
קישור העומק לאפליקציה לבעלי מקצוע של ספר האודיו. הערה: אפשר להשתמש בקישורי עומק לשיוך (Attribution). אפשר לעיין בשאלות הנפוצות |
| Narrator | אופציונלי | צריך לציין לפחות שם אחד של קריין. |
| תאריך פרסום | אופציונלי | באמצעות אלפיות השנייה מאז ראשית זמן יוניקס (Unix epoch), אם צוין. |
| תיאור | אופציונלי | אם מציינים את התיאור, הוא צריך לכלול עד 200 תווים. |
| מחיר | אופציונלי | טקסט חופשי |
| משך | אופציונלי | אם מציינים ערך, הוא חייב להיות חיובי. |
| ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
| שם הסדרה | אופציונלי | שם הסדרה שאליה שייך ספר האודיו (לדוגמה, Harry Potter). |
| אינדקס יחידות של סדרות | אופציונלי | האינדקס של ספר האודיו בסדרה, כאשר 1 הוא ספר האודיו הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, הערך צריך להיות 3. |
| המשך סוג הספר | אופציונלי |
TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בספר חדש בסדרה. TYPE_NEW – חדש. |
| מועד האינטראקציה האחרונה | חובה באופן מותנה | חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. באפוקה באלפיות השנייה. |
| אחוז ההתקדמות שהושלם | חובה באופן מותנה |
חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. ספרי אודיו שנרכשו *לאחרונה* יכולים להיות חלק מהאוסף 'המשך קריאה'. הערך חייב להיות גדול מ-0 וקטן מ-100. |
| DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה | ||
| חותמת זמן של התחלה | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן צריך להיות מוצג במשטח. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
| חותמת זמן של סיום | אופציונלי |
חותמת הזמן של העידן שאחריה התוכן לא מוצג יותר בפלטפורמה. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
BookSeriesEntity
אובייקט BookSeriesEntity מייצג סדרת ספרים (לדוגמה, סדרת הספרים Harry Potter, שכוללת 7 ספרים).
| מאפיין | דרישה | הערות |
|---|---|---|
| שם | חובה | |
| תמונות פוסטר | חובה | צריך לספק לפחות תמונה אחת. הנחיות זמינות במאמר בנושא מפרטים של תמונות. |
| מחבר | חובה | צריך לציין לפחות שם מחבר אחד. |
| URI של קישור לפעולה | חובה |
קישור העומק לאפליקציה של הספק שדרכה אפשר להאזין לספר האודיו או לקרוא את הספר הדיגיטלי. הערה: אפשר להשתמש בקישורי עומק לשיוך (Attribution). אפשר לעיין בשאלות הנפוצות |
| מספר הספרים | חובה | מספר הספרים בסדרה. |
| תיאור | אופציונלי | אם מציינים את התיאור, הוא צריך לכלול עד 200 תווים. |
| ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
| המשך סוג הספר | אופציונלי |
TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בספר חדש בסדרה. TYPE_NEW – חדש. |
| מועד האינטראקציה האחרונה | חובה באופן מותנה | חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. באפוקה באלפיות השנייה. |
| אחוז ההתקדמות שהושלם | חובה באופן מותנה | חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. סדרות ספרים שנרכשו *לאחרונה* יכולות להיכלל בקבוצת הספרים 'המשך קריאה'. הערך חייב להיות גדול מ-0 וקטן מ-100. |
| DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה | ||
| חותמת זמן של התחלה | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן צריך להיות מוצג במשטח. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
| חותמת זמן של סיום | אופציונלי |
חותמת הזמן של העידן שאחריה התוכן לא מוצג יותר בפלטפורמה. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
מפרט לתמונות
בהמשך מפורטות הדרישות לגבי נכסי תמונות:
| יחס גובה-רוחב | אשכולות נתמכים | מספר פיקסלים מינימלי | מספר פיקסלים מומלץ |
|---|---|---|---|
| ריבוע (1x1) | כל האשכולות | 300x300 | 1,200x1,200 |
| תמונה לרוחב (1.91x1) | תוכן מומלץ והמשך | 600x314 | 1,200x628 |
| לאורך (4x5) | המלצה | 480x600 | 960x1200 |
פורמטים של קבצים
PNG, JPG, GIF סטטי, WebP
גודל קובץ מקסימלי
5120 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 הבאים זמינים בלקוח:
isServiceAvailablepublishRecommendationClusterspublishFeaturedClusterpublishContinuationClusterpublishUserAccountManagementRequestupdatePublishStatusdeleteRecommendationsClustersdeleteFeaturedClusterdeleteContinuationClusterdeleteUserManagementClusterdeleteClusters
isServiceAvailable
ה-API הזה משמש כדי לבדוק אם השירות זמין לשילוב ואם אפשר להציג את התוכן במכשיר.
Engage SDK מגרסה 1.6.0 ואילך (מומלץ)
אתם יכולים לבדוק את זמינות השירות לכל סוג של אשכול שאתם מתכוונים לפרסם. isServiceAvailable API מקבל אובייקט בקשה, ServiceAvailabilityRequest, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ClusterTypeערכי ה-enum
הנדרשים עבור 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 לסירוגין כדי להפחית את עלות ההצגה שלהן. אסטרטגיית ניתוח התוכן הזו, שמתבצעת לסירוגין, אפשרית אבל היא משפיעה לרעה על המשתמש ועל המוצר – תוכן מיושן (stale) לא יוצג, ובחלק מהפלטפורמות לא יוצגו מודעות בכלל.
החל מגרסה 1.6.0, ה-Engage SDK מאפשר לבדוק את הזמינות של סוגים ספציפיים של אשכולות. כך יש יותר גמישות, ואם אפליקציה מסוימת מאמצת את אסטרטגיית התוכן לסירוגין, חלק מסוגי האוספים יכולים לפעול לפי האסטרטגיה הזו, בעוד שסוגים אחרים של אוספים תמיד מופעלים (כלומר, אוספי המשכים).
אם שירות Engage לא צריך להיות מופעל 'באופן רציף' בכל המכשירים הנתמכים מסיבה כלשהי, והוא מוגדר להטמעה לסירוגין עבור קבוצה כלשהי של מכשירים, כל הפרסומים של אשכול ההמשכיות (למשל, 'המשך קריאה') עדיין יופעלו כברירת מחדל, ושאר סוגי האשכולות יופעלו ויכובו לסירוגין. אם אתם משתמשים בהטמעה לסירוגין אבל הגדרת ברירת המחדל הזו לא מתאימה לצרכים שלכם, אתם יכולים לפנות לכתובת engage-developers@google.com.
לגרסאות 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.
}
});
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משותף המפתחים יוסרו. - הנתונים מהבקשה מנותחים ומאוחסנים ב-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משותף המפתחים יוסרו. - הנתונים מהבקשה מנותחים ומאוחסנים ב-ContinuationCluster המעודכן.
במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
publishUserAccountManagementRequest
ה-API הזה משמש לפרסום כרטיס כניסה . פעולת הכניסה מפנה את המשתמשים לדף הכניסה של האפליקציה כדי שהאפליקציה תוכל לפרסם תוכן (או לספק תוכן מותאם אישית יותר)
המטא-נתונים הבאים הם חלק מכרטיס הכניסה –
| מאפיין | דרישה | תיאור |
|---|---|---|
| URI של הפעולה | חובה | קישור עומק לפעולה (כלומר, מעבר לדף הכניסה לאפליקציה) |
| תמונה | אופציונלי – אם לא מספקים את הערך הזה, חובה לספק את הערך Title |
התמונה שמוצגת בכרטיס תמונות עם יחס גובה-רוחב של 16:9 ורזולוציה של 1264x712 |
| כותרת | אופציונלי – אם לא מספקים תמונה, חובה לספק סרטון | השם של הכרטיס |
| טקסט פעולה | אופציונלי | הטקסט שמוצג ב-CTA (למשל, 'כניסה') |
| כותרת משנה | אופציונלי | כתובית אופציונלית בכרטיס |
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 הזה משמש למחיקת התוכן של Continuation Cluster.
Kotlin
client.deleteContinuationCluster()
Java
client.deleteContinuationCluster();
כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מ-Continuation Cluster. במקרה של שגיאה, הבקשה כולה נדחית והמצב הקיים נשמר.
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: טיפול ב-Intents של שידור
בנוסף לקריאות ל-API לפרסום תוכן דרך משימה, צריך גם להגדיר BroadcastReceiver כדי לקבל את הבקשה לפרסום תוכן.
המטרה של שידור כוונות היא בעיקר הפעלה מחדש של אפליקציות וכפייה של סנכרון נתונים. ה-Intents של שידורים לא נועדו להישלח בתדירות גבוהה מאוד. ההתראה מופעלת רק כשהשירות של 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. ההרשאה הזו מאפשרת לאפליקציה לקבל שידורי Intent כשהיא לא פועלת, וגם מאפשרת לאפליקציה לפרסם את התוכן.
<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>
הכוונה הבאה תישלח על ידי השירות:
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 apublishContinuationCluster` call when receiving this intent.
תהליך עבודה של שילוב
מדריך מפורט לאימות השילוב אחרי שהוא מסתיים זמין במאמר תהליך העבודה של שילוב Engage למפתחים.
שאלות נפוצות
יצירת קשר
אם יש לכם שאלות במהלך תהליך השילוב, אתם יכולים לפנות אל engage-developers@google.com. הצוות שלנו יחזור אליך בהקדם האפשרי.
השלבים הבאים
אחרי שמסיימים את השילוב, השלבים הבאים הם:
- שולחים אימייל לכתובת
engage-developers@google.comומצרפים את קובץ ה-APK המשולב שמוכן לבדיקה על ידי Google. - Google תבצע אימות ובדיקה פנימיים כדי לוודא שהשילוב פועל כמו שצריך. אם יהיה צורך בשינויים, Google תיצור איתכם קשר ותספק את כל הפרטים הנדרשים.
- כשהבדיקה תושלם ולא יהיה צורך בשינויים, Google תיצור איתכם קשר כדי להודיע לכם שתוכלו להתחיל לפרסם את קובץ ה-APK המעודכן והמשולב בחנות Play.
- אחרי ש-Google תאשר שקובץ ה-APK המעודכן פורסם בחנות Play, קבוצות הפריטים המומלצים, המוצגים והמשך יפורסמו ויוצגו למשתמשים.