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

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

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

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

सर्वर ऐप्लिकेशन का कॉन्फ़िगरेशन

आईफ़्रेम को सुरक्षित रखने के लिए, हम सर्वर के इन कॉन्फ़िगरेशन का सुझाव देते हैं:

• एचटीटीपीएस ज़रूरी है. हमारा सुझाव है कि TLS 1.2 या इससे ज़्यादा वर्शन का इस्तेमाल करें. साथ ही, एचटीटीपी स्ट्रिक्ट ट्रांसपोर्ट सिक्योरिटी (एचएसटीएस) को चालू करें. स्ट्रिक्ट ट्रांसपोर्ट सिक्योरिटी के बारे में, MDN का यह लेख पढ़ें.
• कॉन्टेंट की सुरक्षा के लिए सख्त नीति (स्ट्रिक्ट सीएसपी) चालू करें. यह OWASP लेख और इससे जुड़ा यह कॉन्टेंट की सुरक्षा के लिए नीति (सीएसपी) से जुड़ा MDN लेख पढ़ें.
• Secure कुकी एट्रिब्यूट को चालू करें. HttpOnly एट्रिब्यूट और इससे जुड़ा Cookies MDN लेख पढ़ें.

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

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

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

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

कोर्स आईडी

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

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

आइटम का आईडी

itemId वैल्यू, Announcement, CourseWork या CourseWorkMaterial का आइडेंटिफ़ायर होती है. यह अटैचमेंट, इन्हीं में से किसी एक पर अटैच होता है.

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

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

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

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

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

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

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

सबमिशन आईडी

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

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

ऐड-ऑन टोकन

addOnToken वैल्यू, अनुमति देने वाला टोकन है. इसका इस्तेमाल ऐड-ऑन बनाने के लिए, addOnAttachments.create कॉल करने के लिए किया जाता है.

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

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

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

Link Upgrade iframe के साथ शामिल है.

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

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

लॉगिन से जुड़ा संकेत

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

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

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

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

Attachment Discovery iframe

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

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

teacherViewUri और studentViewUri iframe

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, लिंक अपग्रेड करने वाला iframe लॉन्च करता है. इसका यूआरएल https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 पर सेट होता है.

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

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

iframe बंद करें

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

<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 को close 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 ऐड-ऑन पहले से ही इंस्टॉल किया हुआ है.

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

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