Engage SDK का इस्तेमाल करके, उपयोगकर्ता के डिवाइस पर सुझावों को इंटिग्रेट करना

इस गाइड में, डेवलपर के लिए निर्देश दिए गए हैं. इनमें बताया गया है कि Engage SDK का इस्तेमाल करके, सुझाए गए वीडियो कॉन्टेंट को कैसे इंटिग्रेट किया जा सकता है. इससे Google के अलग-अलग प्लैटफ़ॉर्म, जैसे कि टीवी, मोबाइल, और टैबलेट पर सुझाव दिखाए जा सकते हैं.

सुझाव दिखाने की सुविधा, सुझाव के क्लस्टर का इस्तेमाल करके, एक ही यूज़र इंटरफ़ेस (यूआई) ग्रुपिंग में कई ऐप्लिकेशन से फ़िल्में और टीवी शो दिखाती है. हर डेवलपर पार्टनर, सुझाव वाले हर क्लस्टर में ज़्यादा से ज़्यादा 25 इकाइयां ब्रॉडकास्ट कर सकता है. साथ ही, हर अनुरोध में सुझाव वाले ज़्यादा से ज़्यादा सात क्लस्टर हो सकते हैं.

टीवी ऐप्लिकेशन के बजाय, सीधे अपने बैकएंड सर्वर से दिलचस्पी के हिसाब से सुझाव भेजने के लिए, REST एपीआई का इस्तेमाल करके सुझावों को इंटिग्रेट करना लेख पढ़ें.

सेशन की तैयारी

शुरुआती निर्देशों की गाइड में, पहले से किए जाने वाले काम से जुड़े निर्देश पूरे करें.

  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 का डेटा मिटाना

डेटा के रखरखाव की 60 दिनों की स्टैंडर्ड अवधि से पहले, Google TV के सर्वर से किसी उपयोगकर्ता का डेटा मैन्युअल तरीके से मिटाने के लिए, client.deleteClusters() तरीके का इस्तेमाल करें. अनुरोध मिलने पर, सेवा खाते की प्रोफ़ाइल या पूरे खाते के लिए, Engage का सारा मौजूदा डेटा मिटा देती है.

DeleteReason enum, डेटा मिटाने की वजह तय करता है. नीचे दिया गया कोड, लॉग आउट करने पर सुझावों को हटा देता है.

// 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

ब्यौरे जोड़ना

हर इकाई के बारे में कम शब्दों में जानकारी दें. यह जानकारी तब दिखेगी, जब उपयोगकर्ता इकाई पर कर्सर घुमाएंगे. इससे उन्हें ज़्यादा जानकारी मिलेगी.

कॉल-टू-ऐक्शन टेक्स्ट

हर इकाई के लिए, कॉल-टू-ऐक्शन टेक्स्ट दें. हालांकि, ऐसा करना ज़रूरी नहीं है. यह टेक्स्ट, उपयोगकर्ता को दिलचस्पी बढ़ाने के लिए दिखाया जाएगा.

टैग

हर इकाई के लिए टैग की सूची दें. हालांकि, यह ज़रूरी नहीं है. टैग का इस्तेमाल, कैटगरी में बांटने और फ़िल्टर करने के लिए किया जा सकता है.

प्लैटफ़ॉर्म के हिसाब से वीडियो चलाने के यूआरआई

Android TV, Android या iOS जैसे हर प्लैटफ़ॉर्म के लिए, वीडियो चलाने वाले यूआरआई बनाएं. इससे सिस्टम को संबंधित प्लैटफ़ॉर्म पर वीडियो चलाने के लिए, सही यूआरआई चुनने में मदद मिलती है.

अगर सभी प्लैटफ़ॉर्म के लिए, वीडियो चलाने के यूआरआई एक जैसे हैं, तो हर प्लैटफ़ॉर्म के लिए इसे दोहराएं.

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

पोस्टर इमेज

पोस्टर इमेज के लिए, यूआरआई और पिक्सल डाइमेंशन (ऊंचाई और चौड़ाई) की ज़रूरत होती है. अलग-अलग डिवाइसों को टारगेट करने के लिए, कई पोस्टर इमेज उपलब्ध कराएं. हालांकि, यह पुष्टि करें कि सभी इमेज का आसपेक्ट रेशियो (लंबाई-चौड़ाई का अनुपात) 16:9 हो और उनकी ऊंचाई कम से कम 200 पिक्सल हो. इससे "सुझाव" वाली इकाई सही तरीके से दिखेगी. खास तौर पर, Google के Entertainment Space में. ऐसा हो सकता है कि 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 शामिल होता है. यह आईडी यूनीक होना चाहिए और मीडिया ऐक्शन फ़ीड में मौजूद आईडी से मैच होना चाहिए. इससे, शामिल किए गए फ़ीड कॉन्टेंट की पहचान करने और मीडिया कॉन्टेंट को खोजने में मदद मिलती है.

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