Engage SDK Shopping: Third-party technical integration instructions

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

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

پشتیبانی دسته‌بندی و سطوح

واجدشرایط بودن سطح Engage SDK براساس دسته محتوای برنامه شما است. از جدول زیر برای تعیین واجدشرایط بودن خود برای سطوح خاص استفاده کنید:

وضعیت دسته‌بندی محتوا یا مورد استفاده سطوح پشتیبانی‌شده
پشتیبانی‌شده
(واجدشرایط در همه سطوح)
  • خرید لباس
  • فروشگاه آنلاین
  • خرده‌فروش
  • خرید نوشیدنی و غذا / خواربار
  • تخفیف و کوپن
  • حیوان خانگی / لوازم
  • خانه و خانه‌داری / املاک و مستغلات
  • مجموعه‌ها
  • برگه برنامه‌های «فروشگاه Play»
  • زبانه «شما» در «فروشگاه Play»
  • صفحه فهرستگان فروشگاه «فروشگاه Play»
پشتیبانی نمی‌شود
  • برنامه Shopper
  • خرید شرکت‌به‌شرکت
  • برنامه فروشنده / بازرگان
  • پاداش‌های اسکنر رسید
  • خدمات مخابراتی
  • اکنون بخرید، بعداً پرداخت کنید

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

این بخش مراحل، مدل‌های داده، و اصطلاحات لازم برای ادغام با Engage SDK برای محتوای خرید را به‌تفصیل شرح می‌دهد.

اصطلاحات

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

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

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

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

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

  • خوشه ویژه مجموعه‌ای از نهادهای چندین شریک توسعه‌دهنده را در یک گروه واسط کاربر نمایش می‌دهد. یک خوشه «ویژه» وجود خواهد داشت که در نزدیکی بالای واسط کاربر با جایگاه اولویت‌دار بالاتر از همه خوشه‌های «توصیه» ظاهر می‌شود. هر شریک توسعه‌دهنده می‌تواند حداکثر ۱۰ نهاد را در خوشه «ویژه» همه‌فرستی کند.

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

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

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

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

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

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

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

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

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

    یک خوشه ShoppingOrderTracking وجود دارد که نزدیک بالای میانای کاربری ظاهر می‌شود و اولویت قرارگیری آن بالاتر از همه خوشه‌های «توصیه» است. هر شریک توسعه‌دهنده مجاز است چندین مورد ShoppingOrderTrackingEntity را در خوشه «پیگیری سفارش مرکز خرید» همه‌فرستی کند.

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

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

پیش‌کار

حداقل سطح میانای برنامه‌سازی کاربردی: ۱۹

کتابخانه 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'
}

برای اطلاعات بیشتر، رؤیت‌پذیری بسته در Android 11 را ببینید.

خلاصه

این طراحی براساس پیاده‌سازی خدمات محدودکننده است.

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

نوع خوشه محدودیت‌های خوشه حداکثر حد مجاز نهاد در خوشه
خوشه(های) توصیه حداکثر ۷ حداکثر ۵۰ ShoppingEntity
خوشه ویژه حداکثر ۱ حداکثر ۲۰ ShoppingEntity
خوشه سبد خرید حداکثر ۱ حداکثر ۳ ShoppingCart

چند سبد خرید فقط برای برنامه‌هایی انتظار می‌رود که برای هر فروشنده سبد خرید جداگانه دارند.

خوشه فهرست خرید حداکثر ۱ حداکثر ۳ ShoppingList
Shopping Reorder Cluster حداکثر ۱ حداکثر ۱ ReorderEntity
Shopping Order Tracking Cluster حداکثر ۳ حداکثر ۳ ShoppingOrderTrackingEntity

مرحله ۱: ارائه داده‌های نهاد

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

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

جدول‌های زیر مشخصه‌های دردسترس و الزامات هر نوع را نشان می‌دهد.

ShoppingEntity

شیء ShoppingEntity نشان‌دهنده محصول، تبلیغ، معامله، اشتراک، یا رویدادی است که شرکای توسعه‌دهنده می‌خواهند منتشر کنند.

ShoppingEntity
مشخصه الزام شرح قالب
تصاویر پوستر الزامی حداقل یک تصویر باید ارائه شود. برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان کنش الزامی

پیوند عمیق به صفحه در برنامه که جزئیات مربوط به نهاد را نمایش می‌دهد.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

Uri
عنوان اختیاری نام نهاد.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۹۰ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
قیمت - فعلی الزامی مشروط

قیمت فعلی نهاد.

اگر قیمت خط‌خورده ارائه شده باشد، باید ارائه شود.

نوشتار آزاد
قیمت - خط‌خورده اختیاری قیمت اصلی نهاد که در واسط کاربر خط‌خورده است. نوشتار آزاد
نوشته راهنما اختیاری توضیح برای ویژه کردن تبلیغ، رویداد، یا به‌روزرسانی برای نهاد، درصورت دردسترس بودن.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۴۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
ریزجزئیات نوشته راهنما اختیاری نوشتار ریزنویس برای نوشته راهنما.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۴۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
رده‌بندی (اختیاری) - توجه: همه رده‌بندی‌ها بااستفاده از سیستم رده‌بندی ستاره‌ای استاندارد ما نمایش داده می‌شوند.
رده‌بندی - مقدار حداکثر اختیاری

حداکثر مقدار مقیاس رده‌بندی.

اگر مقدار فعلی رده‌بندی نیز ارائه شده باشد، باید ارائه شود.

 عدد >= ۰٫۰
رده‌بندی - مقدار فعلی اختیاری

مقدار فعلی مقیاس رده‌بندی.

اگر حداکثر مقدار رده‌بندی نیز ارائه شده باشد، باید ارائه شود.

 عدد >= ۰٫۰
رده‌بندی - تعداد اختیاری

تعداد رده‌بندی‌های نهاد.

توجه: اگر برنامه‌تان نحوه نمایش تعداد به کاربران را کنترل می‌کند، این فیلد را ارائه دهید. از رشته‌ای مختصر استفاده کنید. برای مثال، اگر تعداد ۱٬۰۰۰٬۰۰۰ است، از مخفف‌هایی مثل 1M استفاده کنید تا تعداد در اندازه‌های نمایشگر کوچک‌تر کوتاه نشود.

رشته
رده‌بندی - مقدار شمارش اختیاری

تعداد رده‌بندی‌های نهاد.

توجه: اگر منطق اختصار نمایش را خودتان مدیریت نمی‌کنید، این فیلد را ارائه دهید. اگر هم «تعداد» و هم «مقدار تعداد» وجود داشته باشد، «تعداد» به کاربران نشان داده می‌شود.

 بلند
DisplayTimeWindow (اختیاری) - پنجره زمانی را برای نمایش محتوا در سطح تنظیم کنید
مُهر زمان شروع اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا باید در سطح نشان داده شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه
مُهر زمان پایان اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا دیگر در سطح نشان داده نمی‌شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه

ShoppingCart

مشخصه الزام شرح قالب
شناسه منبع یکسان کنش الزامی

پیوند عمیق به سبد خرید در برنامه شریک.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

Uri
تعداد موارد الزامی

تعداد اقلام (نه فقط تعداد محصولات) در سبد خرید.

برای مثال: اگر ۳ پیراهن یکسان و ۱ کلاه در سبد خرید وجود داشته باشد، این عدد باید ۴ باشد.

عدد صحیح >= ۱
متن کنش اختیاری

نوشتار دعوت به اقدام دکمه در «سبد خرید» (برای مثال، ساک خرید شما).

اگر نوشتار کنش توسط توسعه‌دهنده ارائه نشده باشد، مشاهده سبد خرید پیش‌فرض است.

این مشخصه از نسخه ۱.۱.۰ به بعد پشتیبانی می‌شود.

رشته
عنوان اختیاری

عنوان سبد خرید (برای مثال، کیف خرید شما).

اگر توسعه‌دهنده عنوانی ارائه نکرده باشد، سبد خرید شما به‌عنوان پیش‌فرض استفاده می‌شود.

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

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۲۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
تصاویر سبد خرید اختیاری

تصاویر هر محصول در سبد خرید.

حداکثر ۱۰ تصویر را می‌توان به‌ترتیب اولویت ارائه کرد؛ تعداد واقعی تصاویر نمایش‌داده‌شده به ابعاد دستگاه بستگی دارد.

 برای راهنمایی، مشخصات تصویر را ببینید.
برچسب‌های مورد اختیاری

فهرست برچسب‌های موارد موجود در فهرست خرید.

تعداد واقعی برچسب‌های نمایش‌داده‌شده به ضریب شکل دستگاه بستگی دارد.

فهرست برچسب‌های نوشتاری آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۲۰ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
مُهر زمان آخرین تعامل کاربر اختیاری تعداد میلی‌ثانیه‌های سپری‌شده از مبدأ زمانی که آخرین باری را که کاربر با سبد خرید تعامل داشته است مشخص می‌کند.

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

مُهر زمان تاریخ برحسب میلی‌ثانیه
DisplayTimeWindow (اختیاری) - پنجره زمانی را برای نمایش محتوا در سطح تنظیم کنید
مُهر زمان شروع اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا باید در سطح نشان داده شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه
مُهر زمان پایان اختیاری

مُهر زمان مبدأ که پس‌از آن محتوا دیگر در سطح نشان داده نمی‌شود.

اگر تنظیم نشده باشد، محتوا واجدشرایط نمایش در سطح است.

 مُهر زمان تاریخ برحسب میلی‌ثانیه

ShoppingList

مشخصه الزام شرح قالب
شناسه منبع یکسان کنش الزامی

پیوند عمیق به فهرست خرید در برنامه شریک.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

Uri
تعداد موارد الزامی تعداد موارد موجود در فهرست خرید. عدد صحیح >= ۱
عنوان اختیاری

عنوان فهرست (برای مثال، فهرست خواربار شما).

اگر توسعه‌دهنده عنوانی ارائه نکرده باشد، فهرست خرید پیش‌فرض است.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۲۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
برچسب‌های مورد الزامی

فهرست برچسب‌های موارد موجود در فهرست خرید.

باید حداقل ۱ برچسب ارائه شود و حداکثر ۱۰ برچسب را می‌توان به‌ترتیب اولویت ارائه کرد؛ تعداد واقعی برچسب‌های نمایش‌داده‌شده به ابعاد دستگاه بستگی دارد.

فهرست برچسب‌های نوشتاری آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۲۰ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
مُهر زمان آخرین تعامل کاربر الزامی تعداد میلی‌ثانیه‌های سپری‌شده از مبدأ زمانی که آخرین باری را که کاربر با فهرست خرید تعامل داشته است مشخص می‌کند. مُهر زمان تاریخ برحسب میلی‌ثانیه

ShoppingReorderCluster

مشخصه الزام شرح قالب
شناسه منبع یکسان کنش الزامی

پیوند عمیق برای سفارش مجدد در برنامه شریک.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

Uri
متن کنش اختیاری

نوشتار دعوت به اقدام دکمه در «سفارش مجدد» (برای مثال، سفارش مجدد).

اگر نوشتار کنش توسط توسعه‌دهنده ارائه نشده باشد، تغییر ترتیب پیش‌فرض است.

این مشخصه از نسخه ۱.۱.۰ به بعد پشتیبانی می‌شود.

رشته
تعداد موارد الزامی

تعداد اقلام (نه فقط تعداد محصولات) در سفارش قبلی.

برای مثال: اگر در سفارش قبلی ۳ قهوه کوچک و ۱ کروسان وجود داشت، این عدد باید ۴ باشد.

عدد صحیح >= ۱
عنوان الزامی عنوان مورد سفارش مجدد.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: کمتر از ۴۰ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
برچسب‌های مورد

اختیاری

(اگر ارائه نشده باشد، باید تصاویر پوستر ارائه شود)

فهرست برچسب‌های محصول برای سفارش قبلی.

تا ۱۰ برچسب را می‌توان به‌ترتیب اولویت ارائه کرد؛ تعداد واقعی برچسب‌های نمایش‌داده‌شده به ضریب شکل دستگاه بستگی دارد.

فهرست نوشتار آزاد

اندازه نوشتار توصیه‌شده برای هر برچسب: کمتر از ۲۰ نویسه (نوشتار خیلی طولانی ممکن است با سه‌نقطه نشان داده شود)

تصاویر پوستر

اختیاری

(اگر ارائه نشده باشد، برچسب‌های مورد باید ارائه شود)

تصاویر موارد موجود در سفارش قبلی.

حداکثر ۱۰ تصویر را می‌توان به‌ترتیب اولویت ارائه کرد؛ تعداد واقعی تصاویر نمایش‌داده‌شده به ابعاد دستگاه بستگی دارد.

 برای راهنمایی، مشخصات تصویر را ببینید.

ShoppingOrderTrackingCluster

مشخصه الزام شرح قالب
عنوان الزامی

عنوان کوتاهی از بسته/مواردی که رهگیری می‌شوند یا شماره رهگیری.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: ۵۰ نویسه (نوشتار خیلی طولانی با سه‌نقطه نشان داده می‌شود)

نوع سفارش الزامی

عنوان کوتاهی از بسته/مواردی که رهگیری می‌شوند یا شماره رهگیری.

Enum: IN_STORE_PICKUP, SAME_DAY_DELIVERY, MULTI_DAY_DELIVERY
وضعیت الزامی

وضعیت فعلی سفارش.

برای مثال: «دیرکرد»، «در حمل‌ونقل»، «تأخیر»، «ارسال‌شده»، «تحویل‌شده»، «ناموجود»، «سفارش آماده است»

نوشتار آزاد

اندازه توصیه‌شده نوشتار: ۲۵ نویسه (نوشتاری که خیلی طولانی باشد، با سه‌نقطه نشان داده می‌شود)

زمان سفارش الزامی

مُهر زمان تاریخ یونیکس برحسب میلی‌ثانیه که سفارش در آن ثبت شده است.

اگر بازه زمانی موردانتظار برای تحویل وجود نداشته باشد، زمان سفارش نمایش داده خواهد شد

 مُهر زمان تاریخ برحسب میلی‌ثانیه
شناسه منبع یکسان کنش الزامی

پیوند عمیق به پیگیری سفارش در برنامه شریک.

 Uri
OrderDeliveryTimeWindow (اختیاری) - پنجره زمانی را برای سفارشی که از زمان ثبت سفارش تا زمان تحویل موردانتظار/واقعی پیگیری می‌شود تنظیم کنید.
OrderDeliveryTimeWindow - Start Time اختیاری

مُهر زمان تاریخ برحسب میلی‌ثانیه که سفارش در آن زمان یا پس‌از آن تحویل داده می‌شود یا برای تحویل آماده می‌شود.

 مُهر زمان تاریخ برحسب میلی‌ثانیه
OrderDeliveryTimeWindow - End Time اختیاری

مُهر زمان تاریخ یونیکس برحسب میلی‌ثانیه که سفارش در آن زمان یا قبل‌از آن تحویل داده می‌شود یا برای تحویل آماده می‌شود.

مُهر زمان تاریخ برحسب میلی‌ثانیه
تصاویر پوستر اختیاری

تصویر یک مورد/محصول که بخشی از سفارش است.

نسبت ابعادی توصیه‌شده ۱:۱ است

 برای راهنمایی، مشخصات تصویر را ببینید.
تعداد موارد اختیاری تعداد موارد در سفارش. عدد صحیح >= ۱
شرح اختیاری

یک پاراگراف نوشتاری برای توصیف موارد موجود در سفارش.

توجه: یا شرح یا فهرست زیرنویس به کاربر نمایش داده می‌شود، نه هر دو.

نوشتار آزاد

اندازه توصیه‌شده نوشتار: ۱۸۰ نویسه
فهرست زیرنویس اختیاری

حداکثر ۳ زیرنویس، که هر زیرنویس یک خط نوشتار است.

توجه: یا شرح یا فهرست زیرنویس به کاربر نمایش داده می‌شود، نه هر دو.

نوشتار آزاد

اندازه نوشتار توصیه‌شده برای هر زیرنویس: حداکثر ۵۰ نویسه
Order Value - CurrentPrice اختیاری مقدار فعلی سفارش. نوشتار آزاد
شماره سفارش اختیاری شماره/شناسه سفارش که می‌تواند برای شناسایی منحصربه‌فرد سفارش استفاده شود.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: حداکثر ۲۵ نویسه
شماره ردیابی اختیاری شماره ردگیری برای تحویل سفارش/بسته درصورتی‌که سفارش نیاز به تحویل داشته باشد.

نوشتار آزاد

اندازه نوشتار توصیه‌شده: حداکثر ۲۵ نویسه

مشخصات تصویر

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

نسبت ابعادی حداقل پیکسل پیکسل‌های توصیه‌شده

مربع (۱×۱)

ترجیح داده‌شده برای خوشه‌های غیرویژه

 ۳۰۰×۳۰۰ 1200x1200

افقی (۱٫۹۱x۱)

ترجیح داده‌شده برای خوشه‌های ویژه

 ‫۶۰۰×۳۱۴ 1200x628
عمودی (۴×۵) ‫۴۸۰×۶۰۰ 960x1200

قالب‌های فایل

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

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

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

توصیه‌های بیشتر

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

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

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

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

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

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

isServiceAvailable

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

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

نوع خوشه ثابت نوع خوشه مقدار عدد صحیح
نامعلوم TYPE_UNKNOWN 0
خوشه توصیه TYPE_RECOMMENDATION 1
خوشه ویژه TYPE_FEATURED 2
خوشه ادامه TYPE_CONTINUATION 3
خوشه سبد خرید TYPE_SHOPPING_CART 4
خوشه مدیریت کاربر TYPE_ENGAGEMENT 8
خوشه فهرست خرید TYPE_SHOPPING_LIST 9
Shopping Reorder Cluster TYPE_SHOPPING_REORDER 10
Shopping Order Tracking Cluster TYPE_SHOPPING_ORDER_TRACKING 11
خوشه اشتراک TYPE_SUBSCRIPTION 12

کاتلین

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 امکان بررسی دردسترس بودن برای انواع خوشه‌های خاص را فراهم می‌کند. اگر برنامه‌تان از انتقال متناوب استفاده می‌کند:

  • خوشه‌های ادامه (مانند «سبد خرید»، «فهرست خرید»، «سفارش مجدد»، و «پیگیری سفارش خرید») به‌طور پیش‌فرض در همه دستگاه‌های پشتیبانی‌شده فعال می‌مانند.
  • انواع دیگر خوشه‌ها (مانند «توصیه‌ها») به‌طور متناوب فعال و غیرفعال می‌شوند.

اگر این پیکربندی پیش‌فرض برای نیازهای شما مناسب نیست، با engage-developers@google.com تماس بگیرید.

برای نسخه‌های کیت توسعه نرم‌افزار قبل‌از نسخه ۱.۶.۰ (منسوخ‌شده)

کاتلین

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

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

شیء RecommendationCluster می‌تواند مشخصه‌های زیر را داشته باشد:

مشخصه الزام شرح
فهرست ShoppingEntity الزامی فهرستی از اشیاء ShoppingEntity که توصیه‌های این «خوشه توصیه‌شده» را تشکیل می‌دهند.
عنوان الزامی

عنوان «خوشه توصیه‌ها».

اندازه نوشتار توصیه‌شده: کمتر از ۲۵ نویسه (نوشتاری که خیلی طولانی باشد ممکن است با سه‌نقطه نشان داده شود)
زیرنویس اختیاری زیرعنوان «خوشه توصیه‌ها».
شناسه منبع یکسان کنش اختیاری

پیوند عمیق به صفحه‌ای در برنامه شریک که کاربران می‌توانند فهرست کامل توصیه‌ها را در آنجا ببینند.

توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید

کاتلین

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

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

کاتلین

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

جاوا

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

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

  • داده‌های FeaturedCluster موجود از شریک توسعه‌دهنده برداشته می‌شود.
  • داده‌های درخواست تجزیه می‌شود و در «خوشه ویژه» به‌روزشده ذخیره می‌شود.

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

publishShoppingCarts

این میانای برنامه‌سازی کاربردی برای انتشار فهرستی از اشیای ShoppingCart استفاده می‌شود. این مورد برای شریک توسعه‌دهنده‌ای که سبدهای خرید جداگانه برای هر فروشنده منتشر می‌کند قابل‌اجرا است. هنگام استفاده از این میانای برنامه‌سازی کاربردی، نام فروشنده را در عنوان بگنجانید.

کاتلین

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

جاوا

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

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

  • داده‌های ShoppingCart موجود از شریک توسعه‌دهنده برداشته می‌شود.
  • داده‌های درخواست تجزیه می‌شود و در «خوشه سبد خرید» به‌روزشده ذخیره می‌شود.

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

publishShoppingLists

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

کاتلین

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

جاوا

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

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

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

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

publishShoppingReorderCluster

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

کاتلین

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

جاوا

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

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

  • داده‌های ShoppingReorderCluster موجود از شریک توسعه‌دهنده برداشته می‌شود.
  • داده‌های درخواست تجزیه می‌شود و در «خوشه سفارش مجدد» به‌روزشده ذخیره می‌شود.

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

publishShoppingOrderTrackingCluster

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

کاتلین

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

جاوا

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

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

  • داده‌های ShoppingOrderTrackingCluster موجود از شریک توسعه‌دهنده برداشته می‌شود.
  • داده‌های درخواست تجزیه می‌شود و در «خوشه ردیابی سفارش Shopping» به‌روزشده ذخیره می‌شود.

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

publishUserAccountManagementRequest

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

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

مشخصه الزام شرح
شناسه منبع یکسان کنش الزامی پیوند عمیق به کنش (یعنی پیمایش به صفحه ورود به سیستم برنامه)
تصویر اختیاری - اگر ارائه نشود، عنوان باید ارائه شود

تصویر نشان‌داده‌شده در کارت

تصاویر با نسبت ابعادی ۱۶×۹ و وضوح ۱۲۶۴×۷۱۲
عنوان اختیاری - اگر ارائه نشود، تصویر باید ارائه شود عنوان روی کارت
متن کنش اختیاری نوشتار نشان‌داده‌شده در «دعوت به اقدام» (یعنی ورود به سیستم)
زیرنویس اختیاری زیرنویس اختیاری روی کارت

کاتلین

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

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

جاوا

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

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

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

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

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

updatePublishStatus

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

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

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

// Content is published
AppEngagePublishStatusCode.PUBLISHED,

// Content is not published as user is not signed in
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SIGN_IN,

// Content is not published as user is not subscribed
AppEngagePublishStatusCode.NOT_PUBLISHED_REQUIRES_SUBSCRIPTION,

// Content is not published as user location is ineligible
AppEngagePublishStatusCode.NOT_PUBLISHED_INELIGIBLE_LOCATION,

// Content is not published as there is no eligible content
AppEngagePublishStatusCode.NOT_PUBLISHED_NO_ELIGIBLE_CONTENT,

// Content is not published as the feature is disabled by the client
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_FEATURE_DISABLED_BY_CLIENT,

// Content is not published as the feature due to a client error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_CLIENT_ERROR,

// Content is not published as the feature due to a service error
// Available in v1.3.1
AppEngagePublishStatusCode.NOT_PUBLISHED_SERVICE_ERROR,

// Content is not published due to some other reason
// Reach out to engage-developers@ before using this enum.
AppEngagePublishStatusCode.NOT_PUBLISHED_OTHER

اگر محتوا به‌دلیل وارد نشدن کاربر به سیستم منتشر نشود، Google توصیه می‌کند «کارت ورود به سیستم» منتشر شود. اگر ارائه‌دهندگان به هر دلیلی نتوانند «کارت ورود به سیستم» را منتشر کنند، توصیه می‌کنیم با کد وضعیت NOT_PUBLISHED_REQUIRES_SIGN_IN با میانای برنامه‌سازی کاربردی updatePublishStatus تماس بگیرید

کاتلین

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

deleteRecommendationsClusters

این میانای برنامه‌سازی کاربردی برای حذف محتوای «خوشه‌های توصیه‌شده» استفاده می‌شود.

کاتلین

client.deleteRecommendationsClusters()

جاوا

client.deleteRecommendationsClusters();

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

deleteFeaturedCluster

این میانای برنامه‌سازی کاربردی برای حذف محتوای «دسته ویژه» استفاده می‌شود.

کاتلین

client.deleteFeaturedCluster()

جاوا

client.deleteFeaturedCluster();

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

deleteShoppingCartCluster

این میانای برنامه‌سازی کاربردی برای حذف محتوای «خوشه سبد خرید» استفاده می‌شود.

کاتلین

client.deleteShoppingCartCluster()

جاوا

client.deleteShoppingCartCluster();

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

deleteShoppingListCluster

از این میانای برنامه‌سازی کاربردی برای حذف محتوای «خوشه فهرست خرید» استفاده می‌شود.

کاتلین

client.deleteShoppingListCluster()

جاوا

client.deleteShoppingListCluster();

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

deleteReorderCluster

این میانای برنامه‌سازی کاربردی برای حذف محتوای «خوشه سفارش مجدد Shopping» استفاده می‌شود.

کاتلین

client.deleteReorderCluster()

جاوا

client.deleteReorderCluster();

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

deleteShoppingOrderTrackingCluster

این میانای برنامه‌سازی کاربردی برای حذف محتوای «خوشه پیگیری سفارش Shopping» استفاده می‌شود.

کاتلین

client.deleteShoppingOrderTrackingCluster()

جاوا

client.deleteShoppingOrderTrackingCluster();

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

deleteUserManagementCluster

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

کاتلین

client.deleteUserManagementCluster()

جاوا

client.deleteUserManagementCluster();

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

deleteClusters

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

کاتلین

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

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

مدیریت کردن خطا

توصیه می‌شود به نتیجه تکلیف از میاناهای برنامه‌سازی کاربردی انتشار گوش دهید تا بتوانید کنش پیگیری را برای بازیابی و ارسال مجدد تکلیف موفق انجام دهید.

کاتلین

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

کد خطا نام خطا توجه
1 SERVICE_NOT_FOUND این سرویس در دستگاه ارائه‌شده دردسترس نیست.
2 SERVICE_NOT_AVAILABLE این سرویس در دستگاه ارائه‌شده دردسترس است، اما در زمان تماس دردسترس نیست (برای مثال، صریحاً غیرفعال شده است).
3 SERVICE_CALL_EXECUTION_FAILURE اجرای تکلیف به‌دلیل مشکلات رشته‌ای ناموفق بود. در این مورد، می‌توان دوباره امتحان کرد.
4 SERVICE_CALL_PERMISSION_DENIED تماس‌گیرنده مجاز به برقراری تماس سرویس نیست.
5 SERVICE_CALL_INVALID_ARGUMENT درخواست حاوی داده‌های نامعتبر است (برای مثال، بیشتر از تعداد مجاز خوشه‌ها).
6 SERVICE_CALL_INTERNAL خطایی در سمت سرویس وجود دارد.
7 SERVICE_CALL_RESOURCE_EXHAUSTED فراخوانی سرویس بیش‌ازحد انجام می‌شود.

مرحله ۳: مدیریت هدف‌های همه‌فرستی

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

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

BroadcastReceiver باید به دو روش زیر راه‌اندازی شود:

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

کاتلین

class AppEngageBroadcastReceiver : BroadcastReceiver(){
  // Trigger recommendation cluster publish when PUBLISH_RECOMMENDATION
  // broadcast is received
  // Trigger featured cluster publish when PUBLISH_FEATURED broadcast is
  // received
  // Trigger shopping cart cluster publish when PUBLISH_SHOPPING_CART broadcast
  // is received
  // Trigger shopping list cluster publish when PUBLISH_SHOPPING_LIST broadcast
  // is received
  // Trigger reorder cluster publish when PUBLISH_REORDER_CLUSTER broadcast is
  // received
  // Trigger shopping order tracking cluster publish when
  // PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER broadcast is received
}

fun registerBroadcastReceivers(context: Context){
  var  context = context
  context = context.applicationContext

// Register Recommendation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_RECOMMENDATION),
                           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 به‌صورت ایستا اعلام کنید. این به برنامه اجازه می‌دهد تا زمانی که درحال اجرا نیست، اهداف پخش را دریافت کند و همچنین به برنامه اجازه می‌دهد تا محتوا را منتشر کند.

<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 توصیه می‌شود وقتی این هدف دریافت شد، تماس publishRecommendationClusters شروع شود.
  • com.google.android.engage.action.PUBLISH_FEATURED توصیه می‌شود وقتی این قصد دریافت شد، تماس publishFeaturedCluster شروع شود.
  • com.google.android.engage.action.shopping.PUBLISH_SHOPPING_CART توصیه می‌شود وقتی این قصد دریافت شد، تماس publishShoppingCarts شروع شود.
  • com.google.android.engage.action.shopping.PUBLISH_SHOPPING_LIST توصیه می‌شود وقتی این قصد دریافت شد، تماس publishShoppingLists شروع شود.
  • com.google.android.engage.action.shopping.PUBLISH_REORDER_CLUSTER توصیه می‌شود وقتی این قصد دریافت شد، تماس publishReorderCluster شروع شود.
  • com.google.android.engage.action.shopping.PUBLISH_SHOPPING_ORDER_TRACKING_CLUSTER توصیه می‌شود وقتی این قصد دریافت شد، تماس publishShoppingOrderTrackingCluster شروع شود.

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

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

پرسشگان

برای پرسشگان، به پرسشگان Engage SDK مراجعه کنید.

تماس

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

مراحل بعدی

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

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