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

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

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

פרטי השילוב

טרמינולוגיה

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

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

    ההמלצות שלכם בנויות באופן הבא:

    • אשכול המלצות: תצוגת ממשק משתמש שמכילה קבוצה של המלצות משותף פיתוח אחד.

      איור 1. ממשק המשתמש של חבילת הבידור שבו מוצגות המלצות של שותף יחיד.
    • ישות: אובייקט שמייצג פריט יחיד באשכול. ישות יכולה להיות ספר דיגיטלי, ספר אודיו, סדרת ספרים ועוד. רשימה של סוגי ישויות נתמכים מופיעה בקטע הוספת נתוני ישויות.

      איור 2. ממשק המשתמש של חבילת הבידור שבו מוצג ישות אחת באשכול המלצות של שותף אחד.
  • אוסף ההמשכים מציג ספרים שלא סיימתם לקרוא מכמה שותפים מפתחים בקבוצה אחת בממשק המשתמש. כל שותף מפתח יוכל לשדר עד 10 ישויות באשכול ההמשך.

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

  1. EbookEntity
  2. AudiobookEntity
  3. BookSeriesEntity

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

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 הבאים זמינים בלקוח:

  • 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 משותף המפתחים יוסרו.
  • הנתונים מהבקשה מנותחים ומאוחסנים ב-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

אם מסיבה עסקית פנימית כלשהי אף אחת מהקבוצות לא פורסמה, מומלץ מאוד לעדכן את סטטוס הפרסום באמצעות 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 הזה משמש למחיקת התוכן של 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_CONTINUATIONIt is recommended to start apublishContinuationCluster` call when receiving this intent.

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

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

שאלות נפוצות

שאלות נפוצות על Engage SDK

איש/אשת הקשר

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

השלבים הבאים

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

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