جزئیات پارامتر iframe و query

افزونه‌های کلاس درس در iframe بارگیری می‌شوند تا تجربه کاربری یکپارچه و راحت را در اختیار کاربر نهایی قرار دهند. چهار نوع iframe مجزا وجود دارد. برای یک نمای کلی از هدف و ظاهر هر iframe، به صفحات iframes در فهرست سفرهای کاربر مراجعه کنید.

دستورالعمل های امنیتی iframe

از شرکا انتظار می رود بهترین شیوه های صنعت را برای ایمن سازی iframe خود دنبال کنند. برای محافظت از iframe، تیم امنیتی ما موارد زیر را توصیه می‌کند:

• HTTPS مورد نیاز است . ما قویاً توصیه می کنیم از TLS 1.2 یا بالاتر استفاده کنید و امنیت حمل و نقل سخت HTTP را فعال کنید. این مقاله مرتبط با MDN در مورد امنیت حمل و نقل دقیق را ببینید.

• سیاست امنیتی محتوای دقیق را فعال کنید. این مقاله OWASP و این مقاله مربوط به سیاست امنیت محتوا MDN را ببینید.

• ویژگی کوکی امن را فعال کنید. ویژگی HttpOnly و این مقاله مربوط به Cookies MDN را ببینید.

پیکربندی iFrame URI

URI تنظیم پیوست همان چیزی است که iframe اکتشاف پیوست بارگیری می‌کند، و جایی است که معلمان جریان ایجاد پیوست‌های افزودنی را در یک پست Classroom آغاز می‌کنند. می توان آن را در کنسول پروژه Google Cloud تنظیم کرد. این URI را در API و سرویس پروژه Google Cloud > Google Workspace Marketplace SDK > صفحه پیکربندی برنامه تنظیم کنید.

پیشوندهای URI پیوست مجاز برای اعتبارسنجی URI های تنظیم شده در AddOnAttachment با استفاده از روش های *.addOnAttachments.create و *.addOnAttachments.patch استفاده می شود. اعتبارسنجی یک تطبیق پیشوند رشته تحت اللفظی است و در حال حاضر اجازه استفاده از کارت های وحشی را نمی دهد.

پارامترهای پرس و جو

iframes اطلاعات حیاتی را به عنوان پارامترهای جستجو به افزونه ارسال می کند. دو دسته از پارامترها وجود دارد: پارامترهای مربوط به پیوست و مربوط به ورود به سیستم.

پارامترهای مرتبط با پیوست

پارامترهای مرتبط با پیوست اطلاعاتی را در مورد دوره، تکلیف، پیوست افزودنی، ارسال دانشجو و یک نشانه مجاز در اختیار افزونه قرار می دهد.

شناسه دوره

مقدار courseId یک شناسه برای دوره است.

همراه با تمام iframe ها.

شناسه مورد

مقدار itemId یک شناسه Announcement است،

CourseWork یا CourseWorkMaterial که این پیوست روی آن پیوست شده است.

همراه با تمام iframe ها.

نوع مورد

مقدار itemType نوع منبعی را که بر روی آن قرار دارد مشخص می کند

پیوست پیوست شده است. مقدار رشته ارسال شده یکی از "announcements" ، "courseWork" یا "courseWorkMaterials" است.

همراه با تمام iframe ها.

شناسه پیوست

مقدار attachmentId یک شناسه برای پیوست است.

همراه با iframe های teacherViewUri ، studentViewUri و studentWorkReviewUri .

شناسه ارسال

مقدار submissionId یک شناسه برای کار دانش‌آموز است، اما باید در ترکیب با attachmentId برای شناسایی کار دانش‌آموز در یک تکلیف خاص استفاده شود.

همراه با studentWorkReviewUri .

توجه: می‌توانید از کلید ترکیبی submissionId و attachmentId برای شناسایی کار دانش‌آموز استفاده کنید، در صورتی که پیوست یکسانی به یک دانش‌آموز در دوره‌های مختلف اختصاص داده شود. برای اطلاعات بیشتر، به محتوای کپی شده مراجعه کنید.

نشانه افزودنی

مقدار addOnToken یک نشانه مجوز است که برای ساختن استفاده می شود

برای ایجاد افزونه addOnAttachments.create فراخوانی کنید.

همراه با iframe کشف پیوست و iframe ارتقاء پیوند .

URL برای ارتقا

وجود مقدار urlToUpgrade به این معنی است که

معلم یک پیوست پیوند را در تکلیف گنجانده است و موافقت کرده است که آن را به یک پیوست افزودنی ارتقا دهد. اگر قبلاً این ویژگی را پیکربندی نکرده‌اید، برای جزئیات بیشتر به راهنمای ارتقا پیوندها به پیوست‌های افزودنی مراجعه کنید.

همراه با iframe ارتقاء پیوند .

پارامترهای مربوط به ورود به سیستم

پارامتر query login_hint اطلاعاتی را در مورد بازدید کاربر Classroom از صفحه وب افزونه ارائه می دهد. این پارامتر پرس و جو در URL iframe src ارائه شده است. زمانی ارسال می‌شود که کاربر قبلاً از افزونه شما برای کمک به کاهش اصطکاک ورود کاربر نهایی استفاده کرده باشد. شما باید این پارامتر پرس و جو را در اجرای افزونه خود مدیریت کنید.

راهنمایی ورود

login_hint یک شناسه منحصر به فرد برای گوگل کاربر است

حساب. پس از اینکه کاربر برای اولین بار به افزونه شما وارد شد، پارامتر login_hint در هر بازدید بعدی از افزونه شما توسط همان کاربر ارسال می شود.

دو کاربرد بالقوه برای پارامتر login_hint وجود دارد:

1. مقدار login_hint را در جریان احراز هویت ارسال کنید تا کاربر نیازی به وارد کردن اطلاعات کاربری خود در هنگام نمایش کادر گفتگوی ورود نداشته باشد. کاربر به طور خودکار وارد سیستم نشده است.
2. پس از اینکه کاربر وارد سیستم شد، از این پارامتر برای مقایسه مقدار با کاربرانی که ممکن است قبلاً به افزونه وارد شده‌اید، استفاده کنید. اگر مطابقت پیدا کردید، می‌توانید کاربر را وارد سیستم شده رها کنید و از نمایش جریان ورود به سیستم خودداری کنید. اگر پارامتر با هیچ یک از کاربرانی که به سیستم وارد شده‌اند مطابقت ندارد، از کاربر بخواهید با یک دکمه ورود به سیستم مارک Google وارد سیستم شود.

همراه با تمام iframe ها.

توجه: اطلاعات اضافی را می‌توان در مورد اجرای پارامتر login_hint و جریان ورود به سیستم در صفحات راهنما SSO ، ورود بدون اصطکاک ، و ورود به سیستم تکراری Handle پیدا کرد.

iframe کشف پیوست

بعد	توضیحات
مورد نیاز	بله
URI	در فراداده افزودنی ارائه شده است
پارامترهای پرس و جو	courseId ، itemId ، itemType ، addOnToken و login_hint .
ارتفاع	80% ارتفاع پنجره منهای 60 پیکسل برای هدر بالا
عرض	حداکثر 1600 پیکسل 90% عرض پنجره زمانی که پنجره <= 600px عرض داشته باشد 80٪ عرض پنجره زمانی که عرض پنجره > 600 پیکسل باشد

نمونه ای از سناریوی کشف پیوست

1. یک افزونه Classroom در Google Workspace Marketplace با یک URI کشف پیوست https://example.com/addon ثبت شده است.
2. یک معلم این افزونه را نصب می کند و یک اعلان، تکلیف یا مطلب جدیدی را در یکی از دوره های خود ایجاد می کند. برای مثال، itemId=234 ، itemType=courseWork و courseId=123 .
3. در حین پیکربندی آن مورد، معلم افزونه تازه نصب شده را به عنوان پیوست انتخاب می کند.
4. Classroom یک iframe با URL src تنظیم شده روی https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 ایجاد می کند.
   1. معلم برای انتخاب پیوست کاری را در iframe انجام می دهد.
5. در انتخاب پیوست، افزونه یک postMessage به Classroom می‌فرستد تا iframe را ببندد.

iframes teacherViewUri و studentViewUri

بعد	توضیحات
مورد نیاز	بله
URI	teacherViewUri یا studentViewUri
پارامترهای پرس و جو	courseId ، itemId ، itemType ، attachmentId و login_hint .
ارتفاع	100٪ ارتفاع پنجره منهای 140 پیکسل برای هدر بالا
عرض	100% عرض پنجره

studentWorkReviewUri iframe

بعد	توضیحات
مورد نیاز	خیر (تعیین می کند که آیا این یک پیوست از نوع فعالیت است)
URI	studentWorkReviewUri
پارامترهای پرس و جو	courseId ، itemId ، itemType ، attachmentId ، submissionId و login_hint .
ارتفاع	100٪ ارتفاع پنجره منهای 168 پیکسل برای هدر بالا
عرض	100% عرض پنجره منهای نوار کناری<> نوار کناری 312 پیکسل در صورت باز شدن و 56 پیکسل در هنگام جمع شدن

توجه: معلمان می توانند iframe Student Work Review را برای دانش آموزی که قبلاً پیوست افزودنی را مشاهده نکرده است باز کنند. در این حالت، افزونه ممکن است هنوز از این دانش آموز آگاه نباشد و باید پیام مناسبی را نشان دهد.

لینک ارتقا iframe

بعد	توضیحات
مورد نیاز	بله، اگر ارتقاء پیوندها به پیوست های افزودنی توسط افزونه شما پشتیبانی می شود.
URI	در فراداده افزودنی ارائه شده است
پارامترهای پرس و جو	courseId ، itemId ، itemType ، addOnToken ، urlToUpgrade و login_hint .
ارتفاع	80% ارتفاع پنجره منهای 60 پیکسل برای هدر بالا
عرض	حداکثر 1600 پیکسل 90% عرض پنجره زمانی که پنجره <= 600px عرض داشته باشد 80٪ عرض پنجره زمانی که عرض پنجره > 600 پیکسل باشد

نمونه ای از سناریوی ارتقاء پیوند

1. یک افزونه Classroom با URI ارتقا پیوند https://example.com/upgrade ثبت شده است. شما الگوهای پیشوند میزبان و مسیر زیر را برای پیوست‌های پیوند ارائه کرده‌اید که Classroom باید سعی کند آن‌ها را به یک پیوست افزودنی ارتقا دهد:
   • میزبان example.com و پیشوند مسیر /quiz است.
2. یک معلم اعلامیه، تکلیف یا مطالب جدیدی را در یکی از دوره های خود ایجاد می کند. برای مثال، itemId=234 ، itemType=courseWork و courseId=123 .
3. یک معلم پیوندی، https://example.com/quiz/5678 را در گفتگوی پیوست پیوند می‌چسباند که با الگوی URL ارائه شده مطابقت دارد. سپس از معلم خواسته می شود که پیوند را به یک پیوست افزودنی ارتقا دهد.

4. Classroom iframe Link Upgrade را با URL تنظیم شده روی https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 .

5. شما پارامترهای پرس و جو ارسال شده در iframe را ارزیابی می کنید و با نقطه پایانی CreateAddOnAttachment تماس می گیرید. توجه داشته باشید که پارامتر پرس و جوی urlToUpgrade وقتی روی iframe ارسال می شود URI کدگذاری می شود. شما باید پارامتر را رمزگشایی کنید تا آن را به شکل اصلی به دست آورید. به عنوان مثال، جاوا اسکریپت تابع decodeURIComponent() ارائه می دهد.

6. با ایجاد موفقیت آمیز یک پیوست افزودنی از یک پیوند، یک postMessage به Classroom ارسال می کنید تا iframe را ببندید.

iframe را ببندید

ممکن است iframe از ابزار یادگیری با ارسال یک postMessage با محموله {type: 'Classroom', action: 'closeIframe'} بسته شود. Classroom فقط این postMessage از host_name+port مربوط به URI اصلی باز شده می پذیرد.

<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 باید دارای همان domain+port با URI مورد استفاده برای راه اندازی iframe باشد، در غیر این صورت پیام نادیده گرفته می شود. یک راه حل این است که به صفحه ای در دامنه اصلی هدایت شوید که کاری جز ارسال رویداد postMessage انجام نمی دهد.

iframe را از یک برگه جدید ببندید

حفاظت های متقابل دامنه از کارکرد آن جلوگیری می کند. راه حل این است که ارتباطات بین iframe و برگه جدید را به تنهایی مدیریت کنید و اجازه دهید iframe در نهایت مسئول صدور رویداد بسته postMessage باشد. به عنوان یک نکته جانبی، پیوند "باز کردن در نام شریک" در حال حذف است تا کاربران در آینده نزدیک برگه هایی به این روش ایجاد نکنند.

محدودیت ها

همه iframe ها با ویژگی های sandbox زیر باز می شوند:

• 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 در مورد نحوه کاهش افزایش مورد نیاز شرکا ، درخواست‌های ویژگی ایجاد کنید.

قابلیت کشف افزونه ها را با استفاده از عبارات معمولی URL فعال کنید

معلمان اغلب تکالیفی را با پیوست های پیوند ایجاد می کنند. برای ترویج استفاده از برافزای خود، می‌توانید عبارات منظمی را مشخص کنید که با URL منابع قابل دسترسی در افزونه شما مطابقت داشته باشد. معلمی که پیوندی را پیوست می‌کند که با یکی از عبارات معمولی شما مطابقت دارد، گفتگوی غیرقابل رد کردنی را می‌بیند که آنها را تشویق می‌کند تا افزونه شما را امتحان کنند. آنها فقط در صورتی گفتگو را می بینند که افزونه قبلاً برای حساب آنها نصب شده باشد.

اگر می‌خواهید این رفتار را به معلمان ارائه دهید، عبارات منظم مناسب را به مخاطبین Google خود ارائه دهید . اگر عبارات منظمی که ارائه می‌دهید بیش از حد گسترده هستند یا با افزونه دیگری در تضاد هستند، ممکن است برای محدودتر یا متمایزتر بودن اصلاح شوند.

شکل 1. معلم در حال انتخاب پیوست پیوند به یک تکلیف جدید.

شکل 2. معلم پیوندی را از منبع شخص ثالث چسباند. معلم قبلاً افزونه Classroom شخص ثالث را نصب کرده است.

شکل 3. گفتگوی تعاملی زمانی که پیوند چسبانده شده با عبارت منظم مشخص شده توسط توسعه دهنده شخص ثالث مطابقت دارد، به معلم ارائه می شود.

اگر معلمی همانطور که در شکل 3 مشاهده می‌شود، «اکنون امتحان کنید» را انتخاب کند، به iframe کشف پیوست افزونه شما هدایت می‌شود.