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

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

iframe के सुरक्षा दिशा-निर्देश

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

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

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

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

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

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

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

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

कोर्स आईडी

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 वैल्यू की मौजूदगी का मतलब है कि

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

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

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

लॉगिन संकेत

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

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

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

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

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

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

डाइमेंशन कंपनी का ब्यौरा
ज़रूरी है हां
यूआरआई ऐड-ऑन मेटाडेटा में दिया गया
क्वेरी पैरामीटर courseId, itemId, itemType, addOnToken, और login_hint.
ऊंचाई सबसे ऊपर मौजूद हेडर के लिए, विंडो की ऊंचाई का 80% कम से कम 60 पिक्सल
चौड़ाई विंडो > 600 पिक्सल चौड़ी होने पर, विंडो की चौड़ाई ज़्यादा से ज़्यादा 1600 पिक्सल
90% होनी चाहिए, जब विंडो <= 600 पिक्सल चौड़ी हो
विंडो की चौड़ाई 80% से ज़्यादा न हो

अटैचमेंट खोजने की स्थिति का उदाहरण

  1. Classroom ऐड-ऑन को Google Workspace Marketplace में 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. अटैचमेंट चुनने पर, ऐड-ऑन, iframe को बंद करने के लिए Classroom को postMessage भेजता है.

EducatorViewUri और छात्र-छात्राओं के व्यूUri iframes

डाइमेंशन कंपनी का ब्यौरा
ज़रूरी है हां
यूआरआई teacherViewUri या studentViewUri
क्वेरी पैरामीटर courseId, itemId, itemType, attachmentId, और login_hint.
ऊंचाई सबसे ऊपर मौजूद हेडर के लिए, विंडो की 100% ऊंचाई घटाकर 140 पिक्सल
चौड़ाई विंडो की चौड़ाई 100% है

छात्रवर्क रिव्यू यूरी iframe

डाइमेंशन कंपनी का ब्यौरा
ज़रूरी है नहीं (इससे तय होता है कि यह गतिविधि-टाइप अटैचमेंट है या नहीं)
यूआरआई studentWorkReviewUri
क्वेरी पैरामीटर courseId, itemId, itemType, attachmentId, submissionId, और login_hint.
ऊंचाई सबसे ऊपर मौजूद हेडर के लिए, विंडो की 100% ऊंचाई घटाकर 168 पिक्सल
चौड़ाई 100% विंडो की चौड़ाई से साइडबार की चौड़ाई<> बड़ा करने पर साइडबार 312 पिक्सल होता है और छोटा करने पर 56 पिक्सल होता है

डाइमेंशन कंपनी का ब्यौरा
ज़रूरी है हां, अगर ऐड-ऑन अटैचमेंट में लिंक अपग्रेड करने की सुविधा आपके ऐड-ऑन के साथ काम करती है.
यूआरआई ऐड-ऑन मेटाडेटा में दिया गया
क्वेरी पैरामीटर courseId, itemId, itemType, addOnToken, urlToUpgrade, और login_hint.
ऊंचाई सबसे ऊपर मौजूद हेडर के लिए, विंडो की ऊंचाई का 80% कम से कम 60 पिक्सल
चौड़ाई विंडो > 600 पिक्सल चौड़ी होने पर, विंडो की चौड़ाई ज़्यादा से ज़्यादा 1600 पिक्सल
90% होनी चाहिए, जब विंडो <= 600 पिक्सल चौड़ी हो
विंडो की चौड़ाई 80% से ज़्यादा न हो
  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 को लर्निंग टूल से बंद किया जा सकता है. ऐसा करने के लिए, आपको पेलोड {type: 'Classroom', action: 'closeIframe'} के साथ postMessage भेजना होगा. Classroom, खोला गया ओरिजनल यूआरआई से मेल खाने वाले होस्टनेम+port से ही इस 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 और नए टैब के बीच के मैसेज खुद मैनेज करें. साथ ही, postMessage बंद करने के इवेंट को जारी करने के लिए iframe को पूरी ज़िम्मेदारी दें. ध्यान दें, "पार्टनर के नाम में खोलें" हाइपरलिंक को हटाया जा रहा है, ताकि उपयोगकर्ता आने वाले समय में इस तरह से टैब न बनाएं.

ज़रूरी शर्तें

सभी 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 Contacts में सही रेगुलर एक्सप्रेशन का इस्तेमाल करके संपर्क करें. अगर आपके दिए गए रेगुलर एक्सप्रेशन बहुत ज़्यादा बड़े हैं या किसी दूसरे ऐड-ऑन के साथ विरोधाभास हैं, तो उनमें ज़्यादा प्रतिबंधित या खास बदलाव किया जा सकता है.

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

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

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

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