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

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

במדריך הזה מוסבר לשותפי מפתחים איך לשלב את תוכן הקניות שלהם באמצעות Engage SDK כדי לאכלס את הממשק החדש הזה, וגם מישקים קיימים של Google כמו Entertainment Space.

פרטי השילוב

טרמינולוגיה

השילוב הזה כולל את חמשת הסוגים הבאים של אשכולות: Recommendation, Featured, Shopping Cart, Shopping List, סידור מחדש ומעקב אחרי הזמנות שופינג.

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

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

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

  • ShoppingEntity: אובייקט שמייצג פריט יחיד באשכול.

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

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

  עגלת הקניות בנויה במבנה הבא:

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

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

• באשכול רשימת קניות אפשר לראות הצצה לרשימות הקניות מכמה מפתחים שעובדים איתנו בקיבוץ אחד של ממשק המשתמש, כדי לעודד את המשתמשים לחזור לאפליקציה המתאימה כדי לעדכן ולהשלים את הרשימות שלהם. יש רק אשכול אחד של רשימת קניות.

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

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

    • תמונות של X פריטים בהזמנה הקודמת של המשתמש.
    • תוויות ל-X פריטים בהזמנה הקודמת של המשתמש.

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

  יש אשכול יחיד של מעקב אחר הזמנות ב-Shopping שמופיע בחלק העליון של ממשק המשתמש, במיקום בעל עדיפות גבוהה מעל כל אשכולות ההמלצות. כל שותף מפתחים מורשה לשדר מספר פריטים של ShoppingOrderTrackingEntity באשכול 'מעקב אחר הזמנות בשופינג'.

  • המבנה של ShoppingOrderTrackingCluster הוא:

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

עבודה מוקדמת

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

מידע נוסף זמין במאמר חשיפה של חבילות ב-Android 11.

סיכום

התכנון מבוסס על הטמעה של שירות מוגדר.

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

שלב 1: מספקים נתוני ישות

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

1. ShoppingEntity
2. ShoppingCart
3. ShoppingList
4. Reorder
5. ShoppingOrderTracking

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

ShoppingEntity

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

ShoppingEntity

ShoppingCart

ShoppingList

ShoppingReorderCluster

ShoppingOrderTrackingCluster

מפרט לתמונות

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

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

PNG, JPG, GIF סטטי, WebP

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

‎5,120 KB

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

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

שלב 2: מסירת נתוני האשכולות

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

AppEngageShoppingClient אחראי לפרסום אשכולות של קניות.

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

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishShoppingCart
• publishShoppingCarts
• publishShoppingList
• publishShoppingReorderCluster
• publishShoppingOrderTrackingCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteShoppingCartCluster
• deleteShoppingListCluster
• deleteShoppingReorderCluster
• deleteShoppingOrderTrackingCluster
• deleteUserManagementCluster
• deleteClusters

isServiceAvailable

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

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.

לאובייקט RecommendationCluster יכולים להיות המאפיינים הבאים:

client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Black Friday Deals")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

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

client.publishFeaturedCluster(
            PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    FeaturedCluster.Builder()
                        ...
                        .build())
                .build())

client.publishFeaturedCluster(
            new PublishFeaturedClusterRequest.Builder()
                .setFeaturedCluster(
                    new FeaturedCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishShoppingCart

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

client.publishShoppingCart(
            PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingCart(
            new PublishShoppingCartRequest.Builder()
                .setShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

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

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

publishShoppingCarts

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

client.publishShoppingCarts(
            PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    ShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingCarts(
            new PublishShoppingCartClustersRequest.Builder()
                .addShoppingCart(
                    new ShoppingCart.Builder()
                        ...
                        .build())
                .build())

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

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

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

publishShoppingList

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

client.publishFoodShoppingList(
            PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingList(
            new PublishFoodShoppingListRequest.Builder()
                .setFoodShoppingList(
                    new FoodShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishShoppingReorderCluster

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

client.publishShoppingReorderCluster(
            PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingReorderCluster(
            new PublishShoppingReorderClusterRequest.Builder()
                .setReorderCluster(
                    new ShoppingReorderCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishShoppingOrderTrackingCluster

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

client.publishShoppingOrderTrackingCluster(
            PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingOrderTrackingCluster(
            new PublishShoppingOrderTrackingClusterRequest.Builder()
                .setShoppingOrderTrackingCluster(
                    new ShoppingOrderTrackingCluster.Builder()
                        ...
                        .build())
                .build());

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

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

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

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

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

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

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

deleteShoppingCartCluster

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

client.deleteShoppingCartCluster()

client.deleteShoppingCartCluster();

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

deleteShoppingListCluster

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

client.deleteShoppingListCluster()

client.deleteShoppingListCluster();

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

deleteShoppingReorderCluster

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

client.deleteShoppingReorderCluster()

client.deleteShoppingReorderCluster();

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

deleteShoppingOrderTrackingCluster

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

client.deleteShoppingOrderTrackingCluster()

client.deleteShoppingOrderTrackingCluster();

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

deleteUserManagementCluster

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

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

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

deleteClusters

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

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

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .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: טיפול בכוונות שידור

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

המטרה של כוונות השידור היא בעיקר להפעיל מחדש את האפליקציה ולאלץ סנכרון נתונים. כווננו של מודעות ה-Broadcast לא נשלחות בתדירות גבוהה. הוא מופעל רק כשמערכת 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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
  // Trigger shopping order tracking cluster publish when
  // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER 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))

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED))

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART))

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST))

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER))

// Register Shopping Order Tracking Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER))
}

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 shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast is
// received

// Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
// received

// Trigger reorder cluster publish when PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER
// 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));

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED));

// Register Shopping Cart Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_CART));

// Register Shopping List Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_LIST));

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_REORDER_CLUSTER));

// Register Shopping Order Tracking Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.shopping.service.Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER));

}

• מגדירים באופן סטטי הטמעה באמצעות התג <receiver> בקובץ AndroidManifest.xml. כך האפליקציה יכולה לקבל כוונות שידור כשהיא לא פועלת, וגם לפרסם את התוכן.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      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.shopping.PUBLISH_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER" />
      </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.shopping.PUBLISH_SHOPPING_CART מומלץ להתחיל שיחת publishShoppingCart כשמקבלים את הכוונה הזו.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST מומלץ להתחיל קריאת publishShoppingList כשה-Intent הזה מתקבל.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER מומלץ להתחיל שיחת publishReorderCluster כשמקבלים את הכוונה הזו.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER מומלץ להתחיל שיחת publishShoppingOrderTrackingCluster כשמתקבלת הכוונה הזו.

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

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

שאלות נפוצות

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

יצירת קשר

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

השלבים הבאים

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

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