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

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

Ambient API का फ़्लो

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

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

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

   ध्यान दें: Ambient API, अनुमति के अनुरोध में state पैरामीटर को शामिल करने की सुविधा देता है. इससे Ambient API को अनुमति मिलने के बाद, नया डिवाइस बनाने का निर्देश भी मिलेगा.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

मीडिया आइटम की सूची बनाने और उन्हें वापस पाने के बारे में ज़्यादा जानकारी के लिए, गाइड देखें.

अगले चरण

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