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

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

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

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

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

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

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

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

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

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

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

कोर्स आईडी

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

सभी iframe के साथ शामिल हैं.

पोस्ट आईडी (अब इस्तेमाल में नहीं है)

postId वैल्यू उस पोस्ट का आइडेंटिफ़ायर है जिससे यह अटैचमेंट जुड़ा है. जैसे, घोषणा, कोर्स वर्क या कोर्स वर्क मटीरियल.

सभी 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, postId (अब सेवा में नहीं है), itemId, itemType, addOnToken, और login_hint.
ऊंचाई शीर्ष हेडर के लिए विंडो की ऊंचाई 80% माइनस 60px
चौड़ाई विंडो की ज़्यादा से ज़्यादा 1600 पिक्सल
90% चौड़ाई, जब विंडो <= 600 पिक्सल चौड़ी हो
विंडो > 600 पिक्सल चौड़ी होने पर विंडो की चौड़ाई 80% हो

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

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

TeachingViewUri और partnerViewUri iframe

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

स्टूडेंटवर्कसमीक्षाUri iframe

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

डाइमेंशन ब्यौरा
ज़रूरी है हां, अगर ऐड-ऑन अटैचमेंट के लिंक को अपग्रेड करना आपके ऐड-ऑन पर काम करता है.
यूआरआई ऐड-ऑन मेटाडेटा में दिया गया
क्वेरी पैरामीटर courseId, postId (अब सेवा में नहीं है), itemId, itemType, addOnToken, urlToUpgrade, और login_hint.
ऊंचाई शीर्ष हेडर के लिए विंडो की ऊंचाई 80% माइनस 60px
चौड़ाई विंडो की ज़्यादा से ज़्यादा 1600 पिक्सल
90% चौड़ाई, जब विंडो <= 600 पिक्सल चौड़ी हो
विंडो > 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&postId=234&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, खोले गए मूल यूआरआई के हिसाब से सिर्फ़ host_name+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 और नए टैब के बीच कम्यूनिकेशन को खुद मैनेज करें. साथ ही, 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 पर रीडायरेक्ट कर दिया जाएगा.