افزونه‌های کلاس درس در 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.
- نشانه افزودنی
مقدار
addOnTokenیک نشانه مجوز است که برای ساختن استفاده می شودبرای ایجاد افزونه
addOnAttachments.createفراخوانی کنید.همراه با iframe کشف پیوست و iframe ارتقاء پیوند .
- URL برای ارتقا
وجود مقدار
urlToUpgradeبه این معنی است کهمعلم یک پیوست پیوند را در تکلیف گنجانده است و موافقت کرده است که آن را به یک پیوست افزودنی ارتقا دهد. اگر قبلاً این ویژگی را پیکربندی نکرده‌اید، برای جزئیات بیشتر به راهنمای ارتقا پیوندها به پیوست‌های افزودنی مراجعه کنید.
همراه با iframe ارتقاء پیوند .
پارامترهای مربوط به ورود به سیستم
پارامتر query login_hint اطلاعاتی را در مورد بازدید کاربر Classroom از صفحه وب افزونه ارائه می دهد. این پارامتر پرس و جو در URL iframe src ارائه شده است. زمانی ارسال می‌شود که کاربر قبلاً از افزونه شما برای کمک به کاهش اصطکاک ورود کاربر نهایی استفاده کرده باشد. شما باید این پارامتر پرس و جو را در اجرای افزونه خود مدیریت کنید.
- راهنمایی ورود
login_hintیک شناسه منحصر به فرد برای گوگل کاربر استحساب. پس از اینکه کاربر برای اولین بار به افزونه شما وارد شد، پارامتر
login_hintدر هر بازدید بعدی از افزونه شما توسط همان کاربر ارسال می شود.دو کاربرد بالقوه برای پارامتر
login_hintوجود دارد:- مقدار
login_hintرا در جریان احراز هویت ارسال کنید تا کاربر نیازی به وارد کردن اطلاعات کاربری خود در هنگام نمایش کادر گفتگوی ورود نداشته باشد. کاربر به طور خودکار وارد سیستم نشده است. - پس از اینکه کاربر وارد سیستم شد، از این پارامتر برای مقایسه مقدار با کاربرانی که ممکن است قبلاً به افزونه وارد شده‌اید، استفاده کنید. اگر مطابقت پیدا کردید، می‌توانید کاربر را وارد سیستم شده رها کنید و از نمایش جریان ورود به سیستم خودداری کنید. اگر پارامتر با هیچ یک از کاربرانی که به سیستم وارد شده‌اند مطابقت ندارد، از کاربر بخواهید با یک دکمه ورود به سیستم مارک Google وارد سیستم شود.
همراه با تمام iframe ها.
- مقدار
iframe کشف پیوست
| بعد | توضیحات |
|---|---|
| مورد نیاز | بله |
| URI | در فراداده افزودنی ارائه شده است |
| پارامترهای پرس و جو | courseId ، itemId ، itemType ، addOnToken و login_hint . |
| ارتفاع | 80% ارتفاع پنجره منهای 60 پیکسل برای هدر بالا |
| عرض | حداکثر 1600 پیکسل 90% عرض پنجره زمانی که پنجره <= 600px عرض داشته باشد 80٪ عرض پنجره زمانی که عرض پنجره > 600 پیکسل باشد |
نمونه ای از سناریوی کشف پیوست
- یک افزونه Classroom در Google Workspace Marketplace با یک URI کشف پیوست
https://example.com/addonثبت شده است. - یک معلم این افزونه را نصب می کند و یک اعلان، تکلیف یا مطلب جدیدی را در یکی از دوره های خود ایجاد می کند. برای مثال،
itemId=234،itemType=courseWorkوcourseId=123. - در حین پیکربندی آن مورد، معلم افزونه تازه نصب شده را به عنوان پیوست انتخاب می کند.
- Classroom یک iframe با URL src تنظیم شده روی
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456ایجاد می کند.- معلم برای انتخاب پیوست کاری را در iframe انجام می دهد.
- در انتخاب پیوست، افزونه یک
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
| بعد | توضیحات |
|---|---|
| مورد نیاز | بله، اگر ارتقاء پیوندها به پیوست های افزودنی توسط افزونه شما پشتیبانی می شود. |
| URI | در فراداده افزودنی ارائه شده است |
| پارامترهای پرس و جو | courseId ، itemId ، itemType ، addOnToken ، urlToUpgrade و login_hint . |
| ارتفاع | 80% ارتفاع پنجره منهای 60 پیکسل برای هدر بالا |
| عرض | حداکثر 1600 پیکسل 90% عرض پنجره زمانی که پنجره <= 600px عرض داشته باشد 80٪ عرض پنجره زمانی که عرض پنجره > 600 پیکسل باشد |
نمونه ای از سناریوی ارتقاء پیوند
- یک افزونه Classroom با URI ارتقا پیوند
https://example.com/upgradeثبت شده است. شما الگوهای پیشوند میزبان و مسیر زیر را برای پیوست‌های پیوند ارائه کرده‌اید که Classroom باید سعی کند آنها را به یک پیوست افزودنی ارتقا دهد:- میزبان
example.comو پیشوند مسیر/quizاست.
- میزبان
- یک معلم اعلامیه، تکلیف یا مطالب جدیدی را در یکی از دوره های خود ایجاد می کند. برای مثال،
itemId=234،itemType=courseWorkوcourseId=123. - یک معلم پیوندی،
https://example.com/quiz/5678را در گفتگوی پیوست پیوند می‌چسباند که با الگوی URL ارائه شده مطابقت دارد. سپس از معلم خواسته می شود که پیوند را به یک پیوست افزودنی ارتقا دهد. 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.شما پارامترهای پرس و جو ارسال شده در iframe را ارزیابی می کنید و با نقطه پایانی
CreateAddOnAttachmentتماس می گیرید. توجه داشته باشید که پارامتر پرس و جویurlToUpgradeوقتی روی iframe ارسال می شود URI کدگذاری می شود. شما باید پارامتر را رمزگشایی کنید تا آن را به شکل اصلی به دست آورید. به عنوان مثال، جاوا اسکریپت تابعdecodeURIComponent()ارائه می دهد.با ایجاد موفقیت آمیز یک پیوست افزودنی از یک پیوند، یک
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 کشف پیوست افزونه شما هدایت می‌شود.