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

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

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

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

واژه شناسی

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

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

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

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

      شکل 1. Entertainment Space UI که یک خوشه توصیه از یک شریک را نشان می دهد.
    • Entity: یک شی که یک آیتم را در یک خوشه نشان می دهد. یک موجودیت می تواند یک لیست پخش، یک کتاب صوتی، یک پادکست و موارد دیگر باشد. برای لیستی از انواع موجودیت پشتیبانی شده، به بخش ارائه داده های موجودیت مراجعه کنید.

      شکل 2. Entertainment Space UI که یک موجودیت واحد را در کلاستر توصیه یک شریک نشان می دهد.
  • خوشه Continuation محتوای صوتی را نشان می‌دهد که اخیراً توسط کاربران چندین شریک توسعه‌دهنده در یک گروه UI واحد درگیر شده است. هر شریک توسعه دهنده مجاز است حداکثر 10 موجودیت را در خوشه Continuation پخش کند.

    شکل 3. Entertainment Space UI که یک خوشه Continuation را با توصیه های ناتمام از چندین شریک نشان می دهد (در حال حاضر فقط یک توصیه قابل مشاهده است).
  • خوشه ویژه مجموعه‌ای از آیتم‌ها را از چندین شریک توسعه‌دهنده در یک گروه UI واحد به نمایش می‌گذارد. یک کلاستر ویژه وجود خواهد داشت که در نزدیکی بالای رابط کاربری با اولویت بالاتر از همه خوشه‌های توصیه ظاهر می‌شود. هر شریک توسعه دهنده مجاز به پخش حداکثر 10 موجودیت در خوشه ویژه خواهد بود.

    شکل 4. Entertainment Space UI که یک خوشه ویژه را با توصیه هایی از چند شریک نشان می دهد (در حال حاضر فقط یک توصیه قابل مشاهده است).

قبل از کار

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

خلاصه

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

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

نوع خوشه محدودیت های خوشه ای حداکثر محدودیت موجودیت در یک خوشه
خوشه(های) توصیه حداکثر 5 حداکثر 50
خوشه ادامه حداکثر 1 حداکثر 10
خوشه ویژه حداکثر 1 حداکثر 10

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

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

  1. MusicAlbumEntity
  2. MusicArtistEntity
  3. MusicTrackEntity
  4. MusicVideoEntity
  5. PlaylistEntity
  6. PodcastSeriesEntity
  7. PodcastEpisodeEntity
  8. LiveRadioStationEntity
  9. AudiobookEntity

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

MusicAlbumEntity

شی MusicAlbumEntity یک آلبوم موسیقی را نشان می دهد (به عنوان مثال، Midnights اثر تیلور سویفت).

صفت مورد نیاز یادداشت
نام ضروری عنوان آلبوم موسیقی.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
صفحه اطلاعات uri ضروری

پیوند عمیق به برنامه ارائه دهنده برای جزئیات بیشتر در مورد آلبوم موسیقی.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

هنرمندان ضروری لیست هنرمندان آلبوم موسیقی.
پخش uri اختیاری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
آهنگ ها به حساب می آیند اختیاری تعداد آهنگ های آلبوم موسیقی.
ژانرها اختیاری لیست ژانرهای آلبوم موسیقی.
فرمت آلبوم اختیاری

آلبوم (شامل LP و دوبل ال پی)

EP

تنها

میکس تیپ

برچسب های موسیقی اختیاری لیست برچسب های موسیقی مرتبط با آلبوم.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا آلبوم موسیقی در دستگاه دانلود شده است یا خیر.
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد صریح با یک برچسب "E" ظاهر می شوند.

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

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

درصد پیشرفت کامل شد اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود.

عدد صحیح بین 0 تا 100

MusicArtistEntity

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

صفت مورد نیاز یادداشت
نام ضروری نام هنرمند موسیقی.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
صفحه اطلاعات uri ضروری

پیوند عمیق به برنامه ارائه دهنده برای جزئیات بیشتر در مورد هنرمند موسیقی.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

پخش uri اختیاری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

MusicTrackEntity

شی MusicTrackEntity یک آهنگ موسیقی را نشان می دهد (به عنوان مثال، Yellow توسط Coldplay).

صفت مورد نیاز یادداشت
نام ضروری عنوان آهنگ.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
پخش uri ضروری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

صفحه اطلاعات uri اختیاری

یک پیوند عمیق به برنامه ارائه دهنده برای جزئیات در مورد آهنگ موسیقی.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
مدت زمان اختیاری مدت زمان مسیر بر حسب میلی ثانیه.
آلبوم اختیاری نام آلبومی که آهنگ به آن تعلق دارد.
هنرمندان ضروری لیست هنرمندان برای آهنگ موسیقی.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا آهنگ موسیقی در دستگاه دانلود شده است یا خیر.
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد صریح با یک برچسب "E" ظاهر می شوند.

آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

درصد پیشرفت کامل شد اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود.

عدد صحیح بین 0 تا 100

MusicVideoEntity

شی MusicVideoEntity یک موزیک ویدیو را نشان می دهد (به عنوان مثال، The Weeknd - Take My Breath (ویدئو موزیک رسمی) ).

صفت مورد نیاز یادداشت
نام ضروری عنوان موزیک ویدیو.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
پخش uri ضروری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

صفحه اطلاعات uri اختیاری

یک پیوند عمیق به برنامه ارائه دهنده برای جزئیات در مورد موزیک ویدیو.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

مدت زمان اختیاری مدت زمان ویدیو بر حسب میلی ثانیه
تعداد مشاهده اختیاری تعداد بازدید از ویدیو در قالب متن آزاد.
هنرمندان اختیاری لیست هنرمندان موزیک ویدیو.
رتبه بندی محتوا اختیاری لیست رتبه بندی محتوای آهنگ.
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا موزیک ویدیو در دستگاه دانلود شده است یا خیر.
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد واضح با یک برچسب "E" ظاهر می شوند.

آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

درصد پیشرفت کامل شد اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود.

عدد صحیح بین 0 تا 100

PlaylistEntity

شی PlaylistEntity یک لیست پخش موسیقی را نشان می دهد (به عنوان مثال، لیست پخش 10 برتر ایالات متحده).

صفت مورد نیاز یادداشت
نام ضروری عنوان لیست پخش
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
پخش uri ضروری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

صفحه اطلاعات uri اختیاری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

مدت زمان اختیاری مدت زمان لیست پخش بر حسب میلی ثانیه.
آهنگ ها به حساب می آیند اختیاری تعداد آهنگ های موجود در لیست پخش موسیقی.
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا لیست پخش در دستگاه دانلود شده است یا خیر.
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد واضح با یک برچسب "E" ظاهر می شوند.

آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

درصد پیشرفت کامل شد اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود.

عدد صحیح بین 0 تا 100

PodcastSeriesEntity

شی PodcastSeriesEntity یک سری پادکست را نشان می دهد (به عنوان مثال، This American Life ).

صفت مورد نیاز یادداشت
نام ضروری عنوان مجموعه پادکست.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
صفحه اطلاعات uri ضروری

یک پیوند عمیق به برنامه ارائه دهنده برای جزئیات درباره مجموعه پادکست.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

پخش uri اختیاری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

تعداد قسمت ها اختیاری تعداد قسمت های مجموعه پادکست.
نام تولید اختیاری نام تولید مجموعه پادکست.
میزبان ها اختیاری لیست میزبانان مجموعه پادکست.
ژانرها اختیاری لیست ژانرهای مجموعه پادکست.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا پادکست در دستگاه دانلود شده است یا خیر.
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد صریح با یک برچسب "E" ظاهر می شوند.

آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

PodcastEpisodeEntity

شی PodcastEpisodeEntity یک سری پادکست را نشان می دهد (برای مثال Spark Bird، Episode 754: This American Life ).

صفت مورد نیاز یادداشت
نام ضروری عنوان قسمت پادکست.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
پخش uri ضروری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

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

یک پیوند عمیق به برنامه ارائه دهنده برای جزئیات در مورد قسمت پادکست.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

نام تولید اختیاری نام تولید مجموعه پادکست.
نمایه اپیزود اختیاری شاخص قسمت سریال (شاخص اول 1 است).
میزبان ها اختیاری لیست میزبانان قسمت پادکست.
ژانرها اختیاری لیست ژانرهای قسمت پادکست.
در دستگاه دانلود شد اختیاری Boolean نشان می دهد که آیا قسمت پادکست در دستگاه دانلود شده است یا خیر.
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
پادکست ویدیویی اختیاری Boolean نشان می دهد که آیا قسمت پادکست محتوای ویدیویی دارد یا خیر
صریح اختیاری

یک بولی که نشان می دهد محتوا صریح است یا نه

مواردی که حاوی مطالب صریح هستند یا دارای اخطار مشاوره والدین هستند باید روی TRUE تنظیم شوند. موارد صریح با یک برچسب "E" ظاهر می شوند.

نوع بعدی را گوش دهید اختیاری

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

TYPE_CONTINUE - از سرگیری یک مورد صوتی ناتمام.

TYPE_NEXT - در یکی از سری‌های جدید ادامه دهید.

TYPE_NEW - به تازگی منتشر شده است.

آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

درصد پیشرفت کامل شد اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود.

عدد صحیح بین 0 تا 100

LiveRadioStationEntity

شی LiveRadioStationEntity نشان دهنده یک ایستگاه رادیویی زنده است (به عنوان مثال، 98.1 The Breeze).

صفت مورد نیاز یادداشت
نام ضروری عنوان ایستگاه رادیویی زنده.
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
پخش uri ضروری

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

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

صفحه اطلاعات uri اختیاری

یک پیوند عمیق به برنامه ارائه دهنده برای جزئیات در مورد ایستگاه رادیویی.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

فرکانس اختیاری فرکانسی که ایستگاه رادیویی در آن پخش می شود (به عنوان مثال، "98.1 FM").
نمایش عنوان اختیاری برنامه فعلی که در رادیو پخش می شود.
میزبان ها اختیاری لیست میزبانان ایستگاه رادیویی
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
آخرین زمان نامزدی اختیاری

برای موارد موجود در Continuation Cluster توصیه می شود. ممکن است برای رتبه بندی استفاده شود.

در میلی ثانیه های دوره ای

AudiobookEntity

شی AudiobookEntity یک کتاب صوتی را نشان می دهد (برای مثال، کتاب صوتی Becoming اثر میشل اوباما).

صفت مورد نیاز یادداشت
نام ضروری
تصاویر پوستر ضروری حداقل یک تصویر باید ارائه شود. برای راهنمایی به مشخصات تصویر مراجعه کنید.
نویسنده ضروری حداقل یک نام نویسنده باید ارائه شود.
راوی ضروری حداقل نام یک راوی باید ارائه شود.
لینک اقدام uri ضروری

پیوند عمیق به برنامه ارائه دهنده کتاب صوتی.

توجه: می توانید از پیوندهای عمیق برای ذکر منبع استفاده کنید. به این سؤالات متداول مراجعه کنید

تاریخ انتشار اختیاری در صورت ارائه در میلی ثانیه.
شرح اختیاری در صورت ارائه باید حداکثر 200 کاراکتر باشد.
قیمت اختیاری متن آزاد
مدت زمان اختیاری در صورت ارائه باید یک مقدار مثبت باشد.
ژانر. دسته اختیاری فهرست ژانرهای مرتبط با کتاب.
نام سریال اختیاری نام مجموعه ای که کتاب صوتی به آن تعلق دارد (مثلاً هری پاتر .
شاخص واحد سری اختیاری فهرست کتاب صوتی این مجموعه که 1 اولین کتاب صوتی این مجموعه است. به عنوان مثال، اگر هری پاتر و زندانی آزکابان سومین کتاب این مجموعه باشد، باید روی 3 تنظیم شود.
ادامه نوع کتاب اختیاری

TYPE_CONTINUE - رزومه در یک کتاب ناتمام.

TYPE_NEXT - در یکی از سری‌های جدید ادامه دهید.

TYPE_NEW - به تازگی منتشر شده است.

آخرین زمان نامزدی مشروط مورد نیاز است

زمانی که مورد در خوشه Continuation قرار دارد باید ارائه شود.

در میلی ثانیه های دوره ای.

درصد پیشرفت کامل شده است مشروط مورد نیاز است

زمانی که مورد در خوشه Continuation قرار دارد باید ارائه شود.

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

مقدار باید بزرگتر از 0 و کمتر از 100 باشد.

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

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

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

در میلی ثانیه های دوره ای.

پایان مهر زمان اختیاری

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

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

در میلی ثانیه های دوره ای.

مشخصات تصویر

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

نسبت ابعاد مورد نیاز حداقل پیکسل پیکسل های توصیه شده
مربع (1x1) ضروری 300x300 1200x1200
منظره (1.91x1) اختیاری 600x314 1200x628
پرتره (4x5) اختیاری 480x600 960x1200

فرمت های فایل

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

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

5120 کیلوبایت

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

  • ناحیه امن تصویر: محتوای مهم خود را 80 درصد در مرکز تصویر قرار دهید.

مثال ها

MusicAlbumEntity musicAlbumEntity =
        new MusicAlbumEntity.Builder()
            .setName(NAME)
             .addPosterImage(new Image.Builder()
                  .setImageUri(Uri.parse("http://www.x.com/image.png"))
                  .setImageHeightInPixel(960)
                  .setImageWidthInPixel(408)
                  .build())
            .setPlayBackUri("https://play.google/album/play")
            .setInfoPageUri("https://play.google/album/info")
            .setDescription("A description of this album.")
            .addArtist("Artist")
            .addGenre("Genre")
            .addMusicLabel("Label")
            .addContentRating("Rating")
            .setSongsCount(960)
            .setReleaseDateEpochMillis(1633032895L)
            .setDurationMillis(1633L)
            .build();
AudiobookEntity audiobookEntity =
        new AudiobookEntity.Builder()
            .setName("Becoming")
            .addPosterImage(new Image.Builder()
                 .setImageUri(Uri.parse("http://www.x.com/image.png"))
                 .setImageHeightInPixel(960)
                 .setImageWidthInPixel(408)
                  .build())
            .addAuthor("Michelle Obama")
            .addNarrator("Michelle Obama")
            .setActionLinkUri(
               Uri.parse("https://play.google/audiobooks/1"))
            .setDurationMillis(16335L)
            .setPublishDateEpochMillis(1633032895L)
            .setDescription("An intimate, powerful, and inspiring memoir")
            .setPrice("$16.95")
            .addGenre("biography")
            .build();

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

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

AppEngagePublishClient مسئول انتشار خوشه ها است. API های زیر در سرویس گیرنده موجود هستند:

  • isServiceAvailable
  • publishRecommendationClusters
  • publishFeaturedCluster
  • publishContinuationCluster
  • publishUserAccountManagementRequest
  • updatePublishStatus
  • deleteRecommendationsClusters
  • deleteFeaturedCluster
  • deleteContinuationCluster
  • 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 استفاده می شود.

کاتلین


client.publishRecommendationClusters(
            PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build())

جاوا


client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Trending music")
                        .build())
                .build());

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

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

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

publishFeaturedCluster

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

کاتلین


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

جاوا


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

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

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

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

publishContinuationCluster

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

کاتلین


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

جاوا


client.publishContinuationCluster(
            PublishContinuationClusterRequest.Builder()
                .setContinuationCluster(
                    ContinuationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .build())
                .build())

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

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

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

publishUserAccountManagementRequest

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

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

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

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

تصاویر با نسبت ابعاد 16x9 با وضوح 1264x712

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

کاتلین


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

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

deleteContinuationCluster

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

کاتلین


client.deleteContinuationCluster()

جاوا


client.deleteContinuationCluster();

هنگامی که سرویس درخواست را دریافت می کند، داده های موجود را از Continuation 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 با علت به عنوان کد خطا برگردانده می شود.

کد خطا توجه داشته باشید
SERVICE_NOT_FOUND این سرویس در دستگاه داده شده در دسترس نیست.
SERVICE_NOT_AVAILABLE این سرویس در دستگاه داده شده در دسترس است، اما در زمان تماس در دسترس نیست (مثلاً صراحتاً غیرفعال است).
SERVICE_CALL_EXECUTION_FAILURE اجرای کار به دلیل مشکلات رشته ای انجام نشد. در این صورت می توان آن را دوباره امتحان کرد.
SERVICE_CALL_PERMISSION_DENIED تماس گیرنده مجاز به برقراری تماس سرویس نیست.
SERVICE_CALL_INVALID_ARGUMENT درخواست حاوی داده های نامعتبر است (به عنوان مثال، بیش از تعداد مجاز خوشه ها).
SERVICE_CALL_INTERNAL خطایی در سمت سرویس وجود دارد.
SERVICE_CALL_RESOURCE_EXHAUSTED تماس سرویس خیلی مکرر برقرار می شود.

مرحله 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 continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION));

}
  • به صورت ایستا یک پیاده سازی را با تگ <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.PUBLISH_CONTINUATION" />
      </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.PUBLISH_CONTINUATION توصیه می شود هنگام دریافت این هدف، یک تماس publishContinuationCluster شروع کنید.

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

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

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

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

مخاطب

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

مراحل بعدی

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

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