כדי להגביר את רמת העניין באפליקציה, כדאי להגיע למשתמשים במקומות שבהם הם נמצאים. אפשר לשלב את 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). אפשר לעיין בשאלות הנפוצות |
| תאריך פרסום | אופציונלי | באופן אופציונלי, אפשר לציין את הערך באלפיות השנייה לפי תקופה של זמן מערכת. |
| תיאור | אופציונלי | אם מציינים את התיאור, הוא צריך לכלול עד 200 תווים. |
| מחיר | אופציונלי | טקסט חופשי |
| מספר עמודים | אופציונלי | אם מציינים ערך, הוא חייב להיות מספר שלם חיובי. |
| ז'אנר | אופציונלי | רשימת הז'אנרים שמשויכים לספר. |
| שם הסדרה | אופציונלי | שם הסדרה שאליה הספר הדיגיטלי שייך (לדוגמה, Harry Potter). |
| אינדקס יחידות של סדרות | אופציונלי | האינדקס של הספר הדיגיטלי בסדרה, כאשר 1 הוא הספר הדיגיטלי הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, הערך צריך להיות 3. |
| המשך סוג הספר | אופציונלי |
TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בספר חדש בסדרה. TYPE_NEW – גרסה חדשה. |
| מועד האינטראקציה האחרונה | חובה באופן מותנה |
חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. ספרים דיגיטליים שנרכשו *לאחרונה* יכולים להיכלל בקבוצת הספרים 'המשך קריאה'. באפוקה באלפיות השנייה. |
| אחוז ההתקדמות שהושלם | חובה באופן מותנה |
חובה לציין את הערך הזה אם הפריט נמצא באוסף ההמשכים. הערך חייב להיות גדול מ-0 וקטן מ-100. |
| DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה | ||
| חותמת זמן של התחלה | אופציונלי |
חותמת הזמן של התקופה שאחריה התוכן צריך להיות מוצג במשטח. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
| חותמת זמן של סיום | אופציונלי |
חותמת הזמן של העידן שאחריה התוכן לא מוצג יותר בפלטפורמה. אם לא מוגדרת מדיניות, התוכן עומד בדרישות להצגה בפלטפורמה. באפוקה באלפיות השנייה. |
AudiobookEntity
אובייקט AudiobookEntity מייצג ספר אודיו (לדוגמה, ספר האודיו של Becoming מאת מישל אובמה).
| מאפיין | דרישה | הערות |
|---|---|---|
| שם | חובה | |
| תמונות פוסטר | חובה | צריך לספק לפחות תמונה אחת. הנחיות זמינות במאמר בנושא מפרטים של תמונות. |
| מחבר | חובה | צריך לציין לפחות שם מחבר אחד. |
| URI של קישור לפעולה | חובה |
קישור העומק לאפליקציה לבעלי מקצוע של ספר האודיו. הערה: אפשר להשתמש בקישורי עומק לשיוך (Attribution). אפשר לעיין בשאלות הנפוצות |
| Narrator | אופציונלי | צריך לציין לפחות שם אחד של קריין. |
| תאריך פרסום | אופציונלי | באופן אופציונלי, אפשר לציין את הערך באלפיות השנייה לפי תקופה של זמן מערכת. |
| תיאור | אופציונלי | אם מציינים את התיאור, הוא צריך לכלול עד 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 ואילך (מומלץ)
כישורים ב-Android
הצגה ב-GitHubשילוב של Engage SDK
android skills add --skill engage-sdk-integrationUse the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.אתם יכולים לבדוק את זמינות השירות לכל סוג אשכול שאתם מתכוונים לפרסם. isServiceAvailable API מקבל אובייקט בקשה, ServiceAvailabilityRequest, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ClusterTypeערכי ה-enum
הנדרשים עבור ServiceAvailabilityRequest.
| סוג האשכול | קבוע של סוג האשכול | ערך של מספר שלם |
|---|---|---|
| לא ידוע | TYPE_UNKNOWN |
0 |
| אשכול המלצות | TYPE_RECOMMENDATION |
1 |
| אשכול מוצג | TYPE_FEATURED |
2 |
| אשכול המשכיות | TYPE_CONTINUATION |
3 |
| אשכול לניהול משתמשים | TYPE_ENGAGEMENT |
8 |
| Subscription Cluster | 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 שקודמות לגרסה v1.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 |
התמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16x9 וברזולוציה של 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, קבוצות האפליקציות מומלצות, מוצגות והמשך יפורסמו ויוצגו למשתמשים.