راهنمای ادغام SDK برای تلویزیون را درگیر کنید

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

Continue Watching از خوشه Continuation برای نمایش ویدیوهای ناتمام استفاده می‌کند و قسمت‌های بعدی را از همان فصل تلویزیون، از چندین برنامه در یک گروه‌بندی رابط کاربری تماشا می‌کند. می‌توانید موجودیت‌های آن‌ها را در این کلاستر ادامه دهید. این راهنما را دنبال کنید تا یاد بگیرید چگونه تعامل کاربر را از طریق تجربه تماشای ادامه با استفاده از Engage SDK افزایش دهید.

مرحله 1: قبل از کار

قبل از شروع، مراحل زیر را کامل کنید:

مطمئن شوید که برنامه شما سطح API 19 یا بالاتر را برای این ادغام هدف قرار می دهد

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

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

   موبایل

   
     dependencies {
       implementation 'com.google.android.engage:engage-core:1.5.5
     }
   

   تلویزیون

   
     dependencies {
       implementation 'com.google.android.engage:engage-tv:1.0.2
     }
   

2. محیط سرویس Engage را در فایل AndroidManifest.xml روی production قرار دهید.

   موبایل

   
   <meta-data
         android:name="com.google.android.engage.service.ENV"
         android:value="PRODUCTION">
   </meta-data>
   

   تلویزیون

   
   <meta-data
       android:name="com.google.android.engage.service.ENV"
       android:value="PRODUCTION">
   </meta-data>
   

3. اضافه کردن مجوز برای WRITE_EPG_DATA برای tv apk

     <uses-permission android:name="com.android.providers.tv.permission.WRITE_EPG_DATA" />
   

4. با استفاده از یک سرویس پس‌زمینه، مانند androidx.work ، برای زمان‌بندی، از انتشار محتوای قابل اعتماد اطمینان حاصل کنید.

5. برای ارائه یک تجربه تماشای یکپارچه، در صورت وقوع این رویدادها، داده‌های تماشای ادامه را منتشر کنید:

   1. اولین ورود: هنگامی که کاربر برای اولین بار وارد سیستم می شود، انتشار داده های او تضمین می کند که تاریخچه مشاهده او بلافاصله در دسترس است.
   2. ایجاد یا تغییر نمایه (برنامه‌های چند نمایه): اگر برنامه شما از چندین نمایه پشتیبانی می‌کند، زمانی که کاربر نمایه‌ها را ایجاد می‌کند یا تغییر می‌دهد، داده‌ها را منتشر کنید. این تضمین می کند که هر کاربر یک تجربه شخصی دارد.
   3. وقفه در پخش ویدیو: برای کمک به کاربران از جایی که کار را متوقف کرده‌اند، داده‌ها را هنگام توقف یا توقف ویدیو، یا زمانی که برنامه در حین پخش خارج می‌شود، منتشر کنید.
   4. ادامه به‌روزرسانی‌های سینی تماشا (در صورت پشتیبانی): وقتی کاربر موردی را از سینی تماشای ادامه خود حذف می‌کند، آن تغییر را با انتشار داده‌های به‌روز منعکس کنید. این تضمین می کند که سینی مرتبط و شخصی باقی می ماند.
   5. تکمیل ویدئو:
      1. برای فیلم‌ها، فیلم تکمیل‌شده را از سینی تماشای ادامه دهید. اگر فیلم بخشی از یک سریال است، فیلم بعدی را اضافه کنید تا کاربر را درگیر خود نگه دارید.
      2. برای قسمت‌ها، قسمت تکمیل‌شده را حذف کنید و قسمت بعدی مجموعه را در صورت موجود بودن اضافه کنید تا تماشای ادامه پیدا کند.

یکپارچه سازی

نمایه حساب

برای اجازه دادن به تجربه شخصی «ادامه تماشا» در Google TV، اطلاعات حساب و نمایه را ارائه دهید. از نمایه حساب برای ارائه موارد زیر استفاده کنید:

1. شناسه حساب: یک شناسه منحصر به فرد که نشان دهنده حساب کاربر در برنامه شما است. این می تواند شناسه واقعی حساب یا یک نسخه مبهم مناسب باشد.

2. شناسه نمایه (اختیاری): اگر برنامه شما از چندین نمایه در یک حساب پشتیبانی می‌کند، یک شناسه منحصر به فرد برای نمایه کاربر خاص (دوباره واقعی یا مبهم) ارائه دهید.

// If your app only supports account
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .build()
// If your app supports both account and profile
val accountProfile = AccountProfile.Builder()
      .setAccountId("your_users_account_id")
      .setProfileId("your_users_profile_id")
.build()

موجودیت ها را ایجاد کنید

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

1. MovieEntity
2. TvEpisodeEntity
3. LiveStreamingVideoEntity
4. VideoClipEntity

URI های مخصوص پلتفرم و تصاویر پوستر را برای این موجودیت ها مشخص کنید.

همچنین، اگر قبلاً این کار را نکرده‌اید، URI‌های پخش برای هر پلتفرم مانند Android TV، Android یا iOS ایجاد کنید. بنابراین وقتی کاربر به تماشای هر پلتفرم ادامه می‌دهد، برنامه از یک URI پخش هدفمند برای پخش محتوای ویدیویی استفاده می‌کند.

// Required. Set this when you want continue watching entities to show up on
// Google TV
val playbackUriTv =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_ANDROID_TV)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_tv"))
              .build()

// Required. Set this when you want continue watching entities to show up on
// Google TV Android app, Entertainment Space, Playstore Widget
val playbackUriAndroid =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_ANDROID_MOBILE)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_android"))
              .build()
// Optional. Set this when you want continue watching entities to show up on
// Google TV iOS app
val playbackUriIos =
          PlatformSpecificUri.Builder()
              .setPlatformType(PlatformType.TYPE_IOS)
              .setActionUri(Uri.parse("https://www.example.com/entity_uri_for_ios"))
              .build()
 val platformSpecificPlaybackUris =
          Arrays.asList(playbackUriTv, playbackUriAndroid, playbackUriIos)

تصاویر پوستر به URI و ابعاد پیکسل (ارتفاع و عرض) نیاز دارند. با ارائه چندین عکس پوستر، عوامل شکلی مختلف را مورد هدف قرار دهید، اما مطمئن شوید که همه تصاویر دارای نسبت تصویر 16:9 و حداقل ارتفاع 200 پیکسل برای نمایش صحیح موجودیت "Continue Watching" هستند، به خصوص در فضای سرگرمی Google. تصاویر با ارتفاع کمتر از 200 پیکسل ممکن است نشان داده نشوند.

Image image1 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image1.png");)
            .setImageHeightInPixel(300)
            .setImageWidthInPixel(169)
            .build()
Image image2 = new Image.Builder()
            .setImageUri(Uri.parse("http://www.example.com/entity_image2.png");)
            .setImageHeightInPixel(640)
            .setImageWidthInPixel(360)
            .build()
// And other images for different form factors.
val images = Arrays.asList(image1, image2)

MovieEntity

این مثال نحوه ایجاد یک MovieEntity با تمام فیلدهای مورد نیاز را نشان می دهد:

val movieEntity = MovieEntity.Builder()
   .setWatchNextType(WatchNextType.TYPE_CONTINUE)
   .setName("Movie name")
   .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
   .addPosterImages(images)
   // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
   .setLastEngagementTimeMillis(1701388800000)
   // Suppose the duration is 2 hours, it is 72000000 in milliseconds
   .setDurationMills(72000000)
   // Suppose last playback offset is 1 hour, 36000000 in milliseconds
   .setLastPlayBackPositionTimeMillis(36000000)
   .build()

ارائه جزئیاتی مانند ژانرها و رتبه‌بندی محتوا به Google TV این قدرت را می‌دهد تا محتوای شما را به روش‌های پویاتر به نمایش بگذارد و آن را با بینندگان مناسب مرتبط کند.

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build();
val contentRatings = Arrays.asList(rating1);
val movieEntity = MovieEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .build()

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

// Set the expiration time to be now plus 30 days in milliseconds
val expirationTime = new DisplayTimeWindow.Builder()
             .setEndTimestampMillis(now().toMillis()+2592000000).build()
val movieEntity = MovieEntity.Builder()
    ...
    .addAvailabilityTimeWindow(expirationTime)
    .build()

TVEpisodeEntity

این مثال نحوه ایجاد یک TvEpisodeEntity با تمام فیلدهای مورد نیاز را نشان می دهد:

val tvEpisodeEntity = TvEpisodeEntity.Builder()
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Episode name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) // 2 hours in milliseconds
    // 45 minutes and 15 seconds in milliseconds is 2715000
    .setLastPlayBackPositionTimeMillis(2715000)
    .setEpisodeNumber("2")
    .setSeasonNumber("1")
    .setShowTitle("Title of the show")
    .build();

رشته شماره اپیزود (مانند "2" ) و رشته شماره فصل (مانند "1" ) قبل از نمایش در کارت ادامه تماشا به شکل مناسب گسترش می یابد. توجه داشته باشید که آنها باید یک رشته عددی باشند، "e2"، "اپیزود 2"، یا "s1" یا "فصل 1" را قرار ندهید.

اگر یک برنامه تلویزیونی خاص یک فصل دارد، شماره فصل را 1 تنظیم کنید.

برای به حداکثر رساندن شانس بینندگان برای یافتن محتوای شما در Google TV، ارائه داده‌های اضافی مانند ژانرها، رتبه‌بندی محتوا و پنجره‌های زمانی در دسترس را در نظر بگیرید، زیرا این جزئیات می‌توانند نمایشگرها و گزینه‌های فیلتر را افزایش دهند.

val genres = Arrays.asList("Action", "Science fiction")
val rating1 = RatingSystem.Builder().setAgencyName("MPAA").setRating("PG-13").build()
val contentRatings = Arrays.asList(rating1)
val tvEpisodeEntity = TvEpisodeEntity.Builder()
    ...
    .addGenres(genres)
    .addContentRatings(contentRatings)
    .setSeasonTitle("Season Title")
    .setShowTitle("Show Title)
    .build();

VideoClipEntity

در اینجا نمونه ای از ایجاد یک VideoClipEntity با تمام فیلدهای مورد نیاز است.

VideoClipEntity یک کلیپ تولید شده توسط کاربر مانند یک ویدیوی یوتیوب را نشان می دهد.

val videoClipEntity = VideoClipEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Video clip name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(600000) //10 minutes in milliseconds
    .setLastPlayBackPositionTimeMillis(300000) //5 minutes in milliseconds
    .addContentRating(contentRating)
    .build();

می‌توانید به‌صورت اختیاری سازنده، تصویر سازنده، زمان ایجاد بر حسب میلی‌ثانیه یا پنجره زمان در دسترس را تنظیم کنید.

LiveStreamingVideoEntity

در اینجا نمونه ای از ایجاد LiveStreamingVideoEntity با تمام فیلدهای مورد نیاز است.

val liveStreamingVideoEntity = LiveStreamingVideoEntity.Builder()
    .setPlaybackUri(Uri.parse("https://www.example.com/uri_for_current_platform")
    .setWatchNextType(WatchNextType.TYPE_CONTINUE)
    .setName("Live streaming name")
    .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
    .addPosterImages(images)
    // Timestamp in millis for sample last engagement time 12/1/2023 00:00:00
    .setLastEngagementTimeMillis(1701388800000)
    .setDurationMills(72000000) //2 hours in milliseconds
    .setLastPlayBackPositionTimeMillis(36000000) //1 hour in milliseconds
    .addContentRating(contentRating)
    .build();

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

برای اطلاعات دقیق در مورد ویژگی ها و الزامات، به مرجع API مراجعه کنید.

داده های خوشه Continuation را ارائه دهید

AppEngagePublishClient مسئول انتشار خوشه Continuation است. شما از متد publishContinuationCluster() برای انتشار یک شی ContinuationCluster استفاده می کنید.

ابتدا باید از isServiceAvailable() استفاده کنید تا بررسی کنید که آیا سرویس برای یکپارچه سازی در دسترس است یا خیر.

client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .addEntity(movieEntity1)
                .addEntity(movieEntity2)
                .addEntity(tvEpisodeEntity1)
                .addEntity(tvEpisodeEntity2)
                .setSyncAcrossDevices(true)
                .build()
        )
        .build();
)

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

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

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

APIهای منتشر شده APIهای بالا هستند. جایگزین محتوای موجود می شود. اگر نیاز به به‌روزرسانی یک موجودیت خاص در ContinuationCluster دارید، باید همه موجودیت‌ها را دوباره منتشر کنید.

داده های ContinuationCluster فقط باید برای حساب های بزرگسال ارائه شود. فقط زمانی منتشر شود که نمایه حساب متعلق به یک بزرگسال باشد.

همگام سازی بین دستگاهی

پرچم SyncAcrossDevices

این پرچم کنترل می‌کند که آیا داده‌های ContinuationCluster کاربر در دستگاه‌های او (تلویزیون، تلفن، تبلت و غیره) همگام‌سازی شود یا خیر. به طور پیش‌فرض روی false تنظیم می‌شود، به این معنی که همگام‌سازی بین دستگاهی به طور پیش‌فرض غیرفعال است.

ارزش ها:

• true: داده‌های ContinuationCluster در تمام دستگاه‌های کاربر به اشتراک گذاشته می‌شود تا تجربه تماشای یکپارچه داشته باشد. ما قویاً این گزینه را برای بهترین تجربه بین دستگاهی توصیه می کنیم.
• false: داده های ContinuationCluster به دستگاه فعلی محدود شده است.

کسب رضایت:

برنامه رسانه باید یک تنظیم واضح برای فعال/غیرفعال کردن همگام‌سازی بین دستگاهی ارائه دهد. مزایا را برای کاربر توضیح دهید و ترجیحات کاربر را یک بار ذخیره کنید و بر اساس آن در publicContinuationCluster اعمال کنید.

// Example to allow cross device syncing.
client.publishContinuationCluster(
    PublishContinuationClusterRequest
        .Builder()
        .setContinuationCluster(
            ContinuationCluster
                .Builder()
                .setAccountProfile(accountProfile)
                .setSyncAcrossDevices(true)
                .build();
        )
        .build();
)

برای استفاده حداکثری از ویژگی بین دستگاهی ما، مطمئن شوید که برنامه شما رضایت کاربر را دریافت کرده و SyncAcrossDevices را به درستی فعال کنید. این اجازه می دهد تا محتوا به طور یکپارچه در بین دستگاه ها همگام شود، که منجر به تجربه کاربری بهتر و افزایش تعامل می شود. به عنوان مثال، شریکی که این را اجرا کرد، شاهد افزایش 40 درصدی کلیک‌های «ادامه تماشا» بود زیرا محتوای آن‌ها در چندین دستگاه نمایش داده می‌شد.

داده‌های کشف ویدیو را حذف کنید

برای حذف دستی داده‌های کاربر از سرور Google TV قبل از دوره نگهداری استاندارد 60 روزه، از روش ()client.deleteClusters استفاده کنید. پس از دریافت درخواست، سرویس تمام داده‌های کشف ویدیوی موجود برای نمایه حساب یا کل حساب را حذف می‌کند.

فهرست DeleteReason دلیل حذف داده ها را مشخص می کند. کد زیر ادامه مشاهده داده ها را هنگام خروج حذف می کند.

// If the user logs out from your media app, you must make the following call
// to remove continue watching data from the current google TV device,
// otherwise, the continue watching data will persist on the current
// google TV device until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

تست کردن

از برنامه راستی‌آزمایی استفاده کنید تا مطمئن شوید که ادغام Engage SDK به درستی کار می‌کند. این برنامه اندروید ابزارهایی را ارائه می‌کند که به شما کمک می‌کند داده‌های خود را تأیید کنید و تأیید کنید که اهداف پخش به درستی مدیریت می‌شوند.

پس از فراخوانی انتشار API، با بررسی برنامه تأیید، تأیید کنید که داده‌های شما به درستی منتشر شده است. خوشه ادامه شما باید به عنوان یک ردیف مجزا در رابط برنامه نمایش داده شود.

• مطمئن شوید که Engage Service Flag در فایل Manifest Android برنامه شما روی تولید تنظیم نشده باشد.
• برنامه Engage Verify را نصب و باز کنید
• اگر isServiceAvailable false است، روی دکمه "Toggle" کلیک کنید تا فعال شود.
• نام بسته برنامه خود را وارد کنید تا پس از شروع انتشار، داده های منتشر شده به طور خودکار مشاهده شود.
• این اقدامات را در برنامه خود آزمایش کنید:
  • وارد شوید.
  • بین پروفایل ها جابجا شوید (در صورت وجود).
  • شروع کنید، سپس یک ویدیو را متوقف کنید یا به صفحه اصلی بازگردید.
  • برنامه را در حین پخش ویدیو ببندید.
  • یک مورد را از ردیف "ادامه تماشا" (در صورت پشتیبانی) حذف کنید.
• پس از هر اقدام، تأیید کنید که برنامه شما از API publicContinuationClusters استفاده کرده است و داده‌ها به درستی در برنامه تأیید نمایش داده می‌شوند.

• برنامه راستی‌آزمایی یک چک سبز رنگ «همه خوب» را برای موجودیت‌هایی که به درستی اجرا شده‌اند نشان می‌دهد.

  

• برنامه راستی‌آزمایی هر موجودیت مشکل‌ساز را پرچم‌گذاری می‌کند.

  

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