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

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

Ambient API फ़्लो

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

अगले चरण