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

Engage SDK Watch: Third-party technical integration instructions

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

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

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

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

وضعیت	دسته‌بندی محتوا یا مورد استفاده	سطوح پشتیبانی‌شده
پشتیبانی‌شده (واجدشرایط در همه سطوح)	جاری‌سازی فیلم و تلویزیون تلویزیون زنده / ورزش کلیپ‌های ویدیویی به‌درخواست ویدیوهای ورزشی کوتاه-دراما پادکست‌های تصویری	مجموعه‌ها Entertainment Space برگه برنامه‌های «فروشگاه Play» زبانه «شما» در «فروشگاه Play» صفحه فهرستگان فروشگاه «فروشگاه Play»
تاحدی پشتیبانی می‌شود (در برخی سطوح واجدشرایط است)	کلیپ‌های ویدیویی از برنامه‌های خبری	مجموعه‌ها Entertainment Space
پشتیبانی نمی‌شود	کنترل ازراه‌دور بارگیری‌کننده‌ها، پخش‌کننده‌ها، و ویرایشگرهای ویدیو مرورهای فیلم و نمایش تلویزیونی بلیت فیلم راهنمای تلویزیون تماس‌های تصویری و اتاق‌های گپ

مهارت‌های Android

مشاهده در GitHub

ادغام Engage SDK

از مهارت Android در Engage SDK برای ادغام، اشکال‌زدایی، و حل مشکلات پیاده‌سازی استفاده کنید.

برای نصب مهارت از Android CLI، این دستور را اجرا کنید:

android skills add engage-sdk-integration

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

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

اصطلاحات

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

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

توصیه‌های شما ساختار زیر را دارند:
- خوشه توصیه‌ها: نمای واسط کاربری که حاوی گروهی از توصیه‌ها از یک شریک توسعه‌دهنده است.
  
  شکل ۱. میانای کاربری Entertainment Space که «خوشه توصیه‌ها» را از یک شریک نشان می‌دهد.
- نهاد: شیئی که نشان‌دهنده یک مورد در خوشه است. نهاد می‌تواند فیلم، نمایش تلویزیونی، سریال تلویزیونی، ویدیو زنده، و غیره باشد. برای مشاهده فهرست انواع نهادهای پشتیبانی‌شده، به بخش ارائه داده‌های نهاد مراجعه کنید.
  
  شکل ۲. رابط کاربری Entertainment Space که یک «نهاد» را در «خوشه توصیه‌های» یک شریک نشان می‌دهد.
خوشه ادامه ویدیوهای ناتمام و قسمت‌های جدیداً منتشرشده مربوط را از چندین شریک توسعه‌دهنده در یک گروه واسط کاربر نشان می‌دهد. هر شریک توسعه‌دهنده مجاز خواهد بود حداکثر ۱۰ نهاد را در خوشه «ادامه» همه‌فرستی کند. پژوهش‌ها نشان داده است که توصیه‌های شخصی‌سازی‌شده همراه با محتوای «ادامه» شخصی‌سازی‌شده بهترین تعامل کاربر را ایجاد می‌کند.

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

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

پیش‌کار

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

کتابخانه 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 را ببینید.

خلاصه

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

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

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

مرحله ۰: انتقال از ادغام کیت توسعه نرم‌افزار Media Home موجود

این بخش نحوه انتقال مدل‌های داده Media Home SDK و فراخوانی‌های API موجود به Engage SDK را شرح می‌دهد.

تخصیص مدل‌های داده از یکپارچه‌سازی موجود

اگر از یکپارچه‌سازی Media Home موجود مهاجرت می‌کنید، جدول زیر نحوه نگاشت مدل‌های داده در کیت‌های توسعه نرم‌افزار موجود به Engage SDK جدید را نشان می‌دهد:

معادل ادغام MediaHomeVideoContract	معادل ادغام Engage SDK
`com.google.android.mediahome.video.PreviewChannel`	`com.google.android.engage.common.datamodel.RecommendationCluster`
`com.google.android.mediahome.video.PreviewChannel.Builder`	`com.google.android.engage.common.datamodel.RecommendationCluster.Builder`
`com.google.android.mediahome.video.PreviewChannelHelper`	`com.google.android.engage.video.service.AppEngageVideoClient`
`com.google.android.mediahome.video.PreviewProgram`	به کلاس‌های جداگانه تقسیم شده است: `EventVideo`، `LiveStreamingVideo`، `Movie`، `TvEpisode`، `TvSeason`، `TvShow`، `VideoClipEntity`
`com.google.android.mediahome.video.PreviewProgram.Builder`	به سازندگانی در کلاس‌های جداگانه تقسیم شده است: `EventVideo`، `LiveStreamingVideo`، `Movie`، `TvEpisode`، `TvSeason`، `TvShow`، `VideoClipEntity`
`com.google.android.mediahome.video.VideoContract`	دیگر به آن نیاز ندارم.
`com.google.android.mediahome.video.WatchNextProgram`	به مشخصه‌هایی در کلاس‌های جداگانه تقسیم شده است: `EventVideoEntity`، `LiveStreamingVideoEntity`، `MovieEntity`، `TvEpisodeEntity`، `TvSeasonEntity`، `TvShowEntity`، `VideoClipEntity`
`com.google.android.mediahome.video.WatchNextProgram.Builder`	به مشخصه‌هایی در کلاس‌های جداگانه تقسیم شده است: `EventVideoEntity`، `LiveStreamingVideoEntity`، `MovieEntity`، `TvEpisodeEntity`، `TvSeasonEntity`، `TvShowEntity`، `VideoClipEntity`

انتشار خوشه‌ها در Media Home SDK درمقایسه با Engage SDK

با Media Home SDK، خوشه‌ها و نهادها ازطریق میاناهای برنامه‌سازی کاربردی جداگانه منتشر می‌شدند:

// 1. Fetch existing channels
List<PreviewChannel> channels = PreviewChannelHelper.getAllChannels();

// 2. If there are no channels, publish new channels
long channelId = PreviewChannelHelper.publishChannel(builder.build());

// 3. If there are existing channels, decide whether to update channel contents
PreviewChannelHelper.updatePreviewChannel(channelId, builder.build());

// 4. Delete all programs in the channel
PreviewChannelHelper.deleteAllPreviewProgramsByChannelId(channelId);

// 5. publish new programs in the channel
PreviewChannelHelper.publishPreviewProgram(builder.build());

با Engage SDK، انتشار خوشه و نهاد در یک فراخوانی API ترکیب می‌شود. همه نهادهایی که به یک خوشه تعلق دارند، همراه با آن خوشه منتشر می‌شوند:

کاتلین

RecommendationCluster.Builder()
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .addEntity(MOVIE_ENTITY)
            .setTitle("Top Picks For You")
            .build()

جاوا

new RecommendationCluster.Builder()
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .addEntity(MOVIE_ENTITY)
                        .setTitle("Top Picks For You")
                        .build();

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

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

MovieEntity
TvShowEntity
TvSeasonEntity
TvEpisodeEntity
LiveStreamingVideoEntity
VideoClipEntity

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

`MovieEntity`

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان بازپخش	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش فیلم. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
شناسه منبع یکسان صفحه اطلاعات	اختیاری	پیوند عمیق به برنامه ارائه‌دهنده برای نمایش جزئیات فیلم. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
تاریخ انتشار	اختیاری	بر حسب میلی‌ثانیه.
دردسترس بودن	الزامی	دردسترس: محتوا بدون هیچ اقدام دیگری برای کاربر دردسترس است. FREE_WITH_SUBSCRIPTION: محتوا پس‌از خرید اشتراک توسط کاربر دردسترس است. PAID_CONTENT: محتوا به خرید یا اجاره کاربر نیاز دارد. PURCHASED: محتوا توسط کاربر خریداری یا اجاره شده است.
قیمت پیشنهادی	اختیاری	نوشتار آزاد
مدت	الزامی	برحسب میلی‌ثانیه.
ژانر	الزامی	نوشتار آزاد
رتبه‌بندی‌های محتوا	اختیاری	نوشتار آزاد، از استانداردهای صنعت پیروی کنید. (مثال)
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

`TvShowEntity`

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان صفحه اطلاعات	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای نمایش جزئیات نمایش تلویزیونی. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
شناسه منبع یکسان بازپخش	اختیاری	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش نمایش تلویزیونی. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
تاریخ پخش قسمت اول	اختیاری	بر حسب میلی‌ثانیه.
تاریخ پخش جدیدترین قسمت	اختیاری	بر حسب میلی‌ثانیه.
دردسترس بودن	الزامی	دردسترس: محتوا بدون هیچ اقدام دیگری برای کاربر دردسترس است. FREE_WITH_SUBSCRIPTION: محتوا پس‌از خرید اشتراک توسط کاربر دردسترس است. PAID_CONTENT: محتوا به خرید یا اجاره کاربر نیاز دارد. PURCHASED: محتوا توسط کاربر خریداری یا اجاره شده است.
قیمت پیشنهادی	اختیاری	نوشتار آزاد
تعداد فصل‌ها	الزامی	عدد صحیح مثبت
ژانر	الزامی	نوشتار آزاد
رتبه‌بندی‌های محتوا	اختیاری	نوشتار آزاد، از استانداردهای صنعت پیروی کنید. (مثال)
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

`TvSeasonEntity`

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان صفحه اطلاعات	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای نمایش جزئیات فصل برنامه تلویزیونی. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
شناسه منبع یکسان بازپخش	اختیاری	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش فصل نمایش تلویزیونی. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
نمایش شماره فصل	اختیاری دردسترس در نسخه ۱.۳.۱	رشته
تاریخ پخش قسمت اول	اختیاری	بر حسب میلی‌ثانیه.
تاریخ پخش جدیدترین قسمت	اختیاری	بر حسب میلی‌ثانیه.
دردسترس بودن	الزامی	دردسترس: محتوا بدون هیچ اقدام دیگری برای کاربر دردسترس است. FREE_WITH_SUBSCRIPTION: محتوا پس‌از خرید اشتراک توسط کاربر دردسترس است. PAID_CONTENT: محتوا به خرید یا اجاره کاربر نیاز دارد. PURCHASED: محتوا توسط کاربر خریداری یا اجاره شده است.
قیمت پیشنهادی	اختیاری	نوشتار آزاد
تعداد قسمت‌ها	الزامی	عدد صحیح مثبت
ژانر	الزامی	نوشتار آزاد
رتبه‌بندی‌های محتوا	اختیاری	نوشتار آزاد، از استانداردهای صنعت پیروی کنید. (مثال)
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

`TvEpisodeEntity`

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان بازپخش	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش قسمت. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
شناسه منبع یکسان صفحه اطلاعات	اختیاری	پیوند عمیق به برنامه ارائه‌دهنده برای نمایش جزئیات درباره قسمت برنامه تلویزیونی. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
نمایش شماره قسمت	اختیاری دردسترس در نسخه ۱.۳.۱	رشته
تاریخ پخش	الزامی	بر حسب میلی‌ثانیه.
دردسترس بودن	الزامی	دردسترس: محتوا بدون هیچ اقدام دیگری برای کاربر دردسترس است. FREE_WITH_SUBSCRIPTION: محتوا پس‌از خرید اشتراک توسط کاربر دردسترس است. PAID_CONTENT: محتوا به خرید یا اجاره کاربر نیاز دارد. PURCHASED: محتوا توسط کاربر خریداری یا اجاره شده است.
قیمت پیشنهادی	اختیاری	نوشتار آزاد
مدت	الزامی	باید مقدار مثبتی برحسب میلی‌ثانیه باشد.
ژانر	الزامی	نوشتار آزاد
رتبه‌بندی‌های محتوا	اختیاری	نوشتار آزاد، از استانداردهای صنعت پیروی کنید. (مثال)
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

`LiveStreamingVideoEntity`

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان بازپخش	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش ویدیو. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
پخش کننده	الزامی	نوشتار آزاد
زمان شروع	اختیاری	بر حسب میلی‌ثانیه.
زمان پایان	اختیاری	بر حسب میلی‌ثانیه.
تعداد بازدید	اختیاری	Free text, must be localized.
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

`VideoClipEntity`

شیء VideoClipEntity نشان‌دهنده یک نهاد ویدیویی است که از رسانه‌های اجتماعی، مانند TikTok یا YouTube، می‌آید.

مشخصه	الزام	یادداشت‌ها
نام	الزامی
تصاویر پوستر	الزامی	حداقل یک تصویر لازم است و باید با نسبت ابعادی ارائه شود. (افقی ترجیح داده می‌شود اما توصیه می‌شود که هم تصاویر عمودی و هم افقی را برای سناریوهای مختلف ارسال کنید.) برای راهنمایی، مشخصات تصویر را ببینید.
شناسه منبع یکسان بازپخش	الزامی	پیوند عمیق به برنامه ارائه‌دهنده برای شروع پخش ویدیو. توجه: می‌توانید از پیوندهای عمیق برای اِسناد استفاده کنید. به این پرسشگان مراجعه کنید
زمان ایجاد	الزامی	بر حسب میلی‌ثانیه.
مدت	الزامی	باید مقدار مثبتی برحسب میلی‌ثانیه باشد.
سازنده	الزامی	نوشتار آزاد
تصویر محتواساز	اختیاری	تصویر چهرک «محتواساز»
تعداد بازدید	اختیاری	Free text, must be localized.
نوشتار دعوت به اقدام	اختیاری	نوشتار آزاد برای نمایش به‌عنوان دعوت به اقدام.
برچسب‌ها	اختیاری	فهرست برچسب‌های مرتبط با نهاد.
نوع ساعت بعدی	الزامی مشروط	باید وقتی مورد در خوشه «ادامه» است ارائه شود و باید یکی از چهار نوع زیر باشد: CONTINUE: کاربر قبلاً بیش‌از ۱ دقیقه از این محتوا را تماشا کرده است. جدید: کاربر همه قسمت‌های دردسترس از محتوای چندقسمتی را تماشا کرده است، اما قسمت جدیدی دردسترس قرار گرفته است و دقیقاً یک قسمت تماشانشده وجود دارد. این ویژگی برای محتوای اپیزودیک مانند نمایش‌های تلویزیونی یا مسابقات فوتبال ضبط‌شده در یک مجموعه کار می‌کند. NEXT: کاربر یک یا چند قسمت کامل از محتوای چندقسمتی را تماشا کرده است، اما بیش از یک قسمت یا دقیقاً یک قسمت باقی مانده است که قسمت آخر «جدید» نیست و قبل از اینکه کاربر شروع به تماشای محتوای چندقسمتی کند منتشر شده است. فهرست تماشا: کاربر صریحاً انتخاب کرده است که فیلم، رویداد، یا سریالی را به فهرست تماشا اضافه کند تا آنچه را می‌خواهد بعداً تماشا کند به‌صورت دستی انتخاب کند.
آخرین زمان تعامل	الزامی مشروط	وقتی مورد در خوشه «ادامه» است، باید ارائه شود. در میلی‌ثانیه تاریخ.
زمان آخرین موقعیت بازپخش	الزامی مشروط	وقتی مورد در خوشه «ادامه» باشد و WatchNextType از نوع CONTINUE باشد، باید ارائه شود. بر حسب میلی‌ثانیه.

مشخصات تصویر

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

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

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

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

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

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

ناحیه امن تصویر: محتوای مهم خود را در ۸۰٪ مرکزی تصویر قرار دهید.

مثال

کاتلین

var movie = MovieEntity.Builder()
    .setName("Avengers")
    .addPosterImage(Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
    .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
    .setReleaseDateEpochMillis(1633032895L)
    .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
    .setDurationMillis(12345678L)
    .addGenre("action")
    .addContentRating("R")
    .setWatchNextType(WatchNextType.TYPE_NEW)
    .setLastEngagementTimeMillis(1664568895L)
    .setCallToActionText("Watch Now")
    .addTag("Action")
    .build()

جاوا

MovieEntity movie = new MovieEntity.Builder()
                  .setName("Avengers")
                  .addPosterImage(
                      new Image.Builder()
                          .setImageUri(Uri.parse("http://www.x.com/image.png"))
                          .setImageHeightInPixel(960)
                          .setImageWidthInPixel(408)
                          .build())
                  .setPlayBackUri(Uri.parse("http://tv.com/playback/1"))
                  .setReleaseDateEpochMillis(1633032895L)
                  .setAvailability(ContentAvailability.AVAILABILITY_AVAILABLE)
                  .setDurationMillis(12345678L)
                  .addGenre("action")
                  .addContentRating("R")
                  .setWatchNextType(WatchNextType.TYPE_NEW)
                  .setLastEngagementTimeMillis(1664568895L)
                  .setCallToActionText("Watch Now")
                  .addTag("Action")
                  .build();

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

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

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

isServiceAvailable
publishRecommendationClusters
publishFeaturedCluster
publishContinuationCluster
publishUserAccountManagementRequest
updatePublishStatus
deleteRecommendationsClusters
deleteFeaturedCluster
deleteContinuationCluster
deleteUserManagementCluster
deleteClusters

`isServiceAvailable`

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

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

مهارت‌های Android

مشاهده در GitHub

ادغام Engage SDK

برای نصب مهارت از Android CLI، این دستور را اجرا کنید:

android skills add engage-sdk-integration

اگر تیم شما از ابزارهای کدنویسی هوش مصنوعی (مانند Gemini در Android Studio) استفاده می‌کند، می‌توانید این انتقال را با درخواست از دستیار هوش مصنوعی خود به‌طور خودکار انجام دهید:

Use the engage-sdk-integration skill to use Engage SDK 1.6.0 and refactor isServiceAvailable to pass ServiceAvailabilityRequest for publishing all cluster types.

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

نوع خوشه	ثابت نوع خوشه	مقدار عدد صحیح
نامعلوم	`TYPE_UNKNOWN`	0
خوشه توصیه	`TYPE_RECOMMENDATION`	1
خوشه ویژه	`TYPE_FEATURED`	2
خوشه ادامه	`TYPE_CONTINUATION`	3
خوشه مدیریت کاربر	`TYPE_ENGAGEMENT`	8
خوشه اشتراک	`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 استفاده می‌شود.

کاتلین

client.publishRecommendationClusters(
      PublishRecommendationClustersRequest.Builder()
        .addRecommendationCluster(
          RecommendationCluster.Builder()
            .addEntity(entity1)
            .addEntity(entity2)
            .setTitle("Top Picks For You")
            .build()
        )
        .build()
    )

جاوا

client.publishRecommendationClusters(
            new PublishRecommendationClustersRequest.Builder()
                .addRecommendationCluster(
                    new RecommendationCluster.Builder()
                        .addEntity(entity1)
                        .addEntity(entity2)
                        .setTitle("Top Picks For You")
                        .build())
                .build());

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

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

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

`publishFeaturedCluster`

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

کاتلین

client.publishFeaturedCluster(
    PublishFeaturedClusterRequest.Builder()
      .setFeaturedCluster(
        FeaturedCluster.Builder()
          .addEntity(entity1)
          .addEntity(entity2)
          .build())
      .build())

جاوا

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

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

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

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

`publishContinuationCluster`

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

کاتلین

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

جاوا

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

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

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

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

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

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

`deleteContinuationCluster`

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

کاتلین

client.deleteContinuationCluster()

جاوا

client.deleteContinuationCluster();

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

`deleteUserManagementCluster`

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

کاتلین

client.deleteUserManagementCluster()

جاوا

client.deleteUserManagementCluster();

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

`deleteClusters`

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

کاتلین

client.deleteClusters(
    DeleteClustersRequest.Builder()
      .addClusterType(ClusterType.TYPE_CONTINUATION)
      .addClusterType(ClusterType.TYPE_FEATURED)
      .addClusterType(ClusterType.TYPE_RECOMMENDATION)
      .build())

جاوا

client.deleteClusters(
            new DeleteClustersRequest.Builder()
                .addClusterType(ClusterType.TYPE_CONTINUATION)
                .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 continuation cluster publish when PUBLISH_CONTINUATION 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 Continuation Cluster Publish Intent
  context.registerReceiver(AppEngageBroadcastReceiver(),
                           IntentFilter(Intents.ACTION_PUBLISH_CONTINUATION),
                           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 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),
                         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 Continuation Cluster Publish Intent
context.registerReceiver(new AppEngageBroadcastReceiver(),
                         new IntentFilter(com.google.android.engage.service.Intents.ACTION_PUBLISH_CONTINUATION),
                         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.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 مراجعه کنید.

پرسشگان

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

تماس

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

مراحل بعدی

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

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

Engage SDK Watch: Third-party technical integration instructions با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

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

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

اصطلاحات

پیش‌کار

خلاصه

مرحله ۰: انتقال از ادغام کیت توسعه نرم‌افزار Media Home موجود

تخصیص مدل‌های داده از یکپارچه‌سازی موجود

انتشار خوشه‌ها در Media Home SDK درمقایسه با Engage SDK

کاتلین

جاوا

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

MovieEntity

TvShowEntity

TvSeasonEntity

TvEpisodeEntity

LiveStreamingVideoEntity

VideoClipEntity

مشخصات تصویر

مثال

کاتلین

جاوا

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

isServiceAvailable

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

کاتلین

جاوا

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

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

کاتلین

جاوا

publishRecommendationClusters

کاتلین

جاوا

publishFeaturedCluster

کاتلین

جاوا

publishContinuationCluster

کاتلین

جاوا

publishUserAccountManagementRequest

کاتلین

جاوا

updatePublishStatus

کاتلین

جاوا

deleteRecommendationsClusters

کاتلین

جاوا

deleteFeaturedCluster

کاتلین

جاوا

deleteContinuationCluster

کاتلین

جاوا

deleteUserManagementCluster

کاتلین

جاوا

deleteClusters

کاتلین

جاوا

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

کاتلین

جاوا

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

کاتلین

جاوا

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

پرسشگان

تماس

مراحل بعدی

Engage SDK Watch: Third-party technical integration instructions

`MovieEntity`

`TvShowEntity`

`TvSeasonEntity`

`TvEpisodeEntity`

`LiveStreamingVideoEntity`

`VideoClipEntity`

`isServiceAvailable`

`publishRecommendationClusters`

`publishFeaturedCluster`

`publishContinuationCluster`

`publishUserAccountManagementRequest`

`updatePublishStatus`

`deleteRecommendationsClusters`

`deleteFeaturedCluster`

`deleteContinuationCluster`

`deleteUserManagementCluster`

`deleteClusters`