Android TV पर 'देखना जारी रखें' सुविधा को इंटिग्रेट करना

book_path: /distribute/other-docs/_book.yaml project_path: /distribute/other-docs/_project.yaml

इस गाइड में बताया गया है कि Engage SDK का इस्तेमाल करके, Android TV ऐप्लिकेशन में 'देखना जारी रखें' सुविधा को कैसे इंटिग्रेट किया जा सकता है.

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

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

SDK टूल इंटिग्रेशन

ध्यान दें: 'देखना जारी रखें' सुविधा वाला एपीआई, Watch Next API से अलग तरीके से काम करता है. यह सुविधा, एक-एक करके आइटम जोड़ने या हटाने के बजाय, हर बार अपडेट होने पर "देखना जारी रखें" आइटम की पूरी सूची को बदल देती है. इसका मतलब है कि आपको हर बार अपडेट करते समय, वे सभी आइटम भेजने होंगे जिन्हें आपको दिखाना है. 'देखना जारी रखें' लाइन में ज़्यादा से ज़्यादा इकाइयां दिखाएं. हालांकि, इनकी संख्या 10 से ज़्यादा नहीं होनी चाहिए. इसके अलावा, नया एपीआई सूची और आइटम पब्लिश करने के चरणों को एक साथ जोड़ देता है. इससे यह प्रोसेस आसान हो जाती है. ध्यान रखें कि Google TV, आपके भेजे गए सभी आइटम नहीं दिखा सकता. ऐसा इसलिए, क्योंकि यह अलग-अलग ऐप्लिकेशन की सूचियों को एक साथ दिखाता है.

इकाइयां बनाना

एसडीके ने हर आइटम टाइप को दिखाने के लिए अलग-अलग इकाइयां तय की हैं. कंटिन्यूएशन क्लस्टर में ये इकाइयां काम करती हैं:

इन इकाइयों के लिए, प्लैटफ़ॉर्म के हिसाब से यूआरआई और पोस्टर इमेज तय करें.

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

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

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

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

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 = 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", "episode 2", "s1" या "season 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, उपयोगकर्ता की बनाई गई क्लिप को दिखाता है. जैसे, YouTube वीडियो.

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

आपके पास लाइव स्ट्रीमिंग इकाई के लिए, शुरू होने का समय, ब्रॉडकास्टर, ब्रॉडकास्टर आइकॉन या उपलब्धता की समयावधि सेट करने का विकल्प होता है.

एट्रिब्यूट और ज़रूरी शर्तों के बारे में ज़्यादा जानकारी के लिए, एपीआई रेफ़रंस देखें.

जारी रखने वाले क्लस्टर का डेटा उपलब्ध कराना

जारी रखने वाले क्लस्टर को पब्लिश करने की ज़िम्मेदारी AppEngagePublishClient की है. ContinuationCluster ऑब्जेक्ट को पब्लिश करने के लिए, publishContinuationCluste तरीके का इस्तेमाल किया जाता है.

शुरुआती निर्देशों की गाइड में बताए गए तरीके से, क्लाइंट को शुरू करें और सेवा की उपलब्धता की जांच करें.

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

जब सेवा को अनुरोध मिलता है, तो एक लेन-देन में ये कार्रवाइयां होती हैं:

डेवलपर पार्टनर से मिला मौजूदा ContinuationCluster डेटा हटा दिया जाता है.
अनुरोध से मिले डेटा को पार्स करके, अपडेट किए गए ContinuationCluster में सेव किया जाता है.

गड़बड़ी होने पर, पूरे अनुरोध को अस्वीकार कर दिया जाता है और मौजूदा स्थिति बनी रहती है.

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

जारी रखने के लिए क्लस्टर डेटा सिर्फ़ वयस्क खातों के लिए उपलब्ध कराया जाना चाहिए. सिर्फ़ तब पब्लिश करें, जब खाते की प्रोफ़ाइल किसी वयस्क की हो.

अलग-अलग डिवाइसों पर सिंक करने की सुविधा

SyncAcrossDevices फ़्लैग से यह कंट्रोल होता है कि किसी उपयोगकर्ता का ContinuationCluster डेटा, टीवी, फ़ोन, टैबलेट वगैरह जैसे डिवाइसों पर सिंक किया जाए या नहीं. अलग-अलग डिवाइसों पर सिंक करने की सुविधा डिफ़ॉल्ट रूप से बंद होती है.

वैल्यू:

true: वीडियो को वहीं से देखने की सुविधा से जुड़ा डेटा, उपयोगकर्ता के सभी डिवाइसों पर शेयर किया जाता है, ताकि उसे बिना किसी रुकावट के वीडियो देखने का अनुभव मिल सके. हमारा सुझाव है कि आप इस विकल्प को चुनें, ताकि आपको अलग-अलग डिवाइसों पर बेहतर अनुभव मिल सके.
false: Continuation cluster data is restricted to the current device.

सहमति लेना

मीडिया ऐप्लिकेशन में, क्रॉस-डिवाइस सिंक करने की सुविधा को चालू या बंद करने के लिए, साफ़ तौर पर सेटिंग दी जानी चाहिए. उपयोगकर्ता को इसके फ़ायदों के बारे में बताएं. साथ ही, उपयोगकर्ता की प्राथमिकता को एक बार सेव करें और उसे publishContinuationCluster में लागू करें.

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

क्रॉस-डिवाइस सुविधा का ज़्यादा से ज़्यादा फ़ायदा पाने के लिए, पुष्टि करें कि ऐप्लिकेशन को उपयोगकर्ता की सहमति मिली हो. साथ ही, SyncAcrossDevices को true पर सेट करें. इससे कॉन्टेंट को अलग-अलग डिवाइसों पर आसानी से सिंक किया जा सकता है. इससे उपयोगकर्ताओं को बेहतर अनुभव मिलता है और उनकी दिलचस्पी बढ़ती है. उदाहरण के लिए, इस सुविधा को लागू करने वाले पार्टनर को "देखना जारी रखें" पर मिलने वाले क्लिक में 40% की बढ़ोतरी देखने को मिली. ऐसा इसलिए हुआ, क्योंकि उनका कॉन्टेंट कई डिवाइसों पर दिखाया गया था.

वीडियो डिस्कवरी का डेटा मिटाना

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

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


// 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(
    DeleteClustersRequest.Builder()
        .setAccountProfile(AccountProfile())
        .setReason(DeleteReason.DELETE_REASON_USER_LOG_OUT)
        .setSyncAcrossDevices(true)
        .build()
)

टेस्ट करना

पुष्टि करने वाले ऐप्लिकेशन का इस्तेमाल करके, यह पुष्टि करें कि Engage SDK टूल का इंटिग्रेशन सही तरीके से काम कर रहा है.

पब्लिश एपीआई शुरू करने के बाद, पुष्टि करें कि आपका डेटा सही तरीके से पब्लिश किया जा रहा है. इसके लिए, पुष्टि करने वाले ऐप्लिकेशन की जांच करें. आपका कंटिन्यूएशन क्लस्टर, ऐप्लिकेशन के इंटरफ़ेस में एक अलग लाइन के तौर पर दिखना चाहिए.

अपने ऐप्लिकेशन में इन कार्रवाइयों को टेस्ट करें:
- साइन इन करें.
- प्रोफ़ाइलों के बीच स्विच करें(अगर लागू हो).
- वीडियो चलाना शुरू करें, उसे रोकें या होम पेज पर वापस जाएं.
- वीडियो चलाने के दौरान ऐप्लिकेशन बंद करें.
- "देखना जारी रखें" लाइन से कोई आइटम हटाएं (अगर यह सुविधा उपलब्ध है).
हर कार्रवाई के बाद, पुष्टि करें कि आपके ऐप्लिकेशन ने publishContinuationClusters एपीआई शुरू किया हो और डेटा की पुष्टि करने वाले ऐप्लिकेशन में डेटा सही तरीके से दिख रहा हो.
पुष्टि करने वाला ऐप्लिकेशन, सही तरीके से लागू की गई इकाइयों के लिए "सब ठीक है" वाला हरे रंग का सही का निशान दिखाता है.

पहली इमेज. Verification App Success
पुष्टि करने वाला ऐप्लिकेशन, समस्या वाली किसी भी इकाई के बारे में सूचना देगा.

दूसरी इमेज. पुष्टि करने वाले ऐप्लिकेशन के इस्तेमाल से गड़बड़ी
गड़बड़ियों वाली इकाइयों की समस्या हल करने के लिए, टीवी के रिमोट का इस्तेमाल करके पुष्टि करने वाले ऐप्लिकेशन में इकाई को चुनें और उस पर क्लिक करें. आपको खास समस्याएं दिखेंगी. साथ ही, समीक्षा के लिए उन्हें लाल रंग में हाइलाइट किया जाएगा. उदाहरण के लिए, यहां दिया गया इमेज देखें.

तीसरी इमेज. पुष्टि करने वाले ऐप्लिकेशन के इस्तेमाल से गड़बड़ी की जानकारी