دمج الاقتراحات على الجهاز فقط باستخدام حزمة Engage SDK

يتضمّن هذا الدليل تعليمات للمطوّرين حول كيفية دمج محتوى الفيديو المقترَح باستخدام Engage SDK لتوفير تجارب اقتراحات المحتوى على مساحات عرض Google، مثل التلفزيون والأجهزة الجوّالة والأجهزة اللوحية.

تستفيد الاقتراحات من مجموعة الاقتراحات لعرض الأفلام والبرامج التلفزيونية من تطبيقات متعددة في مجموعة واحدة ضمن واجهة المستخدم. يمكن لكل شريك مطوّر بث 25 عنصرًا كحدّ أقصى في كل مجموعة اقتراحات، ويمكن أن يكون هناك 7 مجموعات اقتراحات كحدّ أقصى لكل طلب.

لإرسال اقتراحات غير مخصّصة مباشرةً من خوادم الخلفية بدلاً من تطبيق بث تلفزيوني، يُرجى الاطّلاع على دمج الاقتراحات باستخدام REST API.

العمل التحضيري

أكمِل تعليمات العمل التمهيدي في دليل البدء.

  1. تنفيذ عملية النشر على خدمة تعمل في المقدّمة
  2. نشر بيانات الاقتراحات مرة واحدة يوميًا كحد أقصى، ويتم تفعيل ذلك من خلال أي مما يلي:
    • أول تسجيل دخول للمستخدم في اليوم (أو)
    • عندما يبدأ المستخدم التفاعل مع التطبيق

التكامل

ينشر "AppEngagePublishClient" مجموعة الاقتراحات. استخدِم طريقة publishRecommendationClusters لنشر عنصر اقتراحات.

تأكَّد من إعداد العميل والتحقّق من توفّر الخدمة كما هو موضّح في دليل البدء.

client.publishRecommendationClusters(recommendationRequest)

جارٍ إدراج مجموعات الاقتراحات أو تعديلها

المجموعات العنقودية هي تجميع منطقي للكيانات. توضّح أمثلة الرموز البرمجية التالية كيفية إنشاء المجموعات العنقودية استنادًا إلى تفضيلاتك وكيفية إنشاء طلب نشر وإدراج جميع المجموعات العنقودية أو تعديلها.

يحدّد RecommendationClusterType كيفية عرض المجموعة.

// cluster for popular movies
val recommendationCluster1 = RecommendationCluster
  .Builder()
  .addEntity(movie1)
  .addEntity(movie2)
  .addEntity(movie3)
  .addEntity(movie4)
  .addEntity(tvShow)
  // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Movies")
  .build()

// cluster for live TV programs
val recommendationCluster2 = RecommendationCluster
  .Builder()
  .addEntity(liveTvProgramEntity1)
  .addEntity(liveTvProgramEntity2)
  .addEntity(liveTvProgramEntity3)
  .addEntity(liveTvProgramEntity4)
  .addEntity(liveTvProgramEntity5)
 // This cluster is meant to be used as an individual provider row
  .setRecommendationClusterType(TYPE_PROVIDER_ROW)
  .setTitle("Popular Live TV Programs")
  .build()

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

عندما تتلقّى الخدمة الطلب، يتم تنفيذ الإجراءات التالية ضمن معاملة واحدة:

  • تتم إزالة بيانات RecommendationsCluster الحالية من الشريك المطوّر.
  • يتم تحليل البيانات من الطلب وتخزينها في RecommendationsCluster المعدَّل. في حال حدوث خطأ، يتم رفض الطلب بالكامل ويتم الاحتفاظ بالحالة الحالية.

المزامنة على جميع الأجهزة

يتحكّم الإعداد SyncAcrossDevices في ما إذا كانت بيانات مجموعة الاقتراحات الخاصة بالمستخدم تتم مشاركتها مع Google TV وتكون متاحة على جميع أجهزته، مثل التلفزيون والهاتف والأجهزة اللوحية. لكي يعمل الاقتراح، يجب ضبطه على "صحيح".

يجب أن يوفّر تطبيق الوسائط إعدادًا واضحًا لتفعيل ميزة المزامنة على جميع الأجهزة أو إيقافها. اشرح المزايا للمستخدم واحفظ خياراته المفضّلة مرة واحدة وطبِّقها في طلب "publishRecommendations" وفقًا لذلك. للاستفادة إلى أقصى حدّ من ميزة العمل على عدة أجهزة، يُرجى التأكّد من أنّ التطبيق يحصل على موافقة المستخدم ويسمح لـ "SyncAcrossDevices" بـ "true".

حذف بيانات Engage

لحذف بيانات مستخدم يدويًا من خادم Google TV قبل فترة الاحتفاظ بالبيانات العادية التي تبلغ 60 يومًا، استخدِم طريقة client.deleteClusters(). عند تلقّي الطلب، تحذف الخدمة جميع بيانات Engage الحالية لملف الحساب الشخصي أو للحساب بأكمله.

يحدّد التعداد 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(
  DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setDeleteReason(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(
  DeleteClustersRequest.Builder()
    .setAccountProfile(accountProfile)
    .setDeleteReason(DeleteReason.DELETE_REASON_LOSS_OF_CONSENT)
    .build()
)

إنشاء كيانات

حدّدت حزمة تطوير البرامج (SDK) كيانات مختلفة لتمثيل كل نوع عنصر. تتوفّر العناصر التالية لمجموعة الاقتراحات:

  1. MediaActionFeedEntity
  2. MovieEntity
  3. TvShowEntity
  4. LiveTvChannelEntity
  5. LiveTvProgramEntity

تقديم الأوصاف

أضِف وصفًا قصيرًا لكل كيان، وسيظهر هذا الوصف عندما يمرّر المستخدمون مؤشر الماوس فوق الكيان، ما يوفّر لهم تفاصيل إضافية.

نص الحث على اتخاذ إجراء

أدخِل نصًا اختياريًا لعبارة الحث على اتخاذ إجراء لكل كيان. سيتم عرض هذا النص للمستخدم لتشجيعه على التفاعل.

العلامات

يمكنك تقديم قائمة بالعلامات لكل كيان. يمكن استخدام العلامات للتصنيف والفلترة.

معرّفات الموارد المنتظمة (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 = RatingSystem
  .Builder()
  .setAgencyName("MPAA")
  .setRating("PG-13")
  .build()

صور الملصقات

تتطلّب صور الملصقات معرّف موارد منتظم (URI) وأبعادًا بالبكسل (الارتفاع والعرض). استهدِف أشكال الأجهزة المختلفة من خلال تقديم صور ملصقات متعددة، ولكن تأكَّد من أنّ جميع الصور تحافظ على نسبة عرض إلى ارتفاع تبلغ 16:9 وحد أدنى للارتفاع يبلغ 200 بكسل لعرض عنصر "الاقتراحات" بشكل صحيح، خاصةً ضمن مساحة الترفيه من Google. قد لا يتم عرض الصور التي يقل ارتفاعها عن 200 بكسل.

val image1 = Image.Builder()
  .setImageUri(Uri.parse("http://www.example.com/entity_image1.png"))
  .setImageHeightInPixel(300)
  .setImageWidthInPixel(169)
  .build()

val image2 = 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
  .Builder()
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .addSimilarWatchedTitleName("Movie or TV Show Title")
  .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 userLikedTitle = RecommendationReasonUserLikedTitle
  .Builder()
  .setLikedTitleName("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())
  .build()

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

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

DataFeedElementId

إذا كنت قد دمجت كتالوج الوسائط أو خلاصة إجراءات الوسائط مع Google TV، لن تحتاج إلى إنشاء كيانات منفصلة للأفلام أو البرامج التلفزيونية، بل يمكنك بدلاً من ذلك إنشاء MediaActionFeedEntity يتضمّن الحقل المطلوب DataFeedElementId. يجب أن يكون هذا المعرّف فريدًا وأن يتطابق مع المعرّف في خلاصة &quot;الإجراءات المتعلّقة بالوسائط&quot; لأنّه يساعد في تحديد محتوى الخلاصة الذي تم استيراده والبحث عن محتوى الوسائط.

val id = "dataFeedElementId"

MovieEntity

في ما يلي مثال على إنشاء MovieEntity مع جميع الحقول المطلوبة:

val movieEntity = MovieEntity.Builder()
  .setName("Movie name")
  .setDescription("A sentence describing movie.")
  .addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
  .addPosterImages(images)
  // Suppose the duration is 2 hours, it is 72000000 in milliseconds
  .setDurationMillis(72000000)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .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.")
  .addPlatformSpecificPlaybackUris(platformSpecificPlaybackUris)
  .addPosterImages(images)
  .setCallToActionText("Watch Now")
  .addTag("Drama")
  .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)
  .setCallToActionText("Watch Now")
  .addTag("Action")
  .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()

LiveTvChannelEntity

يمثّل هذا الرمز قناة بث تلفزيوني مباشر. في ما يلي مثال على إنشاء LiveTvChannelEntity مع جميع الحقول المطلوبة:

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  .setName("Channel Name")
  // ID of the live TV channel
  .setEntityId("https://www.example.com/channel/12345")
  .setDescription("A sentence describing this live TV channel.")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUris(channelPlaybackUris)
  .setLogoImage(logoImage)
  .setCallToActionText("Watch Now")
  .addTag("News")
  .build()

يمكنك تقديم بيانات إضافية، مثل تقييمات المحتوى أو سبب الاقتراح.

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)

val liveTvChannelEntity = LiveTvChannelEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .setRecommendationReason(topOnPartner)
  .build()

LiveTvProgramEntity

تمثّل هذه البطاقة برنامجًا تلفزيونيًا مباشرًا يتم بثّه أو من المقرّر بثّه على قناة بث تلفزيوني مباشر. في ما يلي مثال على إنشاء LiveTvProgramEntity مع جميع الحقول المطلوبة:

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  // First set the channel information
  .setChannelName("Channel Name")
  .setChannelId("https://www.example.com/channel/12345")
  // channel playback uri must contain at least PlatformType.TYPE_ANDROID_TV
  .addPlatformSpecificPlaybackUris(channelPlaybackUris)
  .setChannelLogoImage(channelLogoImage)
  // Then set the program or card specific information.
  .setName("Program Name")
  .setEntityId("https://www.example.com/schedule/123")
  .setDescription("Program Description")
  .addAvailabilityTimeWindow(
      DisplayTimeWindow.Builder()
        .setStartTimestampMillis(1756713600000L) // 2025-09-01T07:30:00+0000
        .setEndTimestampMillis(1756715400000L) // 2025-09-01T08:00:00+0000
        .build()
  )
  .addPosterImage(programImage)
  .setCallToActionText("Watch Now")
  .addTag("Sports")
  .build()

يمكنك تقديم بيانات إضافية، مثل تقييمات المحتوى أو الأنواع أو سبب الاقتراح.

val rating1 = RatingSystem.Builder()
  .setAgencyName("MPAA")
  .setRating("pg-13")
  .build()
val contentRatings = Arrays.asList(rating1)
val genres = Arrays.asList("Action", "Science fiction")

val liveTvProgramEntity = LiveTvProgramEntity.Builder()
  ...
  .addContentRatings(contentRatings)
  .addGenres(genres)
  .setRecommendationReason(topOnPartner)
  .build()