इस गाइड में, डेवलपर के लिए निर्देश दिए गए हैं. इन निर्देशों की मदद से, वे Engage SDK का इस्तेमाल करके, सुझाए गए वीडियो कॉन्टेंट को इंटिग्रेट कर सकते हैं. इससे, उन्हें टीवी, मोबाइल, और टैबलेट जैसे Google के सभी प्लैटफ़ॉर्म पर सुझाव दिखाने की सुविधा मिलती है.
सुझाव देने की सुविधा, सुझाव क्लस्टर का इस्तेमाल करके, एक ही यूज़र इंटरफ़ेस (यूआई) ग्रुपिंग में कई ऐप्लिकेशन की फ़िल्मों और टीवी शो के सुझाव दिखाती है. हर डेवलपर पार्टनर, सुझावों के हर क्लस्टर में ज़्यादा से ज़्यादा 25 इकाइयां ब्रॉडकास्ट कर सकता है. साथ ही, हर अनुरोध में सुझावों के ज़्यादा से ज़्यादा सात क्लस्टर हो सकते हैं.
सेशन की तैयारी
शुरू करने से पहले, नीचे दिया गया तरीका अपनाएं. 1. पुष्टि करें कि आपका ऐप्लिकेशन, इस इंटिग्रेशन के लिए एपीआई लेवल 19 या उसके बाद के लेवल को टारगेट करता है.
अपने ऐप्लिकेशन में
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 }
AndroidManifest.xml
फ़ाइल में, Engage सेवा के एनवायरमेंट को प्रोडक्शन पर सेट करें.मोबाइल APK के लिए
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
For tv apk
<meta-data android:name="com.google.android.engage.service.ENV" android:value="PRODUCTION"> </meta-data>
फ़ोरग्राउंड सेवा पर पब्लिश करने की सुविधा चालू करें.
सुझावों का डेटा, दिन में ज़्यादा से ज़्यादा एक बार पब्लिश करें. यह डेटा इनमें से किसी एक वजह से ट्रिगर होता है
- उपयोगकर्ता का दिन का पहला लॉगिन. (या)
- जब उपयोगकर्ता ऐप्लिकेशन के साथ इंटरैक्ट करना शुरू करता है.
SDK टूल इंटिग्रेशन
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
का इस्तेमाल करके:
- खाता आईडी: यह एक यूनीक आइडेंटिफ़ायर है, जो आपके ऐप्लिकेशन में उपयोगकर्ता के खाते की जानकारी देता है. यह खाते का असल आईडी या सही तरीके से बदला गया वर्शन हो सकता है.
- प्रोफ़ाइल आईडी (ज़रूरी नहीं): अगर आपका ऐप्लिकेशन एक ही खाते में कई प्रोफ़ाइलों के साथ काम करता है, तो किसी खास उपयोगकर्ता प्रोफ़ाइल के लिए यूनीक आइडेंटिफ़ायर दें.
- स्थानीय भाषा(ज़रूरी नहीं): उपयोगकर्ता की पसंदीदा भाषा की जानकारी दी जा सकती है.
यह फ़ील्ड तब काम का होता है, जब
RecommendationRequest
मेंMediaActionFeedEntity
भेजा जाता है.
// 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 के साथ शेयर किया जाए या नहीं. साथ ही, यह भी कंट्रोल होता है कि यह डेटा, टीवी, फ़ोन, टैबलेट जैसे उनके सभी डिवाइसों पर उपलब्ध हो या नहीं. सुझाव काम करने के लिए, इसे 'सही है' पर सेट करना ज़रूरी है.
सहमति लेना
मीडिया ऐप्लिकेशन में, अलग-अलग डिवाइसों के बीच सिंक करने की सुविधा को चालू या बंद करने के लिए, साफ़ तौर पर सेटिंग उपलब्ध होनी चाहिए. उपयोगकर्ता को इसके फ़ायदे बताएं और उपयोगकर्ता की प्राथमिकता को एक बार सेव करें. इसके बाद, publishRecommendations
अनुरोध में इसे लागू करें. क्रॉस-डिवाइस की सुविधा का ज़्यादा से ज़्यादा फ़ायदा पाने के लिए, पुष्टि करें कि ऐप्लिकेशन के पास उपयोगकर्ता की सहमति है और SyncAcrossDevices
से true
को चालू किया गया है.
वीडियो डिस्कवरी का डेटा मिटाना
उपयोगकर्ता का डेटा, Google TV के सर्वर से मैन्युअल तरीके से मिटाने के लिए, client.deleteClusters()
तरीके का इस्तेमाल करें. ऐसा, डेटा को 60 दिनों तक सेव रखने की स्टैंडर्ड अवधि से पहले किया जा सकता है. अनुरोध मिलने पर, यह सेवा खाता प्रोफ़ाइल या पूरे खाते के लिए, वीडियो डिस्कवरी से जुड़ा सारा मौजूदा डेटा मिटा देती है.
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 ने हर तरह के आइटम को दिखाने के लिए अलग-अलग इकाइयां तय की हैं. सुझाव क्लस्टर के लिए, ये इकाइयां काम करती हैं:
MediaActionFeedEntity
MovieEntity
TvShowEntity
ब्यौरा
हर इकाई के लिए कम शब्दों में जानकारी दें. यह जानकारी, इकाई पर कर्सर घुमाने पर दिखेगी. इससे उपयोगकर्ताओं को ज़्यादा जानकारी मिलेगी.
प्लैटफ़ॉर्म के हिसाब से playBack यूआरआई
इस्तेमाल किए जा सकने वाले हर प्लैटफ़ॉर्म के लिए, वीडियो चलाने के यूआरआई बनाएं: 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 = new RatingSystem
.Builder()
.setAgencyName("MPAA")
.setRating("PG-13")
.build()
पोस्टर इमेज
पोस्टर इमेज के लिए यूआरआई और पिक्सल डाइमेंशन (ऊंचाई और चौड़ाई) की ज़रूरत होती है. अलग-अलग डिवाइस फ़ॉर्मैट के लिए, एक से ज़्यादा पोस्टर इमेज उपलब्ध कराएं. हालांकि, पक्का करें कि सभी इमेज का आसपेक्ट रेशियो 16:9 हो और उनकी ऊंचाई कम से कम 200 पिक्सल हो, ताकि "सुझाव" इकाई को सही तरीके से दिखाया जा सके. खास तौर पर, Google के Entertainment Space में. हो सकता है कि 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 में वीडियो कॉन्टेंट के सुझावों को इंटिग्रेट कर सकते हैं. इससे उपयोगकर्ताओं को कॉन्टेंट खोजने और उसमें दिलचस्पी लेने में मदद मिलती है. साथ ही, वे अपने सभी डिवाइसों पर कॉन्टेंट देखने का बेहतर और पसंद के मुताबिक अनुभव पाते हैं.