‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

מעורבות SDK – קריאה: הוראות לשילוב טכני של צד שלישי

כדי להגביר את ההתעניינות באפליקציה, כדאי להגיע למשתמשים במקומות שבהם הם נמצאים. אפשר לשלב את Engage SDK כדי להציג המלצות מותאמות אישית ותוכן להמשך ישירות למשתמשים בכמה פלטפורמות במכשיר, כמו אוספים, חבילת הבידור וחנות Play. השילוב מוסיף פחות מ-50KB (דחוסים) ל-APK הממוצע, ולוקח למפתחים בערך שבוע להטמיע אותו ברוב האפליקציות. מידע נוסף זמין באתר העסקי שלנו.

המדריך הזה מכיל הוראות לשותפי פיתוח בנושא העברת תוכן קריאה (ספרים דיגיטליים, ספרי אודיו, קומיקס/מנגה, בלוגים, חדשות וכתבי עת) לפלטפורמות תוכן של Engage.

תמיכה בקטגוריות ופלטפורמות

הזכאות לפלטפורמות של Engage SDK מבוססת על קטגוריית התוכן של האפליקציה. בטבלה הבאה מפורטות הדרישות שצריך לעמוד בהן כדי להציג מוצרים בפלטפורמות ספציפיות:

סטטוס	קטגוריית תוכן או תרחיש לדוגמה	פלטפורמות נתמכות
יש תמיכה (אפשר להציג בכל הפלטפורמות)	eBooks קומיקס ומנגה ספרי אודיו שירותי קריאה של תוכן ארוך שנוצר על ידי משתמשים בלוגים	אוספים חבילת הבידור הכרטיסייה "אפליקציות" בחנות Play הכרטיסייה "אני" בחנות Play (המלצות אישיות והמשך בלבד) דף האפליקציה בחנות Play
יש תמיכה חלקית (עומד בדרישות בחלק מהפלטפורמות)	חדשות וכתבי עת*	אוספים חבילת הבידור
לא נתמך	קורא ספרים דיגיטליים או קובצי PDF ביקורות על ספרים אנציקלופדיה / מילון מתרגם טקסטים דתיים

אפליקציות חדשות

אפליקציות חדשות מספקות תוכן מגוון, וכל אחת מהן כפופה לכללי זכאות ייחודיים. התוכן של Engage SDK בחנות Play תואם לכלי הפרימיום להגדלת ההכנסות ב-Play, ולכן כתבות וקטעי וידאו מאפליקציות חדשות לא עומדים בדרישות של חנות Play, אבל כן עומדים בדרישות של "אוספים" ו"חבילת הבידור". לעומת זאת, תוכן חדשותי לא מסורתי, כמו פודקאסטים ומתכונים, עשוי לעמוד בדרישות של חנות Play:

סוג ישות	עומד בדרישות להצגה באוספים	עומד בדרישות של חבילת הבידור	עומד בדרישות של חנות Play
כתבה	כן (הכרטיסייה "לקרוא")	כן (הכרטיסייה "לקרוא")	לא
קטע וידאו	כן (כרטיסיית הצפייה)	כן (כרטיסיית הצפייה)	לא
פודקאסט	כן (בכרטיסייה "האזנה")	כן (בכרטיסייה "האזנה")	כן
מתכון	כן (בכרטיסייה "אוכל")	לא	כן

מיומנויות ב-Android

הצגת הקוד ב-GitHub

שילוב של Engage SDK

כדי לשלב, לנפות באגים ולפתור בעיות בהטמעה, אתם יכולים להשתמש במיומנות Android של Engage SDK.

כדי להתקין את המיומנות מ-Android CLI, מריצים את הפקודה:

android skills add engage-sdk-integration

פרטי השילוב

בקטע הזה מפורטים השלבים, מודלי הנתונים והמונחים שנדרשים כדי לשלב את Engage SDK לתוכן קריאה.

הסברים על המונחים

השילוב הזה כולל את שלושת סוגי האשכולות הבאים: המלצה, המשך ונבחרים.

המלצות: אשכולות שמציגים הצעות מותאמות אישית לתוכן לקריאה ממפתח שותף ספציפי.

ההמלצות מוצגות במבנה הבא:
- אשכול המלצות: תצוגה בממשק המשתמש שמכילה קבוצת המלצות משותף פיתוח אחד.
  
  איור 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.6.0'
}

סיכום

העיצוב מבוסס על הטמעה של שרת מאגד (bound service).

הנתונים שלקוח יכול לפרסם כפופים למגבלות הבאות, בהתאם לסוגי האשכולות השונים:

סוג האשכול	מגבלות על אשכולות	מגבלות מקסימליות על ישויות באשכול
אשכולות של המלצות	עד 7	עד 50
אוסף ההמשכים	לכל היותר 1	עד 20
אשכול מומלץ	לכל היותר 1	עד 20

שלב 1: מסירת נתוני הישות

ב-SDK מוגדרות ישויות שונות שמייצגות כל סוג פריט. אנחנו תומכים בישויות הבאות בקטגוריה "קריאה":

EbookEntity
AudiobookEntity
BookSeriesEntity

בטבלאות הבאות מפורטים המאפיינים הזמינים והדרישות לכל סוג.

`EbookEntity`

האובייקט EbookEntity מייצג ספר דיגיטלי (לדוגמה, הספר הדיגיטלי Becoming של מישל אובמה).

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת. כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
מחבר	חובה	צריך לציין לפחות שם אחד של מחבר.
‫URI של קישור לפעולה	חובה	קישור העומק לאפליקציה של ספק הספר הדיגיטלי. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
תאריך פרסום	אופציונלי	באלפיות השנייה של ראשית הזמן (epoch), אם צוינו.
תיאור	אופציונלי	אם מציינים את השדה הזה, הוא צריך להכיל עד 200 תווים.
מחיר	אופציונלי	טקסט חופשי
מספר עמודים	אופציונלי	אם מציינים ערך, הוא חייב להיות מספר שלם חיובי.
ז'אנר	אופציונלי	רשימת הז'אנרים שמשויכים לספר.
שם הסדרה	אופציונלי	שם הסדרה שאליה הספר שייך (לדוגמה, הארי פוטר).
אינדקס יחידות של סדרות	אופציונלי	האינדקס של הספר הדיגיטלי בסדרה, כאשר 1 הוא הספר הדיגיטלי הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, צריך להגדיר את הערך 3.
המשך עם סוג הספר	אופציונלי	TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בסדרה חדשה. TYPE_NEW – הושק לאחרונה.
מועד ההתעניינות האחרון	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. ספרים דיגיטליים שנרכשו לאחרונה יכולים להיות חלק מאשכול "המשך קריאה". באלפיות השנייה של התקופה.
אחוז ההתקדמות שהושלם	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. הערך חייב להיות גדול מ-0 וקטן מ-100.
DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה
חותמת הזמן של ההתחלה	אופציונלי	חותמת הזמן של התקופה שאחריה התוכן אמור להופיע בפלטפורמה. אם המדיניות לא מוגדרת, אפשר להציג תוכן בפלטפורמה. באלפיות השנייה של התקופה.
חותמת זמן של סיום	אופציונלי	חותמת הזמן של התקופה שאחריה התוכן לא מוצג יותר בפלטפורמה. אם המדיניות לא מוגדרת, אפשר להציג תוכן בפלטפורמה. באלפיות השנייה של התקופה.

`AudiobookEntity`

האובייקט AudiobookEntity מייצג ספר אודיו (לדוגמה, ספר האודיו Becoming של מישל אובמה).

מאפיין	דרישה	הערות
שם	חובה
תמונות של פוסטרים	חובה	צריך להוסיף לפחות תמונה אחת. כדי לקבל הנחיות, כדאי לעיין במפרט לתמונות.
מחבר	חובה	צריך לציין לפחות שם אחד של מחבר.
‫URI של קישור לפעולה	חובה	קישור העומק לאפליקציית הספק של ספר האודיו. הערה: אפשר להשתמש בקישורי עומק לצורך שיוך (Attribution). כדאי לעיין בשאלות הנפוצות האלה
Narrator	אופציונלי	צריך לציין לפחות שם אחד של קריין.
תאריך פרסום	אופציונלי	באלפיות השנייה של ראשית הזמן (epoch), אם צוינו.
תיאור	אופציונלי	אם מציינים את השדה הזה, הוא צריך להכיל עד 200 תווים.
מחיר	אופציונלי	טקסט חופשי
משך	אופציונלי	אם מציינים ערך, הוא חייב להיות חיובי.
ז'אנר	אופציונלי	רשימת הז'אנרים שמשויכים לספר.
שם הסדרה	אופציונלי	שם הסדרה שאליה ספר האודיו שייך (לדוגמה, הארי פוטר).
אינדקס יחידות של סדרות	אופציונלי	האינדקס של ספר האודיו בסדרה, כאשר 1 הוא ספר האודיו הראשון בסדרה. לדוגמה, אם הארי פוטר והאסיר מאזקבאן הוא הספר השלישי בסדרה, צריך להגדיר את הערך 3.
המשך עם סוג הספר	אופציונלי	TYPE_CONTINUE – המשך קריאה של ספר שלא סיימתם לקרוא. TYPE_NEXT – המשך בסדרה חדשה. TYPE_NEW – הושק לאחרונה.
מועד ההתעניינות האחרון	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. באלפיות השנייה של התקופה.
אחוז ההתקדמות שהושלם	חובה בתנאים מסוימים	חובה לציין את הערך הזה כשהפריט נמצא באוסף ההמשכים. ספרי אודיו שנרכשו לאחרונה יכולים להיות חלק מאשכול "המשך קריאה". הערך חייב להיות גדול מ-0 וקטן מ-100.
DisplayTimeWindow – הגדרת חלון זמן להצגת תוכן בפלטפורמה
חותמת הזמן של ההתחלה	אופציונלי	חותמת הזמן של התקופה שאחריה התוכן אמור להופיע בפלטפורמה. אם המדיניות לא מוגדרת, אפשר להציג תוכן בפלטפורמה. באלפיות השנייה של התקופה.
חותמת זמן של סיום	אופציונלי	חותמת הזמן של התקופה שאחריה התוכן לא מוצג יותר בפלטפורמה. אם המדיניות לא מוגדרת, אפשר להציג תוכן בפלטפורמה. באלפיות השנייה של התקופה.

`BookSeriesEntity`

האובייקט BookSeriesEntity מייצג סדרת ספרים (לדוגמה, סדרת הספרים הארי פוטר, שכוללת 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	960x1,200

פורמט קובץ

‫PNG, ‏ JPG, ‏ GIF סטטי, WebP

גודל קובץ מקסימלי

5,120KB

המלצות נוספות

האזור הבטוח בתמונה: צריך למקם את התוכן החשוב במרכז התמונה, והוא צריך להשתרע על פני 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 הזה משמש כדי לבדוק אם השירות זמין לשילוב ואם אפשר להציג את התוכן במכשיר.

ל-Engage SDK מגרסה 1.6.0 ואילך (מומלץ)

מיומנויות ב-Android

הצגת הקוד ב-GitHub

שילוב של Engage SDK

כדי להתקין את המיומנות מ-Android CLI, מריצים את הפקודה:

android skills add engage-sdk-integration

אם הצוות שלכם משתמש בכלי תכנות מבוססי-AI (כמו Gemini ב-Android Studio), אתם יכולים להפוך את ההעברה הזו לאוטומטית על ידי הנחיה של העוזר האישי מבוסס-AI:

Use 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, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ערכי ה-enum של ClusterType שנדרשים ל-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 לסירוגין כדי להפחית את עלויות ההצגה. עם זאת, אסטרטגיית ניתוח התוכן לסירוגין משפיעה לרעה על חוויית המשתמש: תוכן מיושן לא יוצג, וחלק מהפלטפורמות לא יציגו תוכן.

החל מגרסה 1.6.0, Engage SDK מאפשר לבדוק את הזמינות של סוגי אשכולות ספציפיים. אם האפליקציה שלכם משתמשת בהטמעה לסירוגין:

אשכולות המשך (כמו "המשך קריאה") נשארים מופעלים כברירת מחדל בכל המכשירים הנתמכים.
סוגים אחרים של אשכולות (כמו המלצות) מופעלים ומושבתים לסירוגין.

אם הגדרת ברירת המחדל הזו לא מתאימה לצרכים שלכם, אתם יכולים לפנות לכתובת 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 קיימים של שותף הפיתוח יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול ההמלצות המעודכן.

אם יש שגיאה, כל הבקשה נדחית והמצב הקיים נשמר.

`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 קיימים של שותף הפיתוח יוסרו.
הנתונים מהבקשה מנותחים ונשמרים באשכול ההמשך המעודכן.

אם יש שגיאה, כל הבקשה נדחית והמצב הקיים נשמר.

`publishUserAccountManagementRequest`

ה-API הזה משמש לפרסום כרטיס כניסה . פעולת הכניסה מפנה את המשתמשים לדף הכניסה של האפליקציה כדי שהאפליקציה תוכל לפרסם תוכן (או לספק תוכן מותאם אישית יותר)

המטא-נתונים הבאים הם חלק מכרטיס הכניסה:

מאפיין	דרישה	תיאור
‫URI של פעולה	חובה	קישור עומק לפעולה (למשל, מעבר לדף הכניסה לאפליקציה)
תמונה	אופציונלי – אם לא מציינים את המאפיין הזה, צריך לציין את מאפיין שם הפריט	התמונה שמוצגת בכרטיס תמונות ביחס גובה-רוחב של 16:9 וברזולוציה של 1,264x712
כותרת	אופציונלי – אם לא מספקים את המאפיין הזה, צריך לספק את מאפיין התמונה	השם שמופיע בכרטיס
טקסט פעולה	אופציונלי	הטקסט שמוצג ב-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`

אם מסיבה עסקית פנימית כלשהי אף אחד מהאשכולות לא פורסם, אנחנו ממליצים מאוד לעדכן את סטטוס הפרסום באמצעות ה-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());

`deleteRecommendationsClusters`

ה-API הזה משמש למחיקת התוכן של אשכולות ההמלצות.

Kotlin

client.deleteRecommendationsClusters()

Java

client.deleteRecommendationsClusters();

כשהשירות מקבל את הבקשה, הוא מסיר את הנתונים הקיימים מאשכולות ההמלצות. אם יש שגיאה, כל הבקשה נדחית והמצב הקיים נשמר.

`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, והסיבה נכללת בתור קוד שגיאה.

קוד שגיאה	שם השגיאה	הערה
`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: טיפול בכוונות שידור

בנוסף לביצוע קריאות ל-API לפרסום תוכן באמצעות משימה, צריך גם להגדיר BroadcastReceiver כדי לקבל את הבקשה לפרסום תוכן.

המטרה של כוונות שידור היא בעיקר להפעיל מחדש את האפליקציה ולאלץ סנכרון נתונים. כוונות שידור לא נועדו להישלח בתדירות גבוהה מאוד. הוא מופעל רק כששירות 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. ההרשאה הזו מאפשרת לאפליקציה לקבל כוונות שידור כשהיא לא פועלת, וגם לפרסם את התוכן.

<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 כשמקבלים את ה-intent הזה.
com.google.android.engage.action.PUBLISH_FEATURED מומלץ להתחיל שיחת publishFeaturedCluster כשמקבלים את ה-intent הזה.
com.google.android.engage.action.PUBLISH_CONTINUATIONIt is recommended to start aקריאה ל-publishContinuationCluster` ‎ כשמתקבלת ה-Intent הזו.

תהליך עבודה של שילוב

למדריך מפורט על אימות השילוב אחרי שהוא הושלם, ראו תהליך העבודה של מפתחים לשילוב עם Engage.

שאלות נפוצות

שאלות נפוצות לגבי Engage SDK

יצירת קשר

אם יש לכם שאלות במהלך תהליך השילוב, אתם יכולים לפנות אל engage-developers@google.com. הצוות שלנו ישיב בהקדם האפשרי.

השלבים הבאים

אחרי שתשלימו את השילוב, אלה השלבים הבאים:

שולחים אימייל לכתובת engage-developers@google.com ומצרפים את קובץ ה-APK המשולב שמוכן לבדיקה על ידי Google.
‫Google תבצע אימות ובדיקה פנימית כדי לוודא שהשילוב פועל כצפוי. אם יהיה צורך בשינויים, Google תפנה אליכם ותספק את כל הפרטים הנדרשים.
כשהבדיקה תסתיים ולא יהיה צורך בשינויים, Google תודיע לכם שאתם יכולים להתחיל לפרסם את ה-APK המעודכן והמשולב בחנות Play.
אחרי ש-Google תאשר שקובץ ה-APK המעודכן פורסם בחנות Play, אשכולות ההמלצות, התוכן המוצג והמשך הצפייה יפורסמו ויהיו גלויים למשתמשים.

מעורבות SDK – קריאה: הוראות לשילוב טכני של צד שלישי קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

תמיכה בקטגוריות ופלטפורמות

אפליקציות חדשות

פרטי השילוב

הסברים על המונחים

הכנה

סיכום

שלב 1: מסירת נתוני הישות

EbookEntity

AudiobookEntity

BookSeriesEntity

מפרט לתמונות

דוגמה

שלב 2: ציון נתונים של אוסף ההמשכים

isServiceAvailable

ל-Engage SDK מגרסה 1.6.0 ואילך (מומלץ)

Kotlin

Java

תכונה: זמינות מותנית של שירותים

לגרסאות SDK שקדמו לגרסה 1.6.0 (הוצאה משימוש)

Kotlin

Java

publishRecommendationClusters

Kotlin

Java

publishFeaturedCluster

Kotlin

Java

publishContinuationCluster

Kotlin

Java

publishUserAccountManagementRequest

Kotlin

Java

updatePublishStatus

Kotlin

Java

deleteRecommendationsClusters

Kotlin

Java

deleteFeaturedCluster

Kotlin

Java

deleteContinuationCluster

Kotlin

Java

deleteUserManagementCluster

Kotlin

Java

deleteClusters

Kotlin

Java

טיפול בשגיאות

שלב 3: טיפול בכוונות שידור

Kotlin

Java

תהליך עבודה של שילוב

שאלות נפוצות

יצירת קשר

השלבים הבאים

מעורבות SDK – קריאה: הוראות לשילוב טכני של צד שלישי

`EbookEntity`

`AudiobookEntity`

`BookSeriesEntity`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishContinuationCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationsClusters`

`deleteFeaturedCluster`

`deleteContinuationCluster`

`deleteUserManagementCluster`

`deleteClusters`