Engage SDK Shopping: دستورالعمل‌های یکپارچه‌سازی فنی شخص ثالث

با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

Google در حال ساخت یک سطح روی دستگاه است که برنامه های کاربران را بر اساس عمودی سازماندهی می کند و یک تجربه همهجانبه جدید را برای مصرف شخصی و کشف محتوای برنامه امکان پذیر می کند. این تجربه تمام صفحه به شرکای توسعه‌دهنده فرصتی می‌دهد تا بهترین محتوای غنی خود را در یک کانال اختصاصی خارج از برنامه خود به نمایش بگذارند.

این راهنما حاوی دستورالعمل‌هایی برای شرکای توسعه‌دهنده است تا محتوای خرید خود را با استفاده از Engage SDK برای پر کردن این سطح جدید و سطوح موجود Google مانند Entertainment Space، یکپارچه کنند.

جزئیات یکپارچه سازی

اصطلاحات

این ادغام شامل پنج نوع خوشه زیر است: توصیه ، ویژه ، سبد خرید ، فهرست خرید ، سفارش مجدد و پیگیری سفارش خرید .

• خوشه‌های توصیه پیشنهادات خرید شخصی‌شده از یک شریک توسعه‌دهنده را نشان می‌دهند. این توصیه‌ها را می‌توان برای کاربر شخصی‌سازی کرد یا تعمیم داد (به عنوان مثال، موارد پرطرفدار). از این ها برای نمایش محصولات، رویدادها، فروش ها، تبلیغات، اشتراک ها به دلخواه خود استفاده کنید.

  توصیه های شما ساختار زیر را دارد:

  • Recommendation Cluster: نمای رابط کاربری که شامل گروهی از توصیه‌های یک شریک توسعه‌دهنده است.

  • ShoppingEntity: یک شی که یک مورد را در یک خوشه نشان می دهد.

• خوشه ویژه مجموعه‌ای از موجودیت‌ها را از چندین شریک توسعه‌دهنده در یک گروه‌بندی UI به نمایش می‌گذارد. یک خوشه ویژه وجود خواهد داشت که در نزدیکی بالای رابط کاربری با اولویت بالاتر از همه خوشه‌های توصیه ظاهر می‌شود. هر شریک توسعه دهنده مجاز به پخش حداکثر 10 موجودیت در خوشه ویژه خواهد بود.

• خوشه سبد خرید نگاهی اجمالی به سبد خرید از بسیاری از شرکای توسعه‌دهنده در یک گروه رابط کاربری نشان می‌دهد و کاربران را وادار می‌کند تا سبدهای خرید برجسته خود را تکمیل کنند. یک خوشه سبد خرید وجود دارد که در نزدیکی بالای رابط کاربری ظاهر می‌شود، با اولویت بالاتر از همه خوشه‌های توصیه. هر شریک توسعه دهنده مجاز به پخش حداکثر 3 نمونه ShoppingCart در خوشه سبد خرید است.

  سبد خرید شما ساختار زیر را دارد:

  • خوشه سبد خرید: نمای رابط کاربری که شامل گروهی از پیش نمایش های سبد خرید از بسیاری از شرکای توسعه دهنده است.

  • سبد خرید: شیئی که نمایانگر پیش‌نمایش سبد خرید برای یک شریک توسعه‌دهنده است که در خوشه سبد خرید نمایش داده می‌شود. ShoppingCart باید تعداد کل اقلام موجود در سبد را نشان دهد و همچنین ممکن است شامل تصاویر برخی از اقلام در سبد خرید کاربر باشد.

• خوشه فهرست خرید نگاهی اجمالی به لیست های خرید از چندین شریک توسعه دهنده در یک گروه UI را نشان می دهد که از کاربران می خواهد برای به روز رسانی و تکمیل لیست های خود به برنامه مربوطه بازگردند. یک خوشه لیست خرید وجود دارد.

• خوشه Reorder نگاهی اجمالی از سفارشات قبلی از چندین شریک توسعه دهنده در یک گروه UI را نشان می دهد که کاربران را وادار به سفارش مجدد می کند. یک خوشه Reorder واحد وجود دارد.

  • خوشه سفارش مجدد باید تعداد کل موارد در سفارش قبلی کاربر را نشان دهد و همچنین باید یکی از موارد زیر را شامل شود:

    • تصاویر برای X مورد در سفارش قبلی کاربر.
    • برچسب‌هایی برای X مورد در سفارش قبلی کاربر.

• خوشه ردیابی سفارش خرید نگاهی گذرا از سفارشات خرید در انتظار یا اخیراً تکمیل شده از بسیاری از شرکای توسعه‌دهنده در یک گروه UI نشان می‌دهد که به کاربران امکان می‌دهد سفارش‌های خود را پیگیری کنند.

  یک خوشه ShoppingOrderTracking وجود دارد که در نزدیکی بالای UI ظاهر می‌شود، با اولویت بالاتر از همه خوشه‌های Recommendation. هر شریک توسعه دهنده مجاز است چندین مورد ShoppingOrderTrackingEntity را در خوشه ردیابی سفارش خرید پخش کند.

  • ShoppingOrderTrackingCluster شما ساختار زیر را دارد:

    • ShoppingOrderTracking Cluster : نمای رابط کاربری که شامل گروهی از پیش نمایش های ردیابی سفارش از بسیاری از شرکای توسعه دهنده است.
    • 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

حداکثر اندازه فایل

5120 کیلوبایت

توصیه های اضافی

• ناحیه امن تصویر: محتوای مهم خود را 80 درصد در مرکز تصویر قرار دهید.
• از پس زمینه شفاف استفاده کنید تا تصویر به درستی در تنظیمات تم تیره و روشن نمایش داده شود.

مرحله 2: داده های Cluster را ارائه دهید

توصیه می‌شود کار انتشار محتوا در پس‌زمینه اجرا شود (مثلاً با استفاده از 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 از شریک توسعه دهنده حذف شده است.
• داده‌های درخواست در خوشه پیگیری سفارش خرید به‌روز شده تجزیه و ذخیره می‌شوند.

در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

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 == 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 انتشار کارت ورود به سیستم را توصیه می کند. اگر به هر دلیلی ارائه دهندگان قادر به انتشار کارت ورود به سیستم نیستند، توصیه می کنیم با کد وضعیت NOT_PUBLISHED_REQUIRES_SIGN_IN با updatePublishStatus API تماس بگیرید.

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 برای حذف محتوای Featured Cluster استفاده می شود.

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از خوشه ویژه حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteShoppingCartCluster

این API برای حذف محتوای خوشه سبد خرید استفاده می شود.

client.deleteShoppingCartCluster()

client.deleteShoppingCartCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از خوشه سبد خرید حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteShoppingListCluster

این API برای حذف محتوای خوشه لیست خرید استفاده می شود.

client.deleteShoppingListCluster()

client.deleteShoppingListCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از خوشه لیست خرید حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteShoppingReorderCluster

این API برای حذف محتوای Shopping Reorder Cluster استفاده می شود.

client.deleteShoppingReorderCluster()

client.deleteShoppingReorderCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از خوشه سفارش مجدد خرید حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteShoppingOrderTrackingCluster

این API برای حذف محتوای خوشه ردیابی سفارش خرید استفاده می شود.

client.deleteShoppingOrderTrackingCluster()

client.deleteShoppingOrderTrackingCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از خوشه پیگیری سفارش خرید حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteUserManagementCluster

این API برای حذف محتوای UserAccountManagement Cluster استفاده می شود.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از UserAccountManagement Cluster حذف می کند. در صورت بروز خطا، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

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: اهداف پخش را مدیریت کنید

علاوه بر برقراری تماس‌های API محتوای انتشار از طریق یک کار، برای دریافت درخواست انتشار محتوا نیز باید یک BroadcastReceiver راه‌اندازی کرد.

هدف از اهداف پخش عمدتاً فعال سازی مجدد برنامه و همگام سازی اجباری داده ها است. اهداف پخش برای ارسال خیلی مکرر طراحی نشده اند. تنها زمانی فعال می‌شود که سرویس 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 شروع کنید.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER توصیه می شود هنگامی که این هدف دریافت شد، یک تماس publishReorderCluster شروع شود.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER توصیه می شود هنگامی که این هدف دریافت شد، یک تماس publishShoppingOrderTrackingCluster شروع کنید.

گردش کار یکپارچه سازی

برای راهنمایی گام به گام در مورد تأیید ادغام خود پس از تکمیل، به گردش کار ادغام برنامه‌نویس Engage مراجعه کنید.

سوالات متداول

برای پرسش‌های متداول به پرسش‌های متداول SDK مراجعه کنید.

تماس بگیرید

در صورت وجود هرگونه سوال در طول فرآیند ادغام، با engage-developers@google.com تماس بگیرید. تیم ما در اسرع وقت پاسخ می دهد.

مراحل بعدی

پس از تکمیل این ادغام، مراحل بعدی شما به شرح زیر است:

• یک ایمیل به engage-developers@google.com ارسال کنید و APK یکپارچه خود را که برای آزمایش توسط Google آماده است، پیوست کنید.
• Google یک راستی‌آزمایی را انجام می‌دهد و به صورت داخلی بررسی می‌کند تا مطمئن شود ادغام مطابق انتظار عمل می‌کند. در صورت نیاز به تغییرات، Google با هر گونه جزئیات لازم با شما تماس می گیرد.
• وقتی آزمایش کامل شد و نیازی به تغییر نیست، Google با شما تماس می گیرد تا به شما اطلاع دهد که می توانید شروع به انتشار APK به روز شده و یکپارچه در فروشگاه Play کنید.
• پس از اینکه Google تأیید کرد که APK به‌روزرسانی‌شده شما در فروشگاه Play منتشر شده است، توصیه‌ها ، ویژگی‌ها ، سبد خرید ، فهرست خرید ، خوشه‌های سفارش مجدد و خوشه‌های پیگیری سفارش خرید ممکن است منتشر شده و برای کاربران قابل مشاهده باشند.

Google در حال ساخت یک سطح روی دستگاه است که برنامه های کاربران را بر اساس عمودی سازماندهی می کند و یک تجربه همهجانبه جدید را برای مصرف شخصی و کشف محتوای برنامه امکان پذیر می کند. این تجربه تمام صفحه به شرکای توسعه‌دهنده فرصتی می‌دهد تا بهترین محتوای غنی خود را در یک کانال اختصاصی خارج از برنامه خود به نمایش بگذارند.

این راهنما شامل دستورالعمل هایی برای شرکای توسعه دهنده برای ادغام محتوای خرید خود ، با استفاده از SDK Engage برای جمع آوری هم در سطح جدید و هم سطوح گوگل موجود مانند فضای سرگرمی است.

جزئیات ادغام

اصطلاحات

این ادغام شامل پنج نوع خوشه زیر است: توصیه ، برجسته ، سبد خرید ، لیست خرید ، ردیابی سفارش و سفارش خرید .

• خوشه های توصیه پیشنهادات خرید شخصی را از یک شریک توسعه دهنده خاص نشان می دهند. این توصیه ها را می توان برای کاربر شخصی سازی کرد یا تعمیم داد (به عنوان مثال موارد روند). از این موارد برای محصولات سطحی ، رویدادها ، فروش ، تبلیغات ، اشتراک ها به عنوان مناسب استفاده کنید.

  توصیه های شما ساختار زیر را می گیرد:

  • خوشه توصیه: نمای UI که شامل گروهی از توصیه ها از همان شریک توسعه دهنده است.

  • خرید: یک شیء که یک مورد واحد را در یک خوشه نشان می دهد.

• این خوشه های برجسته مجموعه ای از اشخاص را از چندین شرکای توسعه دهنده در یک گروه بندی UI نشان می دهد. یک خوشه برجسته وجود خواهد داشت که در نزدیکی بالای UI با قرار دادن اولویت بالاتر از همه خوشه های توصیه قرار می گیرد. به هر شریک توسعه دهنده اجازه پخش تا 10 نهاد در خوشه برجسته داده می شود.

• خوشه سبد خرید ، نگاهی دزدکی از سبد خرید از بسیاری از شرکای توسعه دهنده در یک گروه بندی UI نشان می دهد و کاربران را برای تکمیل چرخ دستی های برجسته خود فریب می دهد. یک خوشه سبد خرید واحد وجود دارد که در نزدیکی بالای UI قرار دارد و دارای اولویت بالاتر از همه خوشه های توصیه است. هر شریک توسعه دهنده مجاز به پخش 3 نمونه ShoppingCart در خوشه سبد خرید است.

  سبد خرید شما ساختار زیر را می گیرد:

  • خوشه سبد خرید: نمای UI که شامل گروهی از پیش نمایش های سبد خرید از بسیاری از شرکای توسعه دهنده است.

  • ShoppingCart: یک شیء به نمایندگی از پیش نمایش سبد خرید برای یک شریک توسعه دهنده واحد ، در خوشه سبد خرید نمایش داده می شود. جعبه ShoppingCart باید تعداد کل موارد موجود در سبد خرید را نشان دهد و همچنین ممکن است شامل برخی از موارد موجود در سبد کاربر باشد.

• خوشه لیست خرید ، نگاهی جالب از لیست های خرید از چندین شرکای توسعه دهنده در یک گروه UI نشان می دهد و باعث می شود کاربران برای به روزرسانی و تکمیل لیست های خود به برنامه مربوطه برگردند. یک خوشه لیست خرید واحد وجود دارد.

• خوشه نوری نگاهی دزدکی از سفارشات قبلی از چندین شرکای توسعه دهنده در یک گروه بندی UI نشان می دهد و باعث می شود کاربران دوباره مرتب شوند. یک خوشه تنظیم مجدد وجود دارد.

  • خوشه مجدد باید تعداد کل موارد را در سفارش قبلی کاربر نشان دهد و همچنین باید یکی از موارد زیر را شامل شود:

    • تصاویر برای موارد X در سفارش قبلی کاربر.
    • برچسب های مربوط به موارد X در سفارش قبلی کاربر.

• خوشه ردیابی سفارش خرید ، نگاهی دزدکی از سفارشات خرید در انتظار یا اخیراً تکمیل شده از بسیاری از شرکای توسعه دهنده در یک گروه UI نشان می دهد و به کاربران امکان می دهد سفارشات خود را ردیابی کنند.

  یک خوشه منفرد خرید وجود دارد که در نزدیکی بالای UI قرار دارد و دارای اولویت بالاتر از همه خوشه های توصیه است. به هر شریک توسعه دهنده اجازه داده می شود چندین مورد خرید و فروش را در خوشه ردیابی سفارش خرید پخش کند.

  • شما ساختار زیر را می گیرد:

    • خوشه خرید و فروش : نمای UI که شامل گروهی از پیش نمایش های ردیابی سفارش از بسیاری از شرکای توسعه دهنده است
    • ShoppordorDortrackingEntity : یک شیء که نمایانگر پیش نمایش سفارش خرید برای یک شریک توسعه دهنده واحد است ، در خوشه ردیابی سفارش خرید نمایش داده می شود. خرید و فروش باید وضعیت سفارش و زمان سفارش را نشان دهد. ما اکیداً توصیه می کنیم زمان تحویل مورد انتظار را برای خرید و فروشر برای خرید ، همانطور که در صورت ارائه به کاربران نمایش داده می شود ، جمع کنید.

پیش کار

حداقل سطح 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 استاتیک ، وب

حداکثر اندازه فایل

5120 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 از شریک توسعه دهنده حذف می شود.
• داده های این درخواست در خوشه ردیابی سفارش خرید به روز شده تجزیه و ذخیره می شوند.

در صورت بروز خطا ، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

publishUserAccountManagementRequest

این API برای انتشار یک علامت در کارت استفاده می شود. اقدام Signin کاربران را به صفحه ورود به سیستم هدایت می کند تا برنامه بتواند محتوا را منتشر کند (یا محتوای شخصی تر ارائه می دهد)

ابرداده زیر بخشی از علامت در کارت است -

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 به روز کنید. این مهم است زیرا:

• ارائه وضعیت در تمام سناریوها ، حتی در صورت انتشار محتوا (وضعیت == منتشر شده) ، برای جمع آوری داشبورد که از این وضعیت صریح برای انتقال سلامت و سایر معیارهای ادغام شما استفاده می کنند ، بسیار مهم است.
• اگر هیچ محتوا منتشر نشده باشد اما وضعیت ادغام شکسته نشده است (وضعیت == 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 توصیه می کند که علامت کارت را منتشر کند. اگر به هر دلیلی ارائه دهندگان قادر به انتشار علامت در کارت نیستند ، توصیه می کنیم با کد وضعیت به روزرسانی 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 برای حذف محتوای خوشه سفارش خرید استفاده می شود.

client.deleteShoppingReorderCluster()

client.deleteShoppingReorderCluster();

هنگامی که سرویس درخواست را دریافت می کند ، داده های موجود را از خوشه تغییرگر خرید حذف می کند. در صورت بروز خطا ، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

deleteShoppingOrderTrackingCluster

این API برای حذف محتوای خوشه ردیابی سفارش خرید استفاده می شود.

client.deleteShoppingOrderTrackingCluster()

client.deleteShoppingOrderTrackingCluster();

هنگامی که سرویس درخواست را دریافت می کند ، داده های موجود را از خوشه ردیابی سفارش خرید حذف می کند. در صورت بروز خطا ، کل درخواست رد می شود و وضعیت موجود حفظ می شود.

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: اهداف پخش را کنترل کنید

علاوه بر ایجاد تماس های API Publish Content از طریق یک کار ، همچنین لازم است که برای دریافت درخواست انتشار محتوا ، یک BroadcastReceiver تنظیم کنید.

هدف از اهداف پخش عمدتاً برای فعال سازی مجدد برنامه و مجبور کردن همگام سازی داده ها است. اهداف پخش به گونه ای طراحی نشده است که به طور مکرر ارسال می شود. این تنها هنگامی ایجاد می شود که سرویس 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 شروع کنید.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER توصیه می شود هنگام دریافت این هدف ، یک تماس publishReorderCluster شروع کنید.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER توصیه می شود هنگام دریافت این هدف ، یک تماس publishShoppingOrderTrackingCluster را شروع کنید.

گردش کار ادغام

برای یک راهنمای گام به گام در مورد تأیید ادغام خود پس از اتمام ، به گردش کار ادغام Engage Developer مراجعه کنید.

سوالات متداول

به Engage SDK که اغلب برای سؤالات متداول پرسیده می شود ، مراجعه کنید.

تماس بگیرید

در صورت وجود هرگونه سؤال در طی فرآیند ادغام ، با ingage-developers@google.com تماس بگیرید. تیم ما در اسرع وقت پاسخ می دهد.

مراحل بعدی

پس از تکمیل این ادغام ، مراحل بعدی شما به شرح زیر است:

• یک ایمیل برای Engage-develors@google.com ارسال کرده و APK یکپارچه خود را که آماده آزمایش توسط Google است ، ضمیمه کنید.
• Google یک تأیید را انجام می دهد و در داخل کشور بررسی می کند تا اطمینان حاصل شود که ادغام همانطور که انتظار می رود کار می کند. در صورت نیاز به تغییرات ، Google با هرگونه جزئیات لازم با شما تماس می گیرد.
• هنگامی که آزمایش کامل است و هیچ تغییری لازم نیست ، Google با شما تماس می گیرد تا به شما اطلاع دهد که می توانید APK به روز شده و یکپارچه را در فروشگاه Play شروع کنید.
• بعد از اینکه گوگل تأیید کرد که APK به روز شده شما در فروشگاه Play منتشر شده است ، توصیه شما ، برجسته ، سبد خرید ، لیست خرید ، خوشه ترتیب و سفارش خرید ممکن است خوشه های خوشه ای منتشر و برای کاربران قابل مشاهده باشد.

Google در حال ساخت یک سطح دستگاه است که برنامه های کاربران را توسط عمودی سازماندهی می کند و یک تجربه همهجانبه جدید را برای مصرف و کشف محتوای برنامه شخصی امکان پذیر می کند. این تجربه تمام صفحه ، فرصتی را برای شرکای توسعه دهنده فراهم می کند تا بهترین محتوای غنی خود را در یک کانال اختصاصی در خارج از برنامه خود به نمایش بگذارند.

این راهنما شامل دستورالعمل هایی برای شرکای توسعه دهنده برای ادغام محتوای خرید خود ، با استفاده از SDK Engage برای جمع آوری هم در سطح جدید و هم سطوح گوگل موجود مانند فضای سرگرمی است.

جزئیات ادغام

اصطلاحات

این ادغام شامل پنج نوع خوشه زیر است: توصیه ، برجسته ، سبد خرید ، لیست خرید ، ردیابی سفارش و سفارش خرید .

• خوشه های توصیه پیشنهادات خرید شخصی را از یک شریک توسعه دهنده خاص نشان می دهند. These recommendations can be personalized to the user or generalized (for example, trending items). Use these to surface products, events, sales, promos, subscriptions as you see fit.

  Your recommendations take the following structure:

  • Recommendation Cluster: A UI view that contains a group of recommendations from the same developer partner.

  • ShoppingEntity: An object representing a single item in a cluster.

• The Featured cluster showcases a selection of entities from multiple developer partners in one UI grouping. There will be a single Featured cluster, which is surfaced near the top of the UI with a priority placement above all Recommendation clusters. Each developer partner will be allowed to broadcast up to 10 entities in the Featured cluster.

• The Shopping Cart cluster shows a sneak peek of shopping carts from many developer partners in one UI grouping, nudging users to complete their outstanding carts. There is a single Shopping Cart cluster, which is surfaced near the top of the UI, with a priority placement above all Recommendation clusters. Each developer partner is allowed to broadcast up to 3 ShoppingCart instances in the Shopping Cart cluster.

  Your Shopping Cart takes the following structure:

  • Shopping Cart Cluster: A UI view that contains a group of shopping cart previews from many developer partners.

  • ShoppingCart: An object representing the shopping cart preview for a single developer partner, to be displayed in the Shopping Cart cluster. The ShoppingCart must show the total count of items in the cart and may also include images for some items in the user's cart.

• The Shopping List cluster shows a sneak peek of the shopping lists from multiple developer partners in one UI grouping, prompting users to return to the corresponding app to update and complete their lists. There is a single Shopping List cluster.

• The Reorder cluster shows a sneak peek of the previous orders from multiple developer partners in one UI grouping, prompting users to reorder. There is a single Reorder cluster.

  • Reorder cluster must show the total count of items in the user's previous order and must also include one of the following:

    • Images for X items in the user's previous order.
    • Labels for X items in the user's previous order.

• The Shopping Order Tracking cluster shows a sneak peek of pending or recently completed shopping orders from many developer partners in one UI grouping, allowing users to track their orders.

  There is a single ShoppingOrderTracking cluster that is surfaced near the top of the UI, with a priority placement above all Recommendation clusters. Each developer partner is allowed to broadcast multiple ShoppingOrderTrackingEntity items in the Shopping Order Tracking cluster.

  • Your ShoppingOrderTrackingCluster takes the following structure:

    • ShoppingOrderTracking Cluster : A UI view that contains a group of order tracking previews from many developer partners
    • ShoppingOrderTrackingEntity : An object representing a shopping order tracking preview for a single developer partner, to be displayed in the Shopping Order Tracking cluster. The ShoppingOrderTrackingEntity must show the status of the order and the order time. We strongly recommend populating the expected delivery time for ShoppingOrderTrackingEntity, as it's displayed to users when provided.

Pre-work

Minimum API level: 19

Add the com.google.android.engage:engage-core library to your app:

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

For more information, see Package visibility in Android 11 .

خلاصه

The design is based on an implementation of a bound service .

The data a client can publish is subject to the following limits for different cluster types:

Step 1: Provide entity data

The SDK has defined different entities to represent each item type. The following entities are supported for the Shopping category:

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

The charts below outline available attributes and requirements for each type.

ShoppingEntity

The ShoppingEntity object represents a product, promotion, deal, subscription, or event that developer partners want to publish.

ShoppingEntity

ShoppingCart

ShoppingList

ShoppingReorderCluster

ShoppingOrderTrackingCluster

مشخصات تصویر

Required specifications for image assets are listed below:

فرمت های فایل

PNG, JPG, static GIF, WebP

حداکثر اندازه فایل

5120 KB

توصیه های اضافی

• Image safe area: Put your important content in the center 80% of the image.
• Use a transparent background so that the image can be properly displayed in Dark and Light theme settings.

Step 2: Provide Cluster data

It is recommended to have the content publish job executed in the background (for example, using WorkManager ) and scheduled on a regular basis or on an event basis (for example, every time the user opens the app or when the user just added something to their cart).

AppEngageShoppingClient is responsible for publishing shopping clusters.

Following APIs are exposed to publish clusters in the client:

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

isServiceAvailable

This API is used to check if the service is available for integration and whether the content can be presented on the device.

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

This API is used to publish a list of RecommendationCluster objects.

A RecommendationCluster object can have the following attributes:

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

When the service receives the request, the following actions take place within one transaction:

• All existing Recommendation Cluster data is removed.
• Data from the request is parsed and stored in new Recommendation Clusters.

In case of an error, the entire request is rejected and the existing state is maintained.

publishFeaturedCluster

This API is used to publish a FeaturedCluster object.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing FeaturedCluster data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Featured Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishShoppingCart

This API is used to publish a ShoppingCartCluster object.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing ShoppingCart data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Shopping Cart Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishShoppingCarts

This API is used to publish multiple ShoppingCart objects. This is applicable to developer partner publishing separate carts per merchant. Include merchant name in the title when using this API.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing ShoppingCart data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Shopping Cart Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishShoppingList

This API is used to publish a FoodShoppingList object.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing FoodShoppingList data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Shopping List Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishShoppingReorderCluster

This API is used to publish a ShoppingReorderCluster object.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing ShoppingReorderCluster data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Reorder Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishShoppingOrderTrackingCluster

This API is used to publish a ShoppingOrderTrackingCluster object.

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

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

When the service receives the request, the following actions take place within one transaction:

• Existing ShoppingOrderTrackingCluster data from the developer partner is removed.
• Data from the request is parsed and stored in the updated Shopping Order Tracking Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

publishUserAccountManagementRequest

This API is used to publish a Sign In card . The signin action directs users to the app's sign in page so that the app can publish content (or provide more personalized content)

The following metadata is part of the Sign In Card -

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

When the service receives the request, the following actions take place within one transaction:

• Existing UserAccountManagementCluster data from the developer partner is removed.
• Data from the request is parsed and stored in the updated UserAccountManagementCluster Cluster.

In case of an error, the entire request is rejected and the existing state is maintained.

updatePublishStatus

If for any internal business reason, none of the clusters is published, we strongly recommend updating the publish status using the updatePublishStatus API. This is important because :

• Providing the status in all scenarios, even when the content is published (STATUS == PUBLISHED), is critical to populate dashboards that use this explicit status to convey the health and other metrics of your integration.
• If no content is published but the integration status isn't broken (STATUS == NOT_PUBLISHED), Google can avoid triggering alerts in the app health dashboards. It confirms that content is not published due to an expected situation from the provider's standpoint.
• It helps developers provide insights into when the data is published versus not.
• Google may use the status codes to nudge the user to do certain actions in the app so they can see the app content or overcome it.

The list of eligible publish status codes are :

// 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

If the content is not published due to a user not logged in, Google would recommend publishing the Sign In Card. If for any reason providers are not able to publish the Sign In Card then we recommend calling the updatePublishStatus API with the status code 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

This API is used to delete the content of Recommendation Clusters.

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

When the service receives the request, it removes the existing data from the Recommendation Clusters. In case of an error, the entire request is rejected and the existing state is maintained.

deleteFeaturedCluster

This API is used to delete the content of Featured Cluster.

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

When the service receives the request, it removes the existing data from the Featured Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteShoppingCartCluster

This API is used to delete the content of Shopping Cart Cluster.

client.deleteShoppingCartCluster()

client.deleteShoppingCartCluster();

When the service receives the request, it removes the existing data from the Shopping Cart Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteShoppingListCluster

This API is used to delete the content of Shopping List Cluster.

client.deleteShoppingListCluster()

client.deleteShoppingListCluster();

When the service receives the request, it removes the existing data from the Shopping List Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteShoppingReorderCluster

This API is used to delete the content of Shopping Reorder Cluster.

client.deleteShoppingReorderCluster()

client.deleteShoppingReorderCluster();

When the service receives the request, it removes the existing data from the Shopping Reorder Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteShoppingOrderTrackingCluster

This API is used to delete the content of Shopping Order Tracking Cluster.

client.deleteShoppingOrderTrackingCluster()

client.deleteShoppingOrderTrackingCluster();

When the service receives the request, it removes the existing data from the Shopping Order Tracking Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteUserManagementCluster

This API is used to delete the content of UserAccountManagement Cluster.

client.deleteUserManagementCluster()

client.deleteUserManagementCluster();

When the service receives the request, it removes the existing data from the UserAccountManagement Cluster. In case of an error, the entire request is rejected and the existing state is maintained.

deleteClusters

This API is used to delete the content of a given cluster type.

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

When the service receives the request, it removes the existing data from all clusters matching the specified cluster types. Clients can choose to pass one or many cluster types. In case of an error, the entire request is rejected and the existing state is maintained.

رسیدگی به خطا

It is highly recommended to listen to the task result from the publish APIs such that a follow-up action can be taken to recover and resubmit an successful task.

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

The error is returned as an AppEngageException with the cause included as an error code.

Step 3: Handle broadcast intents

In addition to making publish content API calls through a job, it is also required to set up a BroadcastReceiver to receive the request for a content publish.

The goal of broadcast intents is mainly for app reactivation and forcing data sync. Broadcast intents are not designed to be sent very frequently. It is only triggered when the Engage Service determines the content might be stale (for example, a week old). That way, there is more confidence that the user can have a fresh content experience, even if the application has not been executed for a long period of time.

The BroadcastReceiver must be set up in the following two ways:

• Dynamically register an instance of the BroadcastReceiver class using Context.registerReceiver() . This enables communication from applications that are still live in memory.

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

}