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

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

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

פרטי השילוב

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

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

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

  • אשכול המלצות יכול לכלול ArticleEntity, ‏ PersonEntity או EventEntity, אבל לא שילוב של סוגי ישויות שונים.

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

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

  • ישות: אובייקט שמייצג פריט יחיד באשכול. השילוב הזה מציע כמה ישויות שיוצגו באמצעות אשכול ההמלצות:

    • ‫ArticleEntity: ArticleEntity מייצג המלצה לתוכן מבוסס-טקסט שקשור לבריאות וכושר. אפשר להשתמש בו למאמרים, לפוסטים בבלוג, לתוכן שיווקי, לקטעי חדשות וכו'.

      

    • ‫PersonEntity: PersonEntity מייצג אדם. ההמלצות יכולות להיות להדגיש מאמן או כל אדם שקשור לבריאות ולכושר, וכו'.

      

    • ‫EventEntity: EventEntity מייצג אירוע שיתרחש בעתיד. שעת ההתחלה של האירוע היא נתון חשוב שצריך להעביר למשתמשים. אפשר להשתמש בישות הזו כדי להציג אירועים כמו קמפיין לעידוד תרומת דם, סדנאות, שיעורי כושר או יוגה וכו' שקשורים לבריאות ולכושר.

      

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

  התוכן של ההמשך יכול להיות במבנה הבא:

  • ‫ArticleEntity: ArticleEntity מייצג המלצה לתוכן מבוסס-טקסט שקשור לבריאות וכושר. הישות הזו יכולה לייצג כתבות חדשותיות לא גמורות או תוכן אחר שהמשתמש רוצה להמשיך לצרוך מהמקום שבו הוא הפסיק. לדוגמה: תקציר חדשות, תקציר של פוסט בבלוג בנושאים שקשורים לבריאות או לכושר.

    

  • ‫EventReservationEntity: EventReservationEntity מייצג הזמנה לאירוע ועוזר למשתמשים לעקוב אחרי הזמנות לאירועים קרובים או מתמשכים בתחום הכושר והבריאות. דוגמה: מפגשי הדרכה

    

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

  • ‫GenericFeaturedEntity: הערך GenericFeaturedEntity שונה מהערך Recommendation item בכך שהערך Featured item צריך לשמש לתוכן מוביל יחיד ממפתחים, והוא צריך לייצג את התוכן החשוב ביותר שיהיה מעניין ורלוונטי למשתמשים.

    

עבודה מקדימה

רמת ה-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'
}

סיכום

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

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

שלב 1: הזנת נתוני הישות

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

1. GenericFeaturedEntity
2. ArticleEntity
3. PersonEntity
4. EventEntity
5. EventReservationEntity

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

GenericFeaturedEntity

ArticleEntity

PersonEntity

EventEntity

EventReservationEntity

מפרט לתמונות

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

התמונות צריכות להיות מאוחסנות ברשתות CDN ציבוריות כדי ש-Google תוכל לגשת אליהן.

פורמטים של קבצים

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

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

‎5120 KB

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

• האזור הבטוח בתמונה: צריך למקם את התוכן החשוב ב-80% המרכזיים של התמונה.
• השתמשו ברקע שקוף כדי שהתמונה תוצג בצורה תקינה בהגדרות של עיצוב כהה ובהיר.

קטגוריית תוכן

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

• TYPE_EDUCATION
• TYPE_SPORTS
• TYPE_MOVIES_AND_TV_SHOWS
• TYPE_BOOKS
• TYPE_AUDIOBOOKS
• TYPE_MUSIC
• TYPE_DIGITAL_GAMES
• TYPE_TRAVEL_AND_LOCAL
• TYPE_HOME_AND_AUTO
• TYPE_BUSINESS
• TYPE_NEWS
• TYPE_FOOD_AND_DRINK
• TYPE_SHOPPING
• TYPE_HEALTH_AND_FITENESS
• TYPE_MEDICAL
• TYPE_PARENTING
• TYPE_DATING

התמונות צריכות להיות מאוחסנות ברשתות CDN ציבוריות כדי ש-Google תוכל לגשת אליהן.

הנחיות לשימוש בקטגוריות התוכן

1. יש ישויות כמו ArticleEntity ו-GenericFeaturedEntity שעומדות בדרישות לשימוש בכל אחת מקטגוריות התוכן. לגבי ישויות אחרות כמו EventEntity,‏ EventReservationEntity ו-PersonEntity, רק קבוצת משנה של הקטגוריות האלה עומדת בדרישות. לפני שממלאים את הרשימה, כדאי לבדוק את רשימת הקטגוריות שעומדות בדרישות לסוג ישות.

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

   • ‫TYPE_MOVIES_AND_TV_SHOWS – כדאי לעיין בישויות מתוך מדריך השילוב של Watch לפני שמשתמשים בישויות כלליות.
   • ‫TYPE_BOOKS – כדאי לעיין ב-EbookEntity לפני שמשתמשים בישויות כלליות.
   • ‫TYPE_AUDIOBOOKS – כדאי לעיין ב-AudiobookEntity לפני שמשתמשים בישויות כלליות.
   • ‫TYPE_SHOPPING – מעבר לתשלום לפני השימוש בישויות כלליות, צריך לעיין ב-ShoppingEntity.
   • ‫TYPE_FOOD_AND_DRINK – כדאי לעיין בישויות מתוך מדריך השילוב של הזמנת אוכל לפני שמשתמשים בישויות כלליות.

3. השדה ContentCategory הוא אופציונלי, ואם התוכן לא שייך לאף אחת מהקטגוריות שצוינו קודם, צריך להשאיר אותו ריק.

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

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

מומלץ להריץ את משימת פרסום התוכן ברקע (לדוגמה, באמצעות WorkManager) ולתזמן אותה על בסיס קבוע או על בסיס אירוע (לדוגמה, בכל פעם שהמשתמש פותח את האפליקציה או כשהמשתמש מוסיף פריט לעגלת הקניות).

‫AppEngagePublishClient אחראי לפרסום של אוספים.

יש ממשקי API שמאפשרים לפרסם אשכולות בלקוח:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishContinuationCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteContinuationCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

ה-API הזה משמש כדי לבדוק אם השירות זמין לשילוב ואם אפשר להציג את התוכן במכשיר.

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

אתם יכולים לבדוק את זמינות השירות לכל סוג של אשכול שאתם מתכוונים לפרסם. ‫isServiceAvailable API מקבל אובייקט בקשה, ServiceAvailabilityRequest, שמכיל את סוגי האשכולות שצריך לבדוק את זמינות השירות שלהם. בטבלה הבאה מפורטים ClusterTypeערכי ה-enum הנדרשים עבור ServiceAvailabilityRequest.

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.
    }
}

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 (הוצאה משימוש)

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.
    }
}

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.

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

כשהשירות מקבל את הבקשה, הפעולות הבאות מתבצעות בעסקה אחת:

• הנתונים הקיימים של RecommendationCluster משותף המפתחים יוסרו.
• הנתונים מהבקשה מנותחים ומאוחסנים ב-RecommendationCluster המעודכן.

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

publishFeaturedCluster

ה-API הזה משמש לפרסום רשימה של אובייקטים מסוג FeaturedCluster.

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishFeaturedCluster(
            new PublishFeaturedClustersRequest.Builder()
                .addFeaturedCluster(
                    new FeaturedCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

כשהשירות מקבל את הבקשה, הפעולות הבאות מתבצעות בעסקה אחת:

• הנתונים הקיימים של FeaturedCluster משותף המפתחים יוסרו.
• הנתונים מהבקשה מנותחים ומאוחסנים באשכול המומלץ המעודכן.

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

publishContinuationCluster

משתמשים ב-API הזה כדי לפרסם אובייקט ContinuationCluster.

client.publishContinuationCluster(
    PublishContinuationClusterRequest.Builder()
      .setContinuationCluster(
        ContinuationCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

client.publishContinuationCluster(
            new PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    new ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build());

כשהשירות מקבל את הבקשה, הפעולות הבאות מתבצעות בעסקה אחת:

• הנתונים הקיימים של ContinuationCluster משותף המפתחים יוסרו.
• הנתונים מהבקשה מנותחים ומאוחסנים ב-ContinuationCluster המעודכן.

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

publishUserAccountManagementRequest

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

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

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());

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.

client.updatePublishStatus(
   PublishStatusRequest.Builder()
     .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
     .build())

client.updatePublishStatus(
    new PublishStatusRequest.Builder()
        .setStatusCode(AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN)
        .build());

deleteRecommendationClusters

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteContinuationCluster

ממשק ה-API הזה משמש למחיקת התוכן של Continuation Cluster.

client.deleteContinuationCluster()

client.deleteContinuationCluster();

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

deleteUserManagementCluster

ה-API הזה משמש למחיקת התוכן של UserAccountManagement Cluster.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .addClusterType(ClusterType.TYPE_FEATURED)
                .addClusterType(ClusterType.TYPE_RECOMMENDATION)
                .build());

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

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

מומלץ מאוד להאזין לתוצאת המשימה מממשקי ה-API של הפרסום, כדי שאפשר יהיה לבצע פעולת המשך לשחזור ולשליחה מחדש של משימה שהושלמה בהצלחה.

client.publishRecommendationClusters(
        PublishRecommendationClustersRequest.Builder()
          .addRecommendationCluster(..)
          .build())
      .addOnCompleteListener { task ->
        if (task.isSuccessful) {
          // do something
        } else {
          val exception = task.exception
          if (exception is AppEngageException) {
            @AppEngageErrorCode val errorCode = exception.errorCode
            if (errorCode == AppEngageErrorCode.SERVICE_NOT_FOUND) {
              // do something
            }
          }
        }
      }

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 עם הסיבה שכלולה כקוד שגיאה.

שלב 3: טיפול ב-Intents של שידור

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

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

הפרמטר BroadcastReceiver צריך להיות מוגדר באחת משתי הדרכים הבאות:

• רישום דינמי של מופע של המחלקה BroadcastReceiver באמצעות Context.registerReceiver(). ההרשאה הזו מאפשרת תקשורת מאפליקציות שעדיין פעילות בזיכרון.

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)
}

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 מומלץ להתחיל שיחת publishContinuationCluster כשמתקבלת הכוונה הזו.

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

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

שאלות נפוצות

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

יצירת קשר

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

השלבים הבאים

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

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