SDK را برای توصیه‌های ویدیویی درگیر کنید

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

Recommendation از خوشه Recommendation برای نمایش فیلم‌ها و نمایش‌های تلویزیونی از چندین برنامه در یک گروه UI استفاده می‌کند. هر شریک توسعه‌دهنده می‌تواند حداکثر 25 موجودیت را در هر خوشه توصیه‌ها پخش کند و در هر درخواست حداکثر 7 خوشه توصیه وجود دارد.

قبل از کار

قبل از شروع، مراحل زیر را کامل کنید. 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 قرار دهید.

    برای apk موبایل

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

    برای tv apk

    
    <meta-data
        android:name="com.google.android.engage.service.ENV"
        android:value="PRODUCTION">
    </meta-data>
    
  3. انتشار را در یک سرویس پیش زمینه اجرا کنید.

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

    1. اولین ورود کاربر در روز. ( یا )
    2. هنگامی که کاربر شروع به تعامل با برنامه می کند.

یکپارچه سازی

AppEngagePublishClient خوشه توصیه را منتشر می کند. از متد publishRecommendationClusters برای انتشار یک شیء توصیه استفاده کنید.

از isServiceAvailable() 2 برای بررسی اینکه آیا سرویس برای ادغام در دسترس است یا خیر استفاده کنید.

val client = AppEngagePublishClient(context)

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.
      client.publishRecommendationClusters(recommendationRequest)
    } else {
      // Service is not available
    }
  } else {
    // The IPC call itself fails, proceed with error handling logic here,
    // such as retry.
  }
}

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

خوشه ها گروه بندی منطقی موجودیت ها هستند. مثال‌های کد زیر نحوه ساخت خوشه‌ها را بر اساس ترجیح شما و نحوه ایجاد درخواست انتشار برای همه خوشه‌ها توضیح می‌دهد.

// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
  .Builder()
  .addEntity(movie)
  .addEntity(tvShow)
  .setTitle("Popular Movies")
  .build()

// cluster for top searches
val recommendationCluster2 = RecommendationCluster
  .Builder()
  .addEntity(movie)
  .addEntity(tvShow)
  .setTitle("Top Searches")
  .build()

// creating a publishing request
val recommendationRequest = PublishRecommendationClustersRequest
  .Builder()
  .setSyncAcrossDevices(true)
  .setAccountProfile(accountProfile)
  .addRecommendationCluster(recommendationCluster1)
  .addRecommendationCluster(recommendationCluster2)
  .build()

یک نمایه حساب ایجاد کنید

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

  1. شناسه حساب: یک شناسه منحصر به فرد که نشان دهنده حساب کاربر در برنامه شما است. این می تواند شناسه واقعی حساب یا یک نسخه مبهم مناسب باشد.
  2. شناسه نمایه (اختیاری): اگر برنامه شما از چندین نمایه در یک حساب پشتیبانی می کند، یک شناسه منحصر به فرد برای نمایه کاربر خاص ارائه دهید.
  3. محلی (اختیاری): شما می توانید به صورت اختیاری زبان مورد نظر کاربر را ارائه دهید. اگر MediaActionFeedEntity در RecommendationRequest ارسال کنید، این فیلد مفید است.
// If app only supports account
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .build();

// If app supports both account and profile
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .setProfileId("profile_id")
  .build();

// set Locale
val accountProfile = AccountProfile.Builder()
  .setAccountId("account_id")
  .setProfileId("profile_id")
  .setLocale("en-US")
  .build();

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

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

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

پرچم SyncAcrossDevices کنترل می‌کند که آیا داده‌های خوشه توصیه‌های کاربر با Google TV به اشتراک گذاشته می‌شود و در دستگاه‌های او مانند تلویزیون، تلفن، رایانه لوحی در دسترس است یا خیر. برای اینکه توصیه کار کند، باید روی true تنظیم شود.

برنامه رسانه باید یک تنظیم واضح برای فعال یا غیرفعال کردن همگام سازی بین دستگاهی ارائه دهد. مزایا را برای کاربر توضیح دهید و ترجیحات کاربر را یک بار ذخیره کنید و بر این اساس در درخواست publishRecommendations اعمال کنید. برای استفاده حداکثری از ویژگی بین دستگاهی، تأیید کنید که برنامه رضایت کاربر را دریافت کرده و SyncAcrossDevices به true فعال می‌کند.

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

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

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

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

// If the user revokes the consent to share data with Google TV,
// you must make the following call to remove recommendations data from
// all current google TV devices. Otherwise, the recommendations data persists
// until 60 days later.
client.deleteClusters(
  new DeleteClustersRequest.Builder()
    .setAccountProfile(AccountProfile())
    .setReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

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

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

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity

توضیحات

یک توضیح کوتاه برای هر نهاد ارائه دهید. این توضیحات زمانی نمایش داده می‌شود که کاربران ماوس را بر روی نهاد قرار می‌دهند و جزئیات بیشتری را در اختیار آنها قرار می‌دهند.

URI های پخش ویژه پلتفرم

URI های پخش را برای هر پلتفرم پشتیبانی شده ایجاد کنید: Android TV، Android یا iOS. این به سیستم اجازه می دهد تا URI مناسب را برای پخش ویدیو در پلتفرم مربوطه انتخاب کند.

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

// Required. Set this when you want recommended 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()

// Optional. Set this when you want recommended entities to show up on
// Google TV Android app
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 recommended 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)

// Provide appropriate rating for the system.
val contentRating = new RatingSystem
  .Builder()
  .setAgencyName("MPAA")
  .setRating("PG-13")
  .build()

تصاویر پوستر

تصاویر پوستر به URI و ابعاد پیکسل (ارتفاع و عرض) نیاز دارند. با ارائه چندین تصویر پوستر، عوامل شکلی مختلف را مورد هدف قرار دهید، اما تأیید کنید که همه تصاویر دارای نسبت تصویر 16:9 و حداقل ارتفاع 200 پیکسل برای نمایش صحیح موجودیت "توصیه‌ها" هستند، به خصوص در فضای سرگرمی 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)

دلیل توصیه

به صورت اختیاری یک دلیل توصیه ارائه کنید که می تواند توسط Google TV برای ایجاد دلایلی برای پیشنهاد یک فیلم یا نمایش تلویزیونی خاص به کاربر استفاده شود.

//Allows us to construct reason: "Because it is top 10 on your Channel"
val topOnPartner = RecommendationReasonTopOnPartner
  .Builder()
  .setNum(10) //any valid integer value
  .build()

//Allows us to construct reason: "Because it is popular on your Channel"
val popularOnPartner = RecommendationReasonPopularOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "New to your channel, or Just added"
val newOnPartner = RecommendationReasonNewOnPartner
  .Builder()
  .build()

//Allows us to construct reason: "Because you watched Star Wars"
val watchedSimilarTitles = RecommendationReasonWatchedSimilarTitles
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .Builder()
  .build()

//Allows us to construct reason: "Recommended for you by ChannelName"
val recommendedForUser = RecommendationReasonRecommendedForUser
  .Builder()
  .build()

val watchAgain = RecommendationReasonWatchAgain
  .Builder()
  .build()

val fromUserWatchList = RecommendationReasonFromUserWatchlist
  .Builder()
  .build()

val userLikedOnPartner = RecommendationReasonUserLikedOnPartner
  .Builder()
  .setTitleName("Movie or TV Show Title")
  .build()

val generic = RecommendationReasonGeneric.Builder().build()

نمایش پنجره زمان

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

val window1 = DisplayTimeWindow
  .Builder()
  .setStartTimeStampMillis(now()+ 1.days.toMillis())
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val window2 = DisplayTimeWindow
  .Builder()
  .setEndTimeStampMillis(now()+ 30.days.toMillis())

val availabilityTimeWindows: List<DisplayTimeWindow> = listof(window1,window2)

DataFeedElementId

اگر کاتالوگ رسانه یا فید اقدام رسانه خود را با Google TV ادغام کرده‌اید، نیازی به ایجاد موجودیت‌های جداگانه برای فیلم یا نمایش تلویزیونی ندارید و در عوض می‌توانید یک نهاد MediaActionFeed ایجاد کنید که شامل قسمت مورد نیاز DataFeedElementId است. این شناسه باید منحصر به فرد باشد و باید با شناسه موجود در فید اقدام رسانه مطابقت داشته باشد، زیرا به شناسایی محتوای فید دریافت شده و انجام جستجوی محتوای رسانه کمک می کند.

val id = "dataFeedEleemntId"

MovieEntity

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


val movieEntity = MovieEntity.Builder()
  .setName("Movie name")
  .setDescription("A sentence describing movie.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  // Suppose the duration is 2 hours, it is 72000000 in milliseconds
  .setDurationMills(72000000)
  .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);
//Suppose release date is 11-02-2025
val releaseDate  = 1739233800000L
val movieEntity = MovieEntity.Builder()
  ...
  .addGenres(genres)
  .setReleaseDateEpochMillis(releaseDate)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .build()

TvShowEntity

در اینجا یک مثال از ایجاد یک TvShowEntity با تمام فیلدهای لازم آورده شده است:

val tvShowEntity = TvShowEntity.Builder()
  .setName("Show title")
  .setDescription("A sentence describing TV Show.")
  .addPlatformSpecificPlaybackUri(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .build();

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

val genres = Arrays.asList("Action", "Science fiction");
val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build();
val price = Price.Builder()
  .setCurrentPrice("$14.99")
  .setStrikethroughPrice("$16.99")
  .build();
val contentRatings = Arrays.asList(rating1);
val seasonCount = 5;
val tvShowEntity = TvShowEntity.Builder()
  ...
  .addGenres(genres)
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addAllAvailabilityTimeWindows(availabilityTimeWindows)
  .setSeasonCount(seasonCount)
  .setPrice(price)
  .build()

MediaActionFeedEntity

در اینجا مثالی از ایجاد MediaActionFeedEntity با تمام فیلدهای مورد نیاز آورده شده است:


val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setDataFeedElementId(id)
  .build()

به صورت اختیاری داده‌های اضافی مانند توضیحات، دلیل توصیه و پنجره زمانی نمایش را ارائه دهید، که ممکن است توسط Google TV برای نمایش‌های پیشرفته یا اهداف فیلتر استفاده شود.

val mediaActionFeedEntity = MediaActionFeedEntity.Builder()
  .setName("Movie name or TV Show name")
  .setDescription("A sentence describing an entity")
  .setRecommendationReason(topOnPartner or watchedSimilarTitles)
  .addPosterImages(images)
  .build()

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