Ambient API का इस्तेमाल शुरू करना

Ambient API की मदद से, आपके ऐप्लिकेशन को ऐंबियंट डिवाइसों को उपयोगकर्ता के Google Photos खाते से कनेक्ट करने और उनकी चुनी गई फ़ोटो दिखाने की सुविधा मिलती है.

Ambient API फ़्लो

यहां बताया गया है कि Ambient API, किसी डिवाइस को कनेक्ट करने के बाद मीडिया आइटम को वापस पाने और उन्हें दिखाने के लिए कैसे काम करता है:

1. मौजूदा डिवाइस की जांच करें (सुझाया गया): नया डिवाइस बनाने से पहले, हमारा सुझाव है कि आप यह जांच कर लें कि मौजूदा उपयोगकर्ता के लिए कोई डिवाइस पहले से मौजूद है या नहीं. आपके ऐप्लिकेशन को, आपके इंटरनल उपयोगकर्ता और Google से मिले deviceId के बीच मैपिंग बनाए रखनी चाहिए. ऐसा उन सभी डिवाइसों के लिए करना चाहिए जिन्हें वे आपके ऐप्लिकेशन के ज़रिए बनाते हैं. अगर उपयोगकर्ता के लिए deviceId मिलता है, तो ज़रूरत पड़ने पर उसके ऑथराइज़ेशन टोकन को रीफ़्रेश किया जा सकता है.

2. OAuth 2.0 ऑथराइज़ेशन शुरू करें: ऑथराइज़ेशन कोड का अनुरोध करके, टीवी और सीमित इनपुट डिवाइसों के लिए OAuth 2.0 फ़्लो शुरू करें.

   ध्यान दें: Ambient API, आसान तरीके से पुष्टि करने की प्रोसेस को चालू करने के लिए, अनुमति के अनुरोध में state पैरामीटर को शामिल करने की सुविधा देता है.

3. नया डिवाइस बनाना: आपका ऐप्लिकेशन, CreateDevice को कॉल करके और मान्य v4 यूयूआईडी देकर, उपयोगकर्ता के Google Photos खाते में एक डिवाइस बनाता है.

   डिवाइस बन जाने के बाद, एपीआई एक AmbientDevice ऑब्जेक्ट दिखाएगा. इसमें Google की ओर से असाइन किया गया deviceId शामिल होगा. आपके ऐप्लिकेशन के लिए यह ज़रूरी है कि वह इस deviceId को सेव करे और इसे आपके उपयोगकर्ताओं से जोड़े.

4. settingsUri दिखाएं: AmbientDevice ऑब्जेक्ट में settingsUri शामिल होता है. उपयोगकर्ता को यह यूआरआई दिखाएं. आम तौर पर, यह क्यूआर कोड के तौर पर दिखता है. उपयोगकर्ता इसे अपने फ़ोन या टैबलेट से स्कैन कर सकता है. यह यूआरआई, उपयोगकर्ता को Google Photos ऐप्लिकेशन पर ले जाता है. यहां वे मीडिया सोर्स (जैसे, एल्बम) कॉन्फ़िगर कर सकते हैं जिन्हें वे अपने ऐंबियंट डिवाइस पर दिखाना चाहते हैं.

5. mediaSourcesSet के लिए पोल: आपके ऐप्लिकेशन को समय-समय पर GetDevice तरीके को कॉल करना चाहिए. साथ ही, एंबियंट डिवाइस की स्थिति देखने के लिए deviceId देना चाहिए. AmbientDevice के जवाब में mediaSourcesSet फ़ील्ड को मॉनिटर करें. शुरुआत में इसकी वैल्यू false होगी.

   जब उपयोगकर्ता Google Photos ऐप्लिकेशन में मीडिया सोर्स चुन लेगा, तब इस फ़ील्ड की वैल्यू बदलकर true हो जाएगी.

   AmbientDevice के जवाब में, pollInterval के साथ pollingConfig शामिल होता है. आपको इसका इस्तेमाल, पोलिंग की फ़्रीक्वेंसी के लिए दिशा-निर्देश के तौर पर करना चाहिए.

6. मीडिया आइटम वापस पाना: जब mediaSourcesSet 'सही' वैल्यू दिखाता है, तो आपका ऐप्लिकेशन उपयोगकर्ता के चुने गए मीडिया आइटम फ़ेच करना शुरू कर सकता है.

   ListMediaItems तरीके को कॉल करें और deviceId उपलब्ध कराएं. एपीआई, ListMediaItemsResponse दिखाएगा. इसमें AmbientMediaItem ऑब्जेक्ट की सूची होगी. हर AmbientMediaItem में id, createTime, और ज़्यादा मेटाडेटा वाले MediaFile ऑब्जेक्ट जैसी जानकारी शामिल होती है. MediaFile में एक baseUrl होता है. इसका इस्तेमाल करके, किसी मीडिया आइटम के असल बाइट फ़ेच किए जा सकते हैं. baseUrl के अन्य पैरामीटर के बारे में जानने के लिए, मीडिया आइटम की सूची बनाना और उन्हें वापस पाना गाइड देखें.

7. मीडिया आइटम दिखाना: एंबियंट डिवाइस पर मीडिया कॉन्टेंट डाउनलोड करने और दिखाने के लिए, MediaFile से baseUrl का इस्तेमाल करें.

विचार करने योग्य महत्वपूर्ण बातें

डिवाइस की सीमा और मैनेजमेंट:

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

डिवाइसों को बनाने और मैनेज करने की गाइड में ज़्यादा जानकारी दी गई है.

मीडिया आइटम के साथ काम करना:

• मीडिया आइटम का इस्तेमाल: baseUrl का इस्तेमाल करके, मीडिया आइटम के कॉन्टेंट को सही तरीके से फ़ेच और मैनेज करने का तरीका जानें. इसमें ज़रूरी पुष्टि या पैरामीटर शामिल हैं.
• गड़बड़ी ठीक करना: एपीआई कॉल के लिए, गड़बड़ी ठीक करने की बेहतर सुविधा लागू करें. इसमें ये स्थितियां शामिल हैं: डिवाइसों के लिए NOT_FOUND, मीडिया सोर्स सेट न होने पर FAILED_PRECONDITION, और डिवाइसों की सीमाएं पूरी होने पर RESOURCE_EXHAUSTED.

मीडिया आइटम की सूची बनाने और उन्हें वापस पाने से जुड़ी गाइड में ज़्यादा जानकारी दी गई है. इसमें कॉन्टेंट से जुड़ी नीति और फ़िल्टर करने के बारे में जानकारी भी शामिल है.

अगले चरण

• अपना ऐप्लिकेशन कॉन्फ़िगर करें: पुष्टि करें कि आपके पास ज़रूरी क्रेडेंशियल हैं. साथ ही, आपने टीवी और सीमित इनपुट डिवाइसों के लिए OAuth 2.0 के लिए अपना ऐप्लिकेशन कॉन्फ़िगर किया है.
• Ambient API के रेफ़रंस दस्तावेज़ देखें: उपलब्ध सभी तरीकों, अनुरोध और जवाब के पैरामीटर, और गड़बड़ी के कोड के लिए, ज़्यादा जानकारी वाला रेफ़रंस दस्तावेज़ देखें.