iframe और क्वेरी पैरामीटर की जानकारी

Classroom ऐड-ऑन को iframe में लोड किया जाता है, ताकि असली उपयोगकर्ता को बेहतर और सुविधाजनक अनुभव मिल सके. iframe के चार अलग-अलग टाइप होते हैं. हर iframe के मकसद और उसके दिखने के तरीके की खास जानकारी के लिए, उपयोगकर्ता के सफ़र की डायरेक्ट्री में iframe पेज देखें.

iframe की सुरक्षा से जुड़े दिशा-निर्देश

पार्टनर को अपने iframe को सुरक्षित रखने के लिए, इंडस्ट्री के सबसे सही तरीकों का पालन करना चाहिए. iframe को सुरक्षित रखने के लिए, हमारी सुरक्षा टीम इन बातों का सुझाव देती है:

• एचटीटीपीएस ज़रूरी है. हमारा सुझाव है कि आप TLS 1.2 या इसके बाद के वर्शन का इस्तेमाल करें और एचटीटीपी स्ट्रिक्ट ट्रांसपोर्ट सिक्योरिटी को चालू करें. स्ट्रिक्ट ट्रांसपोर्ट सिक्योरिटी के बारे में MDN का यह लेख पढ़ें.

• कॉन्टेंट की सुरक्षा के लिए सख्त नीति चालू करें. OWASP का यह लेख और इससे जुड़ा कॉन्टेंट सुरक्षा नीति का MDN लेख देखें.

• सुरक्षित कुकी एट्रिब्यूट चालू करें. HttpOnly एट्रिब्यूट और इससे जुड़ा कुकी MDN लेख देखें.

iFrame यूआरआई कॉन्फ़िगरेशन

अटैचमेंट सेटअप यूआरआई, अटैचमेंट डिस्कवरी iframe को लोड करता है. साथ ही, यह वह जगह है जहां शिक्षक, Classroom पोस्ट पर ऐड-ऑन अटैचमेंट बनाने का फ़्लो शुरू करते हैं. इसे Google Cloud प्रोजेक्ट कंसोल में सेट किया जा सकता है. इस यूआरआई को अपने Google Cloud प्रोजेक्ट के एपीआई और सेवा > Google Workspace Marketplace SDK > ऐप्लिकेशन कॉन्फ़िगरेशन पेज पर सेट करें.

अटैचमेंट के लिए अनुमति वाले यूआरआई प्रीफ़िक्स का इस्तेमाल, *.addOnAttachments.create और *.addOnAttachments.patch तरीकों का इस्तेमाल करके, AddOnAttachment में सेट किए गए यूआरआई की पुष्टि करने के लिए किया जाता है. पुष्टि करने के लिए, लिटरल स्ट्रिंग प्रीफ़िक्स मैच का इस्तेमाल किया जाता है. फ़िलहाल, इसमें वाइल्ड कार्ड का इस्तेमाल नहीं किया जा सकता.

क्वेरी पैरामीटर

iframe, ऐड-ऑन को क्वेरी पैरामीटर के रूप में ज़रूरी जानकारी भेजते हैं. पैरामीटर की दो कैटगरी होती हैं: अटैचमेंट से जुड़े और साइन-इन से जुड़े पैरामीटर.

अटैचमेंट से जुड़े पैरामीटर

अटैचमेंट से जुड़े पैरामीटर, ऐड-ऑन को कोर्स, असाइनमेंट, ऐड-ऑन अटैचमेंट, छात्र/छात्रा के सबमिट करने की प्रक्रिया, और अनुमति देने वाले टोकन के बारे में जानकारी देते हैं.

कोर्स आईडी

courseId वैल्यू, कोर्स का आइडेंटिफ़ायर होती है.

यह सभी iframe के साथ शामिल होता है.

आइटम का आईडी

itemId वैल्यू, Announcement का आइडेंटिफ़ायर है,

CourseWork या CourseWorkMaterial पर यह अटैचमेंट अटैच किया गया है.

यह सभी iframe में शामिल होता है.

आइटम का प्रकार

itemType वैल्यू से उस रिसॉर्स टाइप की पहचान होती है जिस पर यह

अटैचमेंट अटैच किया गया है. पास की गई स्ट्रिंग वैल्यू, "announcements", "courseWork" या "courseWorkMaterials" में से कोई एक हो.

यह सभी iframe में शामिल होता है.

अटैचमेंट आईडी

attachmentId वैल्यू, अटैचमेंट का आइडेंटिफ़ायर होती है.

teacherViewUri, studentViewUri, और studentWorkReviewUri iframes के साथ शामिल है.

सबमिशन आईडी

submissionId वैल्यू, छात्र के काम का आइडेंटिफ़ायर है. हालांकि, किसी खास असाइनमेंट में छात्र के काम की पहचान करने के लिए, attachmentId के साथ इसका इस्तेमाल किया जाना चाहिए.

studentWorkReviewUri के साथ शामिल है.

ऐड-ऑन टोकन

addOnToken वैल्यू, अनुमति देने वाला टोकन होता है. इसका इस्तेमाल

addOnAttachments.create कॉल का इस्तेमाल करके ऐड-ऑन बनाएं.

यह अटैचमेंट डिस्कवरी iframe और लिंक अपग्रेड iframe के साथ शामिल होता है.

अपग्रेड किया जाने वाला यूआरएल

urlToUpgrade वैल्यू की मौजूदगी का मतलब है कि

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

यह लिंक अपग्रेड iframe के साथ शामिल होता है.

साइन-इन से जुड़े पैरामीटर

login_hint क्वेरी पैरामीटर, ऐड-ऑन के वेब पेज पर आने वाले Classroom उपयोगकर्ता के बारे में जानकारी देता है. यह क्वेरी पैरामीटर, iframe src यूआरएल पर दिया गया है. यह तब भेजा जाता है, जब उपयोगकर्ता ने पहले आपके ऐड-ऑन का इस्तेमाल किया हो. इससे, असली उपयोगकर्ता को साइन-इन करने में आसानी होती है. आपको ऐड-ऑन लागू करते समय, इस क्वेरी पैरामीटर को मैनेज करना होगा.

लॉगिन संकेत

login_hint, उपयोगकर्ता के Google खाते का यूनीक आइडेंटिफ़ायर है

खाता पर टैप करें। जब उपयोगकर्ता आपके ऐड-ऑन में पहली बार लॉग इन करता है, तो उसी उपयोगकर्ता के बाद के हर ऐड-ऑन विज़िट पर, login_hint पैरामीटर पास किया जाता है.

login_hint पैरामीटर का इस्तेमाल दो तरह से किया जा सकता है:

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

यह सभी iframe में शामिल होता है.

अटैचमेंट डिस्कवरी iframe

अटैचमेंट डिस्कवरी की स्थिति का उदाहरण

1. Classroom का कोई ऐड-ऑन, Google Workspace के मार्केटप्लेस में https://example.com/addon के अटैचमेंट डिस्कवरी यूआरआई के साथ रजिस्टर किया गया है.
2. कोई शिक्षक इस ऐड-ऑन को इंस्टॉल करता है और अपने किसी कोर्स में नई सूचना, असाइनमेंट या कॉन्टेंट बनाता है. उदाहरण के लिए, itemId=234, itemType=courseWork, और courseId=123.
3. उस आइटम को कॉन्फ़िगर करते समय, शिक्षक नए इंस्टॉल किए गए ऐड-ऑन को अटैचमेंट के तौर पर चुनता है.
4. Classroom, https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 पर सेट किए गए src यूआरएल का इस्तेमाल करके, एक iframe बनाता है.
   1. अटैचमेंट चुनने के लिए, शिक्षक iframe में काम करता है.
5. अटैचमेंट चुनने पर, ऐड-ऑन Classroom को postMessage भेजता है, ताकि iframe बंद हो सके.

TrainerViewUri और छात्रViewUri iframes

studentWorkReviewUri iframe

लिंक अपग्रेड iframe

लिंक अपग्रेड करने के उदाहरण

1. Classroom ऐड-ऑन, https://example.com/upgrade के लिंक अपग्रेड यूआरआई के साथ रजिस्टर किया गया है. आपने लिंक अटैचमेंट के लिए, यहां दिए गए होस्ट और पाथ प्रीफ़िक्स पैटर्न दिए हैं. इन पैटर्न को अपनाकर, Classroom को ऐड-ऑन अटैचमेंट में अपग्रेड करना चाहिए:
   • होस्ट example.com है और पाथ का प्रीफ़िक्स /quiz है.
2. कोई शिक्षक अपने किसी कोर्स में नई सूचना, असाइनमेंट या कॉन्टेंट बनाता है. उदाहरण के लिए, itemId=234, itemType=courseWork, और courseId=123.
3. कोई शिक्षक, लिंक किए गए अटैचमेंट के डायलॉग बॉक्स में https://example.com/quiz/5678 लिंक चिपकाता है. यह लिंक, आपके दिए गए यूआरएल पैटर्न से मेल खाता है. इसके बाद, शिक्षक को लिंक को ऐड-ऑन अटैचमेंट में अपग्रेड करने के लिए कहा जाता है.

4. Classroom, लिंक अपग्रेड करने के लिए https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 पर सेट किए गए यूआरएल के साथ iframe लॉन्च करता है.

5. iframe पर पास किए गए क्वेरी पैरामीटर का आकलन किया जाता है और CreateAddOnAttachment एंडपॉइंट को कॉल किया जाता है. ध्यान दें कि iframe पर पास किए जाने पर, urlToUpgrade क्वेरी पैरामीटर को यूआरआई कोड में बदल दिया जाता है. पैरामीटर को उसके ओरिजनल फ़ॉर्म में पाने के लिए, आपको उसे डिकोड करना होगा. उदाहरण के लिए, JavaScript decodeURIComponent() फ़ंक्शन ऑफ़र करता है.

6. लिंक की मदद से ऐड-ऑन अटैचमेंट बनाने के बाद, iframe को बंद करने के लिए, Classroom को postMessage भेजा जाता है.

iframe बंद करना

लर्निंग टूल से iframe को बंद किया जा सकता है. इसके लिए, {type: 'Classroom', action: 'closeIframe'} पेलोड के साथ postMessage भेजें. Classroom, सिर्फ़ उस ओरिजनल यूआरआई के होस्ट_नेम+पोर्ट से यह postMessage स्वीकार करता है जिसे खोला गया था.

<button id="close">Send message to close iframe</button>
<script>
  document.querySelector('#close')
    .addEventListener('click', () => {
        window.parent.postMessage({
            type: 'Classroom',
            action: 'closeIframe',
        }, '*');
    });
</script>

iframe से iframe को बंद करना

postMessage इवेंट भेजने वाले पेज का डोमेन+पोर्ट, iframe को लॉन्च करने के लिए इस्तेमाल किए गए यूआरआई के डोमेन+पोर्ट से मेल खाना चाहिए. ऐसा न होने पर, मैसेज को अनदेखा कर दिया जाता है. इस समस्या को हल करने के लिए, उपयोगकर्ताओं को ओरिजनल डोमेन पर मौजूद उस पेज पर रीडायरेक्ट करें जो सिर्फ़ postMessage इवेंट भेजता है.

नए टैब से iframe बंद करना

क्रॉस-डोमेन सुरक्षा की सुविधाएं, इस सुविधा को काम करने से रोकती हैं. इस समस्या को हल करने के लिए, iframe और नए टैब के बीच के कम्यूनिकेशन को खुद मैनेज करें. साथ ही, आखिर में iframe को postMessage इवेंट बंद करने की अनुमति दें. ध्यान दें, "पार्टनर के नाम में खोलें" हाइपरलिंक को हटाया जा रहा है, ताकि उपयोगकर्ता आने वाले समय में इस तरह से टैब न बनाएं.

पाबंदियां

सभी iframe, इन सैंडबॉक्स एट्रिब्यूट के साथ खुलते हैं:

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

और ये सुविधा से जुड़ी नीति

• allow="microphone *"

तीसरे पक्ष की कुकी ब्लॉक करना

ध्यान रखें कि तीसरे पक्ष की कुकी ब्लॉक करने की सुविधा से, iframe में साइन इन किए गए सेशन को बनाए रखना मुश्किल हो जाता है. अलग-अलग ब्राउज़र में कुकी ब्लॉक करने की मौजूदा स्थिति के बारे में जानने के लिए https://www.cookiestatus.com पर जाएं. हालांकि, यह समस्या सिर्फ़ Google Classroom के ऐड-ऑन के लिए नहीं है. इसका असर उन सभी वेबसाइटों पर पड़ता है जो तीसरे पक्ष के iframe का इस्तेमाल करती हैं. हमारे कई पार्टनर को पहले ही इस समस्या का सामना करना पड़ा है.

समस्या को हल करने के कुछ सामान्य तरीके ये हैं:

• पहले-पक्ष के कॉन्टेक्स्ट में कुकी बनाने के लिए, नया टैब खोलें. कुछ ब्राउज़र तीसरे पक्ष के मामले में, पहले-पक्ष के कॉन्टेक्स्ट में बनाई गई कुकी को ऐक्सेस देते हैं.
• उपयोगकर्ता से तीसरे पक्ष की कुकी के इस्तेमाल की अनुमति मांगें. ऐसा हो सकता है कि सभी उपयोगकर्ताओं के लिए, यह सुविधा हमेशा उपलब्ध न हो.
• ऐसे सिंगल-पेज वेब ऐप्लिकेशन डिज़ाइन करें जो कुकी पर निर्भर न हों.

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

यूआरएल रेगुलर एक्सप्रेशन का इस्तेमाल करके ऐड-ऑन खोजने की सुविधा चालू करें

शिक्षक अक्सर लिंक अटैच करके असाइनमेंट बनाते हैं. ऐड-ऑन के इस्तेमाल को बढ़ावा देने के लिए, आपके पास ऐसे रेगुलर एक्सप्रेशन तय करने का विकल्प होता है जो आपके ऐड-ऑन में ऐक्सेस किए जा सकने वाले संसाधनों के यूआरएल से मेल खाते हैं. आपके रेगुलर एक्सप्रेशन से मेल खाने वाले लिंक को अटैच करने वाले शिक्षक को, खारिज किया जा सकने वाला एक डायलॉग दिखता है, जो उन्हें ऐड-ऑन आज़माने के लिए कहता है. उन्हें यह डायलॉग सिर्फ़ तब दिखता है, जब उनके खाते के लिए ऐड-ऑन पहले से इंस्टॉल हो.

अगर आपको शिक्षकों को यह सुविधा देनी है, तो अपने Google संपर्कों के लिए सही रेगुलर एक्सप्रेशन दें. अगर आपने जो रेगुलर एक्सप्रेशन दिए हैं वे बहुत बड़े हैं या किसी दूसरे ऐड-ऑन से मेल खाते हैं, तो उनमें बदलाव करके उन्हें ज़्यादा सीमित या अलग बनाया जा सकता है.

पहली इमेज. शिक्षक, किसी नए असाइनमेंट में लिंक अटैचमेंट चुन रहा है.

दूसरी इमेज. शिक्षक किसी तीसरे पक्ष के सोर्स से लिंक चिपका रहे हैं. शिक्षक ने तीसरे पक्ष का Classroom ऐड-ऑन पहले से इंस्टॉल कर लिया हो.

तीसरी इमेज. जब चिपकाया गया लिंक, तीसरे पक्ष के डेवलपर के तय किए गए रेगुलर एक्सप्रेशन से मेल खाता है, तो शिक्षक को इंटरैक्टिव डायलॉग दिखता है.

अगर कोई शिक्षक, तीसरे चित्र में दिखाए गए पॉप-अप में "अभी आज़माएं" को चुनता है, तो उसे आपके ऐड-ऑन के अटैचमेंट डिस्कवरी iframe पर रीडायरेक्ट कर दिया जाता है.