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

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

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

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

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

اصطلاحات

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

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

  • یک خوشه توصیه می تواند از لیست های ProductEntity ، StoreEntity یا RecipeEntity ساخته شود، اما ترکیبی از انواع موجودیت های مختلف نباشد.

  

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

  

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

  • Cluster سبد خرید غذا باید تعداد کل اقلام موجود در سبد را نشان دهد و همچنین ممکن است تصاویر X مورد در سبد خرید کاربر را نیز شامل شود.

    

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

  

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

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

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

  

قبل از کار

حداقل سطح 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'
}

خلاصه

طراحی بر اساس اجرای یک سرویس محدود است.

داده‌هایی که مشتری می‌تواند منتشر کند مشمول محدودیت‌های زیر برای انواع مختلف خوشه است:

مرحله 1: داده های موجودیت را ارائه دهید

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

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

نمودارهای زیر ویژگی ها و الزامات موجود برای هر نوع را مشخص می کند.

ProductEntity

شی ProductEntity نشان دهنده یک مورد منفرد است (مانند یک کالای خواربارفروشی، غذای یک رستوران یا یک تبلیغ) که شرکای توسعه دهنده می خواهند منتشر کنند.

StoreEntity

شی StoreEntity نشان دهنده یک فروشگاه فردی است که شرکای توسعه دهنده می خواهند منتشر کنند، مانند یک رستوران یا یک فروشگاه مواد غذایی.

RecipeEntity

شی RecipeEntity یک آیتم دستوری را نشان می دهد که شرکای توسعه دهنده می خواهند منتشر کنند.

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

مشخصات تصویر

مشخصات مورد نیاز برای دارایی های تصویر در زیر ذکر شده است:

فرمت های فایل

PNG، JPG، GIF استاتیک، WebP

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

5120 کیلوبایت

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

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

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

توصیه می‌شود کار انتشار محتوا در پس‌زمینه اجرا شود (مثلاً با استفاده از WorkManager ) و به‌طور منظم یا بر اساس رویداد برنامه‌ریزی شود (به عنوان مثال، هر بار که کاربر برنامه را باز می‌کند یا زمانی که کاربر به تازگی چیزی را به سبد خرید خود اضافه کرده است).

AppEngageFoodClient مسئول انتشار خوشه های غذایی است.

API های زیر برای انتشار خوشه ها در مشتری وجود دارد:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• 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("Big savings on Thanksgiving menu")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .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 موجود از شریک توسعه حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه ویژه به روز شده ذخیره می شود.

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

publishFoodShoppingCart

این API برای انتشار یک شی FoodShoppingCart استفاده می شود.

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodShoppingCart موجود از شریک توسعه دهنده حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه سبد خرید به روز شده ذخیره می شود.

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

publishFoodShoppingList

این API برای انتشار یک شی FoodShoppingList استفاده می شود.

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

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

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodShoppingList موجود از شریک سازنده حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه لیست خرید به روز شده ذخیره می شود.

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

publishReorderCluster

این API برای انتشار یک شی FoodReorderCluster استفاده می شود.

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodReorderCluster موجود از شریک توسعه حذف شده است.
• داده‌های درخواست تجزیه و تحلیل می‌شوند و در خوشه ترتیب مجدد به‌روز شده ذخیره می‌شوند.

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

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

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

deleteFoodShoppingCartCluster

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

client.deleteFoodShoppingCartCluster()

client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

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

client.deleteFoodShoppingListCluster()

client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

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

client.deleteReorderCluster()

client.deleteReorderCluster();

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

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(
              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 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_FOOD_SHOPPING_CART
// broadcast is received

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

// Trigger reorder cluster publish when PUBLISH_REORDER_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.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

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

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART توصیه می شود هنگام دریافت این هدف، یک تماس publishFoodShoppingCart را شروع کنید.
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST توصیه می شود هنگام دریافت این هدف، یک تماس publishFoodShoppingList شروع کنید.
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER توصیه می شود هنگام دریافت این هدف، یک تماس publishReorderCluster شروع کنید.

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

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

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

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

تماس بگیرید

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

مراحل بعدی

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

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

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

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

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

اصطلاحات

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

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

  • یک خوشه توصیه می تواند از لیست های ProductEntity ، StoreEntity یا RecipeEntity ساخته شود، اما ترکیبی از انواع موجودیت های مختلف نباشد.

  

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

  

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

  • Cluster سبد خرید غذا باید تعداد کل اقلام موجود در سبد را نشان دهد و همچنین ممکن است تصاویر X مورد در سبد خرید کاربر را نیز شامل شود.

    

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

  

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

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

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

  

قبل از کار

حداقل سطح 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'
}

خلاصه

طراحی بر اساس اجرای یک سرویس محدود است.

داده‌هایی که مشتری می‌تواند منتشر کند مشمول محدودیت‌های زیر برای انواع مختلف خوشه است:

مرحله 1: داده های موجودیت را ارائه دهید

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

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

نمودارهای زیر ویژگی ها و الزامات موجود برای هر نوع را مشخص می کند.

ProductEntity

شی ProductEntity نشان دهنده یک مورد منفرد است (مانند یک کالای خواربارفروشی، غذای یک رستوران یا یک تبلیغ) که شرکای توسعه دهنده می خواهند منتشر کنند.

StoreEntity

شی StoreEntity نشان دهنده یک فروشگاه فردی است که شرکای توسعه دهنده می خواهند منتشر کنند، مانند یک رستوران یا یک فروشگاه مواد غذایی.

RecipeEntity

شی RecipeEntity یک آیتم دستوری را نشان می دهد که شرکای توسعه دهنده می خواهند منتشر کنند.

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

مشخصات تصویر

مشخصات مورد نیاز برای دارایی های تصویر در زیر ذکر شده است:

فرمت های فایل

PNG، JPG، GIF استاتیک، WebP

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

5120 کیلوبایت

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

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

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

توصیه می‌شود کار انتشار محتوا در پس‌زمینه اجرا شود (مثلاً با استفاده از WorkManager ) و به‌طور منظم یا بر اساس رویداد برنامه‌ریزی شود (به عنوان مثال، هر بار که کاربر برنامه را باز می‌کند یا زمانی که کاربر به تازگی چیزی را به سبد خرید خود اضافه کرده است).

AppEngageFoodClient مسئول انتشار خوشه های غذایی است.

API های زیر برای انتشار خوشه ها در مشتری وجود دارد:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• 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("Big savings on Thanksgiving menu")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .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 موجود از شریک توسعه حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه ویژه به روز شده ذخیره می شود.

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

publishFoodShoppingCart

این API برای انتشار یک شی FoodShoppingCart استفاده می شود.

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodShoppingCart موجود از شریک توسعه دهنده حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه سبد خرید به روز شده ذخیره می شود.

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

publishFoodShoppingList

این API برای انتشار یک شی FoodShoppingList استفاده می شود.

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

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

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodShoppingList موجود از شریک سازنده حذف شده است.
• داده های درخواست تجزیه و تحلیل می شود و در خوشه لیست خرید به روز شده ذخیره می شود.

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

publishReorderCluster

این API برای انتشار یک شی FoodReorderCluster استفاده می شود.

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های FoodReorderCluster موجود از شریک توسعه حذف شده است.
• داده‌های درخواست تجزیه و تحلیل می‌شوند و در خوشه ترتیب مجدد به‌روز شده ذخیره می‌شوند.

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

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

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

deleteFoodShoppingCartCluster

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

client.deleteFoodShoppingCartCluster()

client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

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

client.deleteFoodShoppingListCluster()

client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

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

client.deleteReorderCluster()

client.deleteReorderCluster();

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

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(
              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 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_FOOD_SHOPPING_CART
// broadcast is received

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

// Trigger reorder cluster publish when PUBLISH_REORDER_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.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

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

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART توصیه می شود هنگام دریافت این هدف، یک تماس publishFoodShoppingCart را شروع کنید.
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST توصیه می شود هنگام دریافت این هدف ، یک تماس تلفنی publishFoodShoppingList کنید.
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER توصیه می شود هنگام دریافت این هدف ، یک تماس publishReorderCluster شروع کنید.

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

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

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

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

تماس بگیرید

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

مراحل بعدی

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

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

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

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

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

اصطلاحات

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

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

  • یک خوشه توصیه می تواند از لیست های ProductEntity ، StoreEntity یا RecipeEntity ساخته شود ، اما ترکیبی از انواع مختلف موجودیت نیست.

  

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

  

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

  • خوشه سبد خرید مواد غذایی باید تعداد کل موارد موجود در سبد خرید را نشان دهد و همچنین ممکن است شامل تصاویر مربوط به موارد X در سبد کاربر باشد.

    

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

  

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

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

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

  

قبل از کار

حداقل سطح 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'
}

خلاصه

طراحی بر اساس اجرای یک سرویس محدود است.

داده هایی که مشتری می تواند منتشر کند برای انواع مختلف خوشه ای در معرض محدودیت های زیر است:

مرحله 1: داده های موجودیت را ارائه دهید

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

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

نمودارهای زیر ویژگی ها و الزامات موجود برای هر نوع را مشخص می کند.

ProductEntity

شیء ProductEntity یک مورد جداگانه (مانند کالای مواد غذایی ، ظرف از رستوران یا تبلیغی) را نشان می دهد که شرکای توسعه دهنده می خواهند منتشر کنند.

StoreEntity

Object StoreEntity نمایانگر یک فروشگاه شخصی است که شرکای توسعه دهنده می خواهند منتشر کنند ، مانند رستوران یا یک فروشگاه مواد غذایی.

RecipeEntity

شیء RecipeEntity نشان دهنده یک مورد دستور العمل است که شرکای توسعه دهنده می خواهند منتشر کنند.

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

مشخصات تصویر

مشخصات لازم برای دارایی های تصویر در زیر ذکر شده است:

فرمت های فایل

PNG، JPG، GIF استاتیک، WebP

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

5120 کیلوبایت

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

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

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

توصیه می شود که محتوای منتشر شده در پس زمینه (به عنوان مثال ، با استفاده از WorkManager ) اجرا شود و به طور منظم یا به صورت رویداد برنامه ریزی شود (به عنوان مثال ، هر بار که کاربر برنامه را باز می کند یا وقتی کاربر فقط چیزی را به سبد خرید خود اضافه کرده است).

AppEngageFoodClient مسئول انتشار خوشه های غذایی است.

API های زیر برای انتشار خوشه ها در مشتری وجود دارد:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• 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("Big savings on Thanksgiving menu")
                        .build())
                .build())

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Big savings on Thanksgiving menu")
                        .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 موجود از شریک توسعه دهنده حذف می شود.
• داده های حاصل از درخواست تجزیه و در خوشه برجسته به روز شده ذخیره می شود.

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

publishFoodShoppingCart

این API برای انتشار یک شیء FoodShoppingCart استفاده می شود.

client.publishFoodShoppingCart(
            PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    FoodShoppingCart.Builder()
                        ...
                        .build())
                .build())

client.publishFoodShoppingCart(
            new PublishFoodShoppingCartClusterRequest.Builder()
                .setShoppingCart(
                    new FoodShoppingCart.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های موجود FoodShoppingCart از شریک توسعه دهنده حذف می شود.
• داده های این درخواست در خوشه سبد خرید به روز شده تجزیه و ذخیره می شوند.

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

publishFoodShoppingList

این API برای انتشار یک شیء FoodShoppingList استفاده می شود.

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

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

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های موجود FoodShoppingList از شریک توسعه دهنده حذف می شود.
• داده های این درخواست در خوشه لیست خرید به روز شده تجزیه و ذخیره می شوند.

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

publishReorderCluster

این API برای انتشار یک شیء FoodReorderCluster استفاده می شود.

client.publishReorderCluster(
            PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    FoodReorderCluster.Builder()
                        ...
                        .build())
                .build())

client.publishReorderCluster(
            new PublishReorderClusterRequest.Builder()
                .setReorderCluster(
                    new FoodReorderCluster.Builder()
                        ...
                        .build())
                .build());

هنگامی که سرویس درخواست را دریافت می کند، اقدامات زیر در یک تراکنش انجام می شود:

• داده های موجود FoodReorderCluster از شریک توسعه دهنده حذف می شود.
• داده های حاصل از درخواست تجزیه و در خوشه به روز شده به روز شده ذخیره می شود.

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

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteFoodShoppingCartCluster

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

client.deleteFoodShoppingCartCluster()

client.deleteFoodShoppingCartCluster();

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

deleteFoodShoppingListCluster

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

client.deleteFoodShoppingListCluster()

client.deleteFoodShoppingListCluster();

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

deleteReorderCluster

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

client.deleteReorderCluster()

client.deleteReorderCluster();

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

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(
              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 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_FOOD_SHOPPING_CART
// broadcast is received

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

// Trigger reorder cluster publish when PUBLISH_REORDER_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.food.service.Intents.ACTION_PUBLISH_FOOD_SHOPPING_CART));

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

// Register Reorder Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.food.service.Intents.ACTION_PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.food.PUBLISH_REORDER_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.food.PUBLISH_FOOD_SHOPPING_CART توصیه می شود هنگام دریافت این هدف ، یک تماس publishFoodShoppingCart را شروع کنید.
• com.google.android.engage.action.food.PUBLISH_FOOD_SHOPPING_LIST توصیه می شود هنگام دریافت این هدف ، یک تماس تلفنی publishFoodShoppingList کنید.
• com.google.android.engage.action.food.PUBLISH_REORDER_CLUSTER توصیه می شود هنگام دریافت این هدف ، یک تماس publishReorderCluster شروع کنید.

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

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

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

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

تماس بگیرید

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

مراحل بعدی

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

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

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

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

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

اصطلاحات

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

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

  • یک خوشه توصیه می تواند از لیست های ProductEntity ، StoreEntity یا RecipeEntity ساخته شود ، اما ترکیبی از انواع مختلف موجودیت نیست.

  

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

  

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

  • خوشه سبد خرید مواد غذایی باید تعداد کل موارد موجود در سبد خرید را نشان دهد و همچنین ممکن است شامل تصاویر مربوط به موارد X در سبد کاربر باشد.

    

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

  

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

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

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

  

قبل از کار

حداقل سطح 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'
}

خلاصه

طراحی بر اساس اجرای یک سرویس محدود است.

داده هایی که مشتری می تواند منتشر کند برای انواع مختلف خوشه ای در معرض محدودیت های زیر است:

مرحله 1: داده های موجودیت را ارائه دهید

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

1. ProductEntity
2. StoreEntity
3. RecipeEntity
4. FoodShoppingCart
5. FoodShoppingList
6. FoodReorderCluster

نمودارهای زیر ویژگی ها و الزامات موجود برای هر نوع را مشخص می کند.

ProductEntity

شیء ProductEntity یک مورد جداگانه (مانند کالای مواد غذایی ، ظرف از رستوران یا تبلیغی) را نشان می دهد که شرکای توسعه دهنده می خواهند منتشر کنند.

StoreEntity

Object StoreEntity نمایانگر یک فروشگاه شخصی است که شرکای توسعه دهنده می خواهند منتشر کنند ، مانند رستوران یا یک فروشگاه مواد غذایی.

RecipeEntity

شیء RecipeEntity نشان دهنده یک مورد دستور العمل است که شرکای توسعه دهنده می خواهند منتشر کنند.

FoodShoppingCart

FoodShoppingList

FoodReorderCluster

مشخصات تصویر

مشخصات لازم برای دارایی های تصویر در زیر ذکر شده است:

فرمت های فایل

PNG، JPG، GIF استاتیک، WebP

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

5120 کیلوبایت

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

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

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

توصیه می شود که محتوای منتشر شده در پس زمینه (به عنوان مثال ، با استفاده از WorkManager ) اجرا شود و به طور منظم یا به صورت رویداد برنامه ریزی شود (به عنوان مثال ، هر بار که کاربر برنامه را باز می کند یا وقتی کاربر فقط چیزی را به سبد خرید خود اضافه کرده است).

AppEngageFoodClient مسئول انتشار خوشه های غذایی است.

API های زیر برای انتشار خوشه ها در مشتری وجود دارد:

• isServiceAvailable
• publishRecommendationClusters
• publishFeaturedCluster
• publishFoodShoppingCart
• publishFoodShoppingList
• publishReorderCluster
• publishUserAccountManagementRequest
• updatePublishStatus
• deleteRecommendationsClusters
• deleteFeaturedCluster
• deleteFoodShoppingCartCluster
• deleteFoodShoppingListCluster
• deleteReorderCluster
• 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("Big savings on Thanksgiving menu")
                        .build())
                .build())