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

با دسترسی به کاربران خود در هر کجا که هستند، تعامل با برنامه را افزایش دهید. Engage SDK را ادغام کنید تا توصیه‌های شخصی‌سازی‌شده و محتوای مداوم را مستقیماً به کاربران در سطوح مختلف روی دستگاه، مانند Collections ، Entertainment Space و Play Store ارائه دهید. این ادغام کمتر از ۵۰ کیلوبایت (فشرده‌شده) به میانگین APK اضافه می‌کند و برای اکثر برنامه‌ها حدود یک هفته از زمان توسعه‌دهنده را می‌گیرد. برای اطلاعات بیشتر به سایت تجاری ما مراجعه کنید.

این راهنما شامل دستورالعمل‌هایی برای شرکای توسعه‌دهنده است تا محتوای خرید را به سطوح محتوای Engage ارسال کنند.

جزئیات ادغام

اصطلاحات

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

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

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

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

  • ShoppingEntity: یک شیء که نشان‌دهنده یک آیتم واحد در یک خوشه است.

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

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

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

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

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

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

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

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

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

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

  یک خوشه ShoppingOrderTracking واحد وجود دارد که در نزدیکی بالای رابط کاربری ظاهر می‌شود و اولویت آن بالاتر از همه خوشه‌های توصیه (Recommendation) است. هر شریک توسعه‌دهنده مجاز است چندین مورد ShoppingOrderTrackingEntity را در خوشه Shopping Order Tracking پخش کند.

  • کلاستر ShoppingOrderTrackingCluster شما ساختار زیر را می‌گیرد:

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

پیش کار

حداقل سطح API: ۱۹

کتابخانه com.google.android.engage:engage-core به برنامه خود اضافه کنید:

dependencies {
    // Make sure you also include that repository in your project's build.gradle file.
    implementation 'com.google.android.engage:engage-core:1.6.0'
}

For more information, see Package visibility in Android 11 .

خلاصه

طراحی بر اساس پیاده‌سازی یک سرویس محدود (bound service) است.

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

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

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

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

نمودارهای زیر ویژگی‌ها و الزامات موجود برای هر نوع را شرح می‌دهند.

ShoppingEntity

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

ShoppingEntity

ShoppingCart

ShoppingList

ShoppingReorderCluster

ShoppingOrderTrackingCluster

مشخصات تصویر

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

فرمت‌های فایل

PNG، JPG، GIF ثابت، WebP

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

۵۱۲۰ کیلوبایت

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

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

مرحله ۲: ارائه داده‌های خوشه‌ای

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

AppEngageShoppingClient مسئول انتشار خوشه‌های خرید است.

API های زیر برای انتشار خوشه ها در کلاینت در دسترس هستند:

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

isServiceAvailable

این API برای بررسی اینکه آیا سرویس برای ادغام در دسترس است و آیا محتوا می‌تواند روی دستگاه ارائه شود، استفاده می‌شود.

برای Engage SDK نسخه ۱.۶.۰ و بالاتر (توصیه شده)

شما می‌توانید در دسترس بودن سرویس را برای هر نوع کلاستری که قصد انتشار آن را دارید، بررسی کنید. isServiceAvailable API یک شیء درخواست به نام ServiceAvailabilityRequest را می‌پذیرد که شامل انواع کلاستری است که در دسترس بودن سرویس برای آنها باید بررسی شود. می‌توانید مقادیر شمارشی ClusterType مورد نیاز برای ServiceAvailabilityRequest را از جدول زیر پیدا کنید.

val request = ServiceAvailabilityRequest.Builder()
    .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
    .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
    .build()

client.isServiceAvailable(request).addOnCompleteListener { task ->
    if (task.isSuccessful) {
        val availabilityMap = task.result
        if (availabilityMap[ClusterType.TYPE_CONTINUATION] == true) {
            // Proceed with publishing continuation content
        }
        if (availabilityMap[ClusterType.TYPE_RECOMMENDATION] == true) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
}

ServiceAvailabilityRequest request =
    new ServiceAvailabilityRequest.Builder()
        .addIntendedClusterType(ClusterType.TYPE_CONTINUATION)
        .addIntendedClusterType(ClusterType.TYPE_RECOMMENDATION)
        .build();

client.isServiceAvailable(request).addOnCompleteListener(task -> {
    if (task.isSuccessful()) {
        Map<Integer, Boolean> availabilityMap = task.getResult();
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_CONTINUATION))) {
            // Proceed with publishing continuation content
        }
        if (Boolean.TRUE.equals(availabilityMap.get(ClusterType.TYPE_RECOMMENDATION))) {
            // Proceed with publishing recommendation content
        }
    } else {
        // The IPC call itself fails, proceed with error handling logic here,
        // such as retry.
    }
});

ویژگی دسترسی مشروط به سرویس

برخی از برنامه‌های یکپارچه، پیکربندی خاصی را درخواست می‌کنند که سرویس Engage را به طور متناوب فعال و غیرفعال کند تا هزینه سرویس‌دهی خود را کاهش دهند. این استراتژی مصرف محتوای متناوب، اگرچه ممکن است، اما بر کاربر و محصول تأثیر منفی می‌گذارد - محتوای قدیمی ارائه نمی‌شود و برخی از سطوح اصلاً سرویس‌دهی نمی‌شوند.

از نسخه ۱.۶.۰ به بعد، Engage SDK امکان بررسی در دسترس بودن انواع خاصی از کلاسترها را فراهم می‌کند. این امر انعطاف‌پذیری بیشتری را فراهم می‌کند، به طوری که اگر استراتژی محتوای متناوب توسط یک برنامه خاص اتخاذ شده باشد، برخی از انواع کلاسترها می‌توانند از آن استراتژی متناوب پیروی کنند در حالی که سایر انواع کلاسترها همیشه فعال هستند (یعنی کلاسترهای مداوم).

اگر سرویس Engage به هر دلیلی نباید به صورت «مداوم» روی تمام دستگاه‌های پشتیبانی‌شده فعال باشد و برای هر مجموعه‌ای از دستگاه‌ها به صورت مصرف متناوب پیکربندی شده باشد، تمام انتشارات خوشه‌های مداوم (مثلاً سبد خرید، لیست خرید، سفارش مجدد و ردیابی سفارش خرید) همچنان با پیکربندی پیش‌فرض فعال خواهند بود و بقیه انواع خوشه‌ها به صورت متناوب فعال و غیرفعال می‌شوند. اگر مصرف متناوب برای شما صدق می‌کند اما این پیکربندی پیش‌فرض برای نیازهای شما مناسب نیست، لطفاً با engage-developers@google.com تماس بگیرید.

برای نسخه‌های SDK قبل از v1.6.0 (منسوخ شده)

client.isServiceAvailable.addOnCompleteListener { task ->
    if (task.isSuccessful) {
        // Handle IPC call success
        if(task.result) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
}

client.isServiceAvailable().addOnCompleteListener(task - > {
    if (task.isSuccessful()) {
        // Handle success
        if(task.getResult()) {
          // Service is available on the device, proceed with content publish
          // calls.
        } else {
          // Service is not available, no further action is needed.
        }
    } else {
      // The IPC call itself fails, proceed with error handling logic here,
      // such as retry.
    }
});

publishRecommendationClusters

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

یک شیء 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());

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

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

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

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

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

publishShoppingLists

این API برای انتشار لیستی از اشیاء ShoppingList استفاده می‌شود.

client.publishShoppingLists(
            PublishShoppingListsRequest.Builder()
                .addShoppingList(
                    ShoppingList.Builder()
                        ...
                        .build())
                .build())

client.publishShoppingLists(
            new PublishShoppingListsRequest.Builder()
                .addShoppingList(
                    new ShoppingListEntity.Builder()
                        ...
                        .build())
                .build());

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

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

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

publishShoppingReorderCluster

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

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

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

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

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

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

publishShoppingOrderTrackingCluster

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

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

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

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

• Existing ShoppingOrderTrackingCluster data from the developer partner is removed.
• داده‌های درخواست تجزیه و تحلیل شده و در خوشه‌ی به‌روزرسانی‌شده‌ی ردیابی سفارش خرید ذخیره می‌شوند.

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

publishUserAccountManagementRequest

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

فراداده‌های زیر بخشی از کارت ورود به سیستم هستند -

var SIGN_IN_CARD_ENTITY =
      SignInCardEntity.Builder()
          .addPosterImage(
              Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build()

client.publishUserAccountManagementRequest(
            PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

SignInCardEntity SIGN_IN_CARD_ENTITY =
      new SignInCardEntity.Builder()
          .addPosterImage(
              new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(500)
                  .setImageWidthInPixel(500)
                  .build())
          .setActionText("Sign In")
          .setActionUri(Uri.parse("http://xx.com/signin"))
          .build();

client.publishUserAccountManagementRequest(
            new PublishUserAccountManagementRequest.Builder()
                .setSignInCardEntity(SIGN_IN_CARD_ENTITY)
                .build());

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

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

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

updatePublishStatus

اگر به هر دلیل داخلی تجاری، هیچ یک از کلاسترها منتشر نشده‌اند، اکیداً توصیه می‌کنیم وضعیت انتشار را با استفاده از API مربوط به updatePublishStatus به‌روزرسانی کنید. این مهم است زیرا:

• ارائه وضعیت در همه سناریوها، حتی زمانی که محتوا منتشر شده است (وضعیت == منتشر شده)، برای پر کردن داشبوردهایی که از این وضعیت صریح برای انتقال سلامت و سایر معیارهای ادغام شما استفاده می‌کنند، بسیار مهم است.
• اگر هیچ محتوایی منتشر نشده باشد اما وضعیت ادغام خراب نباشد (STATUS == NOT_PUBLISHED)، گوگل می‌تواند از نمایش هشدارها در داشبوردهای سلامت برنامه جلوگیری کند. این تأیید می‌کند که محتوا به دلیل وضعیت مورد انتظار از دیدگاه ارائه‌دهنده منتشر نشده است.
• این به توسعه‌دهندگان کمک می‌کند تا بینشی در مورد زمان انتشار داده‌ها در مقابل عدم انتشار آنها ارائه دهند.
• گوگل ممکن است از کدهای وضعیت برای ترغیب کاربر به انجام اقدامات خاص در برنامه استفاده کند تا بتواند محتوای برنامه را ببیند یا از آن عبور کند.

لیست کدهای وضعیت انتشار واجد شرایط عبارتند از:

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

اگر محتوا به دلیل عدم ورود کاربر منتشر نشود، گوگل انتشار کارت ورود به سیستم را توصیه می‌کند. اگر به هر دلیلی ارائه دهندگان خدمات قادر به انتشار کارت ورود به سیستم نیستند، توصیه می‌کنیم API مربوط به updatePublishStatus را با کد وضعیت NOT_PUBLISHED_REQUIRES_SIGN_IN فراخوانی کنید.

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

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

deleteRecommendationClusters

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

client.deleteRecommendationClusters()

client.deleteRecommendationClusters();

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

deleteFeaturedCluster

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

client.deleteFeaturedCluster()

client.deleteFeaturedCluster();

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

deleteShoppingCartCluster

این API برای حذف محتوای سبد خرید (Shopping Cart Cluster) استفاده می‌شود.

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 استفاده می‌شود.

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

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.

مدیریت خطا

اکیداً توصیه می‌شود که به نتیجه‌ی وظیفه از 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 برگردانده می‌شود و علت آن به صورت کد خطا درج می‌شود.

مرحله ۳: مدیریت اهداف پخش

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

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

BroadcastReceiver باید به دو روش زیر تنظیم شود:

• با استفاده از Context.registerReceiver() یک نمونه از کلاس BroadcastReceiver را به صورت پویا ثبت کنید. این کار امکان ارتباط از برنامه‌هایی را که هنوز در حافظه فعال هستند، فراهم می‌کند.

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),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Featured Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_FEATURED),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Shopping Cart Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_CART),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Shopping List Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_LIST),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Reorder Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_REORDER_CLUSTER),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)

// Register Shopping Order Tracking Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER),
                           com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                           /*scheduler=*/null)
}

class AppEngageBroadcastReceiver extends BroadcastReceiver {
// Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION broadcast
// is received

// Trigger featured cluster publish when PUBLISH_FEATURED broadcast is received

// Trigger 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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

// Register Featured Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_FEATURED),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

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

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

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

// 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),
                         com.google.android.engage.service.BroadcastReceiverPermissions.BROADCAST_REQUEST_DATA_PUBLISH_PERMISSION,
                         /*scheduler=*/null);

}

• یک پیاده‌سازی را به صورت ایستا با تگ <receiver> در فایل AndroidManifest.xml خود تعریف کنید. این به برنامه اجازه می‌دهد تا در زمانی که در حال اجرا نیست، اهداف پخش (broadcast intents) را دریافت کند و همچنین به برنامه اجازه می‌دهد تا محتوا را منتشر کند.

<application>
   <receiver
      android:name=".AppEngageBroadcastReceiver"
      android:permission="com.google.android.engage.REQUEST_ENGAGE_DATA"
      android:exported="true"
      android:enabled="true">
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_RECOMMENDATION" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.PUBLISH_FEATURED" />
      </intent-filter>
      <intent-filter>
         <action android:name="com.google.android.engage.action.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 توصیه می‌شود هنگام دریافت این intent، یک فراخوانی publishRecommendationClusters آغاز شود.
• com.google.android.engage.action.PUBLISH_FEATURED توصیه می‌شود هنگام دریافت این intent، یک فراخوانی publishFeaturedCluster آغاز شود.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART It is recommended to start a publishShoppingCarts call when this intent is received.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST It is recommended to start a publishShoppingLists call when this intent is received.
• com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER It is recommended to start a publishReorderCluster call when this intent is received.
• com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER It is recommended to start a publishShoppingOrderTrackingCluster call when this intent is received.

Integration workflow

For a step-by-step guide on verifying your integration after it is complete, see Engage developer integration workflow .

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

See Engage SDK Frequently Asked Questions for FAQs.

تماس

Contact engage-developers@google.com if there are any questions during the integration process. Our team replies as soon as possible.

مراحل بعدی

After completing this integration, your next steps are as follows:

• Send an email to engage-developers@google.com and attach your integrated APK that is ready for testing by Google.
• Google performs a verification and reviews internally to make sure the integration works as expected. If changes are needed, Google contacts you with any necessary details.
• When testing is complete and no changes are needed, Google contacts you to notify you that you can start publishing the updated and integrated APK to the Play Store.
• After Google has confirmed that your updated APK has been published to the Play Store, your Recommendation , Featured , Shopping Cart , Shopping List , Reorder Cluster and Shopping Order Tracking Cluster clusters may be published and visible to users.