Ambient API के लिए अपने ऐप्लिकेशन को कॉन्फ़िगर करें

Ambient API का इस्तेमाल शुरू करने के लिए, Google API Console में एपीआई को चालू करके और OAuth 2.0 क्लाइंट आईडी सेट अप करके, अपना प्रोजेक्ट कॉन्फ़िगर करें. Ambient API, टीवी और सीमित इनपुट वाले डिवाइस के ऐप्लिकेशन के लिए OAuth 2.0 का इस्तेमाल करता है.

आपका ऐप्लिकेशन, Ambient API के उपयोगकर्ता की ओर से Ambient API के साथ इंटरैक्ट करता है. उपयोगकर्ता, OAuth 2.0 प्रोटोकॉल का इस्तेमाल करके, इन एपीआई अनुरोधों को अनुमति देता है.

OAuth 2.0 क्लाइंट आईडी की मदद से, आपके ऐप्लिकेशन के उपयोगकर्ता साइन इन कर सकते हैं, पुष्टि कर सकते हैं, और Ambient API का इस्तेमाल कर सकते हैं. Ambient API, सेवा खातों के साथ काम नहीं करते. इन एपीआई का इस्तेमाल करने के लिए, उपयोगकर्ताओं को किसी मान्य Google खाते में साइन इन करना होगा.

अपने ऐप्लिकेशन को कॉन्फ़िगर करना

सबसे पहले एपीआई को चालू करें. इसके बाद, OAuth 2.0 क्लाइंट आईडी का अनुरोध करें.

एपीआई चालू करना

Ambient API का इस्तेमाल करने से पहले, आपको अपने प्रोजेक्ट में इसे चालू करना होगा.

1. Google API कंसोल पर जाएं.
2. मेन्यू बार से कोई प्रोजेक्ट चुनें या नया प्रोजेक्ट बनाएं.
3. Google Photos का कोई एपीआई खोलने के लिए, नेविगेशन मेन्यू में जाकर, एपीआई और सेवाएं > लाइब्रेरी चुनें.
4. "Ambient API" खोजें. Ambient API चुनें और चालू करें पर क्लिक करें.

OAuth 2.0 क्लाइंट आईडी का अनुरोध करना

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

1. Google API (एपीआई) कंसोल पर जाएं और अपना प्रोजेक्ट चुनें.
2. मेन्यू में, एपीआई और सेवाएं > क्रेडेंशियल चुनें.

3. क्रेडेंशियल पेज पर, क्रेडेंशियल बनाएं > OAuth क्लाइंट आईडी पर क्लिक करें.

   ध्यान दें: नया प्रोजेक्ट सेट अप करते समय, आपसे प्रोजेक्ट की सहमति स्क्रीन को कॉन्फ़िगर करने के लिए कहा जा सकता है.

4. ऐप्लिकेशन का टाइप चुनें. इस उदाहरण में, ऐप्लिकेशन टाइप टीवी और सीमित इनपुट डिवाइस है.

5. अपने OAuth 2.0 क्लाइंट को कोई नाम दें और बनाएं पर क्लिक करें.

6. OAuth क्लाइंट के डायलॉग बॉक्स में दिखने वाली जानकारी में से, ये कॉपी करें:

   • Client-ID
   • क्लाइंट सीक्रेट

आपका ऐप्लिकेशन इन वैल्यू का इस्तेमाल करके, चालू किए गए Google API को ऐक्सेस कर सकता है.

Ambient API को ऐक्सेस करने वाला कोई सार्वजनिक ऐप्लिकेशन लॉन्च करने से पहले, Google को आपके ऐप्लिकेशन की समीक्षा करनी होगी. ऐप्लिकेशन की जांच करने पर, स्क्रीन पर "ऐप्लिकेशन की पुष्टि नहीं की गई है" मैसेज दिखता है. यह मैसेज तब तक दिखता रहेगा, जब तक ऐप्लिकेशन की पुष्टि नहीं हो जाती.

ऐप्लिकेशन को कॉन्फ़िगर करने के बाद, उसे इस्तेमाल किया जा सकता है. यहां दिए गए संसाधनों को एक्सप्लोर करें या Ambient API के लिए, पुष्टि करने के बेहतर तरीके के बारे में पढ़ें.

• डिवाइस बनाना और उन्हें मैनेज करना
• मीडिया आइटम की सूची बनाना और उन्हें वापस लाना

अपना क्लाइंट आईडी बदलना

Google Photos के किसी भी एपीआई की मदद से बनाए गए संसाधनों को सिर्फ़ उस ओरिजनल क्लाइंट आईडी का इस्तेमाल करके ऐक्सेस या उनमें बदलाव किया जा सकता है जिसका इस्तेमाल उन्हें बनाने के लिए किया गया था. उदाहरण के लिए, अगर आपने किसी खास क्लाइंट आईडी के साथ Picker API में session बनाया है और बाद में अपने ऐप्लिकेशन में उस क्लाइंट आईडी को बदल दिया है, तो आपके ऐप्लिकेशन के पास पिछले क्लाइंट आईडी से बनाए गए किसी भी API रिसॉर्स का ऐक्सेस नहीं रहेगा.

ध्यान से प्लान बनाएं और इस्तेमाल किए जा रहे Photos API के लिए सही क्लाइंट आईडी टाइप चुनें. ऐक्सेस से जुड़ी समस्याओं से बचने के लिए, सिर्फ़ ज़रूरत पड़ने पर अपना क्लाइंट आईडी बदलें.

Ambient API के लिए, पुष्टि करने का आसान तरीका

Ambient API की पुष्टि करने के स्टैंडर्ड फ़्लो के लिए, आपके उपयोगकर्ताओं को दो QR कोड स्कैन करने होंगे:

• अपने Google खाते में सबसे पहले साइन इन करने वाला व्यक्ति (अगर उसने पहले से साइन इन नहीं किया है).
• दूसरा, जो उनके Google Photos खाते में बनाए गए नए ऐंबियंट डिवाइस से लिंक होता है. यहां वे डिसप्ले के लिए मीडिया आइटम चुन सकते हैं.

बेहतर फ़्लो की मदद से, अपने उपयोगकर्ताओं को एक ही क्यूआर कोड दिया जा सकता है. इसके लिए, पुष्टि करने के शुरुआती कॉल के साथ state पैरामीटर को पास करना होगा.

सीमित इनपुट डिवाइसों के लिए, OAuth के तहत डिवाइस और उपयोगकर्ता कोड का अनुरोध करते समय, अपने अनुरोध में state पैरामीटर शामिल करें. state पैरामीटर में ये जोड़ें:

पैरामीटर
requestId	string ज़रूरी है. इस अनुरोध के लिए, क्लाइंट से मिला यूनीक आइडेंटिफ़ायर. इसका इस्तेमाल, नेटवर्क के काम न करने पर, संसाधनों के डुप्लीकेट होने की समस्या को कम करने के लिए किया जाता है. यह आईडी, UUID (वर्शन 4) स्ट्रिंग के फ़ॉर्मैट में होना चाहिए. साथ ही, यह इन ज़रूरी शर्तों के मुताबिक होना चाहिए: इसमें उपयोगकर्ता की पहचान से जुड़ी कोई संवेदनशील जानकारी शामिल नहीं होनी चाहिए. इसमें 32 हेक्साडेसिमल वर्ण होने चाहिए. इन्हें पांच ग्रुप में बांटा गया है और हायफ़न लगाकर अलग किया गया है. यह "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (या 8-4-4-4-12) फ़ॉर्मैट में होना चाहिए.
displayName	string ज़रूरी नहीं. इस डिवाइस के लिए, उपयोगकर्ता का तय किया गया डिसप्ले नेम. यह जानकारी, Google Photos ऐप्लिकेशन की सेटिंग में उपयोगकर्ताओं को दिखेगी. हालांकि, इसमें सिर्फ़ इस एपीआई की मदद से बदलाव किया जा सकता है. मान्य डिसप्ले नेम में 1 से 100 वर्ण होने चाहिए.

उदाहरण के लिए, यह कोड ब्लॉक देखें:

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

सही रिस्पॉन्स में user_code और verification_url शामिल होंगे. इन्हें उपयोगकर्ता को दिखाया जाता है. ज़्यादातर मामलों में, इन्हें क्यूआर कोड के तौर पर दिखाया जाता है, ताकि उपयोगकर्ता किसी दूसरे डिवाइस पर वहां जा सके. state पैरामीटर को शामिल करने पर, बाद में Ambient API के साथ createDevice को कॉल करने पर, दूसरे क्यूआर कोड में settingsUri को दिखाने की ज़रूरत नहीं होती. ऐसा इसलिए, क्योंकि OAuth फ़्लो का आखिरी चरण, इस जगह पर अपने-आप रीडायरेक्ट हो जाएगा.

पूरी जानकारी के लिए, हमने ज़्यादा जानकारी दी है. आपके पास हमारे सैंपल ऐप्लिकेशन में मौजूद कोड की समीक्षा करने का भी विकल्प है. इससे, आपको Ambient API के साथ सीमित इनपुट डिवाइसों के लिए, OAuth के हिस्से के तौर पर state पैरामीटर का इस्तेमाल करने का उदाहरण मिलेगा.

पुष्टि करने के आसान तरीके के बारे में जानकारी

Ambient API के लिए, आसानी से इस्तेमाल किए जा सकने वाले OAuth फ़्लो को पूरी तरह से समझने के लिए, TV और सीमित इनपुट वाले डिवाइस के ऐप्लिकेशन के लिए OAuth 2.0 फ़्लो के साथ-साथ, स्टैंडर्ड Ambient API फ़्लो को समझना ज़रूरी है. यहां हर फ़्लो के लिए चरणों के बारे में बताया गया है.

टीवी और सीमित इनपुट वाले डिवाइस के लिए OAuth 2.0:

1. आपका ऐप्लिकेशन, Google के ऑथराइज़ेशन सर्वर को एक अनुरोध भेजता है. इस सर्वर से उन स्कोप की पहचान की जाती है जिन्हें ऐक्सेस करने के लिए आपका ऐप्लिकेशन अनुमति का अनुरोध करेगा.
2. सर्वर, कई तरह की जानकारी के साथ जवाब देता है. इस जानकारी का इस्तेमाल, अगले चरणों में किया जाता है. जैसे, डिवाइस कोड और उपयोगकर्ता कोड.
3. आपने ऐसी जानकारी दिखाई है जिसे उपयोगकर्ता किसी दूसरे डिवाइस पर डालकर, आपके ऐप्लिकेशन को अनुमति दे सकता है.
4. आपका ऐप्लिकेशन, Google के ऑथराइज़ेशन सर्वर से अनुरोध करने लगता है, ताकि यह पता लगाया जा सके कि उपयोगकर्ता ने आपके ऐप्लिकेशन को अनुमति दी है या नहीं.
5. उपयोगकर्ता, बेहतर इनपुट सुविधाओं वाले डिवाइस पर स्विच करता है, वेब ब्राउज़र को लॉन्च करता है, तीसरे चरण में दिखाए गए यूआरएल पर जाता है, और तीसरे चरण में दिखाया गया कोड डालता है. इसके बाद, उपयोगकर्ता आपके ऐप्लिकेशन का ऐक्सेस दे सकता है या अस्वीकार कर सकता है.
6. पोलिंग के अनुरोध के अगले जवाब में वे टोकन शामिल होते हैं जिनकी ज़रूरत आपके ऐप्लिकेशन को, उपयोगकर्ता की ओर से अनुरोधों को अनुमति देने के लिए होती है. (अगर उपयोगकर्ता ने आपके ऐप्लिकेशन का ऐक्सेस देने से मना कर दिया है, तो रिस्पॉन्स में टोकन शामिल नहीं होते.)

Ambient API फ़्लो:

1. मौजूदा OAuth टोकन देखें और टोकन को रीफ़्रेश करें या नए टोकन का अनुरोध करें.
2. OAuth टोकन मिलने के बाद, नया डिवाइस बनाएं.
3. उपयोगकर्ता को settingsUri दिखाएं और डिवाइस को तब तक पोल करें, जब तक कि mediaSourcesSet सही न हो जाए.
4. उपयोगकर्ता settingsUri पर जाता है और वे फ़ोटो चुनता है जिन्हें उसे आपके ऐप्लिकेशन के साथ शेयर करना है.
5. mediaSourcesSet के 'सही' के तौर पर दिखने के बाद, mediaItems की सूची वापस पाएं.
6. अब स्लाइड शो या अन्य ऐंबियंट डिसप्ले शुरू किया जा सकता है.

दोनों फ़्लो में एक चरण शामिल होता है, जिसमें उपयोगकर्ता को यूआरएल दिखाया जाता है और उपयोगकर्ता अपने बेहतर इनपुट डिवाइस पर वहां जाता है. अपने शुरुआती OAuth कॉल में state पैरामीटर को शामिल करके, आपको दिखाए जाने वाले दूसरे यूआरएल से बचा जा सकता है.

ऐसा इसलिए होता है, क्योंकि टीवी और सीमित इनपुट वाले डिवाइस के ऐप्लिकेशन के लिए OAuth 2.0 फ़्लो का आखिरी चरण, आम तौर पर उपयोगकर्ता को उस पेज पर रीडायरेक्ट करता है जिस पर लिखा होता है कि "अब आपके पास अपने डिवाइस पर वापस जाने का विकल्प है." स्टेट पैरामीटर को शामिल करने पर, फ़्लो के आखिरी चरण में अब आपको settingsUri पर रीडायरेक्ट करने की कोशिश की जाएगी. आपके ऐप्लिकेशन को अब भी OAuth टोकन मिलेगा. आपको उसी requestId का इस्तेमाल करके, createDevice को कॉल करने के लिए इस टोकन का इस्तेमाल करना चाहिए. जब उसी आईडी वाला डिवाइस बन जाएगा, तो Photos ऐप्लिकेशन में, रिच डिवाइस पर उपयोगकर्ता को सही पेज पर रीडायरेक्ट करने के लिए, OAuth का शुरुआती फ़्लो काम करेगा.

इन बातों का ध्यान रखें:

• पुष्टि करने में कोई समस्या आने पर, settingsUri दिखाना अब भी एक अच्छा तरीका है.
• हालांकि, settingsUri का इस्तेमाल अब भी अन्य मामलों में किया जा सकता है. जैसे, जब कोई उपयोगकर्ता अपनी चुनी गई फ़ोटो अपडेट करना चाहता है.