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

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

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

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

پیکربندی برنامه سرور

برای محافظت از iframe، پیکربندی‌های سرور زیر را توصیه می‌کنیم:

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

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

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

شناسه دوره

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

شامل تمام iframe ها می‌شود.

شناسه کالا

مقدار itemId شناسه‌ی Announcement ، CourseWork یا CourseWorkMaterial است که این پیوست به آن پیوست شده است.

شامل تمام iframe ها می‌شود.

نوع کالا

مقدار itemType نوع منبعی را که این پیوست به آن متصل شده است، مشخص می‌کند. مقدار رشته‌ای ارسالی یکی از انواع "announcements" ، "courseWork" یا "courseWorkMaterials" است.

شامل تمام iframe ها می‌شود.

شناسه پیوست

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

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

شناسه ارسال

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

همراه با studentWorkReviewUri ارائه شده است.

توکن افزونه

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

همراه با iframe مربوط به Attachment Discovery و iframe مربوط به Link Upgrade .

آدرس اینترنتی برای ارتقا

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

همراه با iframe مربوط به ارتقاء لینک .

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

راهنمای ورود

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

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

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

شامل تمام iframe ها می‌شود.

iframe کشف پیوست

ابعاد توضیحات
مورد نیاز بله
یو آر آی ارائه شده در فراداده افزونه
پارامترهای پرس و جو courseId ، itemId ، itemType ، addOnToken و login_hint .
ارتفاع ۸۰٪ ارتفاع پنجره منهای ۶۰ پیکسل برای هدر بالا
عرض حداکثر ۱۶۰۰ پیکسل
۹۰٪ عرض پنجره وقتی عرض پنجره کمتر از ۶۰۰ پیکسل باشد
۸۰٪ عرض پنجره وقتی عرض پنجره > ۶۰۰ پیکسل باشد

مثال سناریوی کشف پیوست

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

آیفریم‌های teacherViewUri و studentViewUri

ابعاد توضیحات
مورد نیاز بله
یو آر آی teacherViewUri یا studentViewUri
پارامترهای پرس و جو courseId ، itemId ، itemType ، attachmentId و login_hint .
ارتفاع ۱۰۰٪ ارتفاع پنجره منهای ۱۴۰ پیکسل برای هدر بالا
عرض ۱۰۰٪ عرض پنجره

iframe مربوط به studentWorkReviewUri

ابعاد توضیحات
مورد نیاز خیر (تعیین می‌کند که آیا این یک پیوست از نوع فعالیت است یا خیر)
یو آر آی studentWorkReviewUri
پارامترهای پرس و جو courseId ، itemId ، itemType ، attachmentId ، submissionId و login_hint .
ارتفاع ۱۰۰٪ ارتفاع پنجره منهای ۱۶۸ پیکسل برای هدر بالا
عرض ۱۰۰٪ عرض پنجره منهای عرض سایدبار<> سایدبار در حالت باز ۳۱۲ پیکسل و در حالت جمع شده ۵۶ پیکسل است
ابعاد توضیحات
مورد نیاز بله، اگر افزونه شما از ارتقاء لینک‌ها به پیوست‌های افزونه پشتیبانی کند.
یو آر آی ارائه شده در فراداده افزونه
پارامترهای پرس و جو courseId ، itemId ، itemType ، addOnToken ، urlToUpgrade و login_hint .
ارتفاع ۸۰٪ ارتفاع پنجره منهای ۶۰ پیکسل برای هدر بالا
عرض حداکثر ۱۶۰۰ پیکسل
۹۰٪ عرض پنجره وقتی عرض پنجره کمتر از ۶۰۰ پیکسل باشد
۸۰٪ عرض پنجره وقتی عرض پنجره > ۶۰۰ پیکسل باشد
  1. یک افزونه‌ی Classroom با آدرس URL ارتقاء لینک https://example.com/upgrade ثبت شده است. شما الگوهای پیشوند میزبان و مسیر زیر را برای پیوست‌های لینک ارائه داده‌اید که Classroom باید سعی کند آنها را به یک پیوست الحاقی ارتقا دهد:
    • میزبان example.com و پیشوند مسیر /quiz است.
  2. یک معلم یک اطلاعیه، تکلیف یا مطلب جدید در یکی از دوره‌های خود ایجاد می‌کند. برای مثال، itemId=234 ، itemType=courseWork و courseId=123 .
  3. معلمی لینکی https://example.com/quiz/5678 را در پنجره‌ی پیوست لینک قرار می‌دهد که با الگوی URL ارائه شده توسط شما مطابقت دارد. سپس از معلم خواسته می‌شود که لینک را به یک پیوست افزونه ارتقا دهد.

  4. کلاس‌روم، آی‌فریم «ارتقاء لینک» را با 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 را از طریق ابزار یادگیری با ارسال یک postMessage با payload {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 ارسال می‌کند باید همان دامنه+پورتی را داشته باشد که 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های شخص ثالث استفاده می‌کنند، تأثیر می‌گذارد. بسیاری از شرکای ما قبلاً با این مشکل مواجه شده‌اند.

برخی از راهکارهای کلی عبارتند از:

  • برای ایجاد کوکی در یک زمینه شخص ثالث، یک برگه جدید باز کنید. برخی از مرورگرها به کوکی‌های ایجاد شده در زمینه شخص ثالث در حالی که در یک زمینه شخص ثالث هستند، دسترسی می‌دهند.
  • از کاربر بخواهید کوکی‌های شخص ثالث را مجاز کند. این ممکن است همیشه برای همه کاربران امکان‌پذیر نباشد.
  • برنامه‌های وب تک صفحه‌ای طراحی کنید که به کوکی‌ها متکی نباشند.

انتظار می‌رود محدودیت‌های کوکی بیشتری در نسخه‌های آینده مرورگر اعمال شود. درخواست‌های ویژگی ایجاد کنید تا در مورد چگونگی کاهش افزایش مورد نیاز شرکا، به گوگل بازخورد ارسال کنید.

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

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

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

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

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

پنجره‌ی کشف‌پذیری عبارت منظم (Regex) شکل ۳. پنجره محاوره‌ای که وقتی لینک پیست‌شده با یک عبارت منظم مشخص‌شده توسط توسعه‌دهنده شخص ثالث مطابقت دارد، به معلم نمایش داده می‌شود.

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