сведения о параметрах iframe и запроса

Дополнения для класса загружаются в iframe, обеспечивая конечному пользователю удобный и бесперебойный пользовательский интерфейс. Существует пять различных типов iframe; см. страницы iframe в каталоге «Пути пользователя» для обзора назначения и внешнего вида каждого iframe.

правила безопасности iframe

От разработчиков ожидается соблюдение передовых отраслевых практик для защиты iframe. Однако вам также следует включить определённые взаимодействия с API в свой пользовательский интерфейс, чтобы подтвердить наличие учётных данных и возможность корректно определить роль пользователя в курсе.

Конфигурация серверного приложения

Для защиты iframe мы рекомендуем следующие конфигурации сервера:

• Требуется HTTPS . Мы настоятельно рекомендуем использовать TLS 1.2 или выше и включить HTTP Strict Transport Security (HSTS). См. соответствующую статью MDN о Strict Transport Security.
• Включите строгую политику безопасности контента (Strict CSP). См. эту статью OWASP и соответствующую статью MDN о политике безопасности контента .
• Включите атрибут «Безопасный файл cookie» . См. атрибут HttpOnly и соответствующую статью MDN о файлах cookie .

Параметры запроса

Элементы iframe передают важную информацию в надстройку в виде параметров запроса . Существует две категории параметров: параметры, связанные с вложениями, и параметры, связанные с входом в систему.

Параметры, связанные с прикреплением

Параметры, связанные с вложением, предоставляют надстройке информацию о курсе, задании, вложении к дополнению, отправке студента и авторизационном токене.

Идентификатор курса

Значение courseId — это идентификатор курса.

Включено во все фреймы.

Идентификатор товара

Значение itemId — это идентификатор Announcement , CourseWork или CourseWorkMaterial , к которому прикреплено это вложение.

Включено во все фреймы.

Тип элемента

Значение itemType определяет тип ресурса, к которому прикреплено это вложение. Переданное строковое значение может быть одним из следующих: "announcements" , "courseWork" или "courseWorkMaterials" .

Включено во все фреймы.

Идентификатор вложения

Значение attachmentId — это идентификатор вложения.

Включено в фреймы teacherViewUri , studentViewUri и studentWorkReviewUri .

Идентификатор отправки

Значение submissionId является идентификатором работы учащегося, но его следует использовать в сочетании с attachmentId для идентификации работы учащегося по конкретному заданию.

Включено в studentWorkReviewUri .

Дополнительный токен

Значение addOnToken — это токен авторизации, используемый для выполнения вызовов addOnAttachments.create с целью создания надстройки.

Входит в состав iframe обнаружения вложений и iframe обновления ссылок .

URL для обновления

Наличие значения urlToUpgrade означает, что преподаватель включил в задание вложение-ссылку и согласился преобразовать его в дополнение . Если эта функция ещё не настроена, см. руководство по преобразованию ссылок в дополнительные вложения для получения более подробной информации.

Включено в iframe обновления ссылок .

Параметры, связанные со входом в систему

Параметр запроса login_hint предоставляет информацию о посещении пользователем Classroom веб-страницы дополнения. Этот параметр запроса указан в URL-адресе iframe src . Он отправляется, когда пользователь ранее использовал ваше дополнение, чтобы упростить вход конечного пользователя. Вам необходимо обработать этот параметр запроса в реализации вашего дополнения.

Подсказка для входа

Параметр login_hint — это уникальный идентификатор учётной записи Google пользователя. После первого входа пользователя в ваше дополнение параметр login_hint передаётся при каждом последующем посещении дополнения этим же пользователем.

Параметр login_hint может использоваться в двух случаях:

1. Передайте значение login_hint во время аутентификации, чтобы пользователю не приходилось вводить свои учётные данные при появлении диалогового окна входа. Пользователь не будет автоматически авторизован.
2. После входа пользователя в систему используйте этот параметр для сравнения значения с данными других пользователей, которые уже могли войти в дополнение. Если вы найдете совпадение, вы можете оставить пользователя в системе и не показывать процесс входа. Если параметр не совпадает ни с одним из вошедших пользователей, предложите пользователю войти с помощью кнопки входа с логотипом Google .

Включено во все фреймы.

iframe обнаружения вложений

Пример сценария обнаружения вложений

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.

фреймы teacherViewUri и studentViewUri

studentWorkReviewUri iframe

Обновление ссылки iframe

Пример сценария обновления ссылки

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 обновления ссылок с 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. Чтобы получить его в исходном виде, необходимо декодировать этот параметр. Например, в JavaScript есть функция 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 должны совпадать с доменом и портом URI, используемого для запуска iframe, в противном случае сообщение игнорируется. Обходной путь — перенаправление на страницу в исходном домене, которая просто отправляет событие postMessage .

Закрыть iframe из новой вкладки

Междоменная защита не позволяет этому сработать. Обходной путь — самостоятельно обрабатывать взаимодействие между iframe и новой вкладкой, и iframe в конечном итоге будет отвечать за генерацию события закрытия postMessage . Кстати, гиперссылка «Открыть в имени партнёра» удаляется, чтобы пользователи не создавали вкладки таким образом в ближайшем будущем.

Ограничения

Все фреймы открываются со следующими атрибутами песочницы :

• allow-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-same-origin

и следующая политика функций:

• allow="microphone *"

Блокировка сторонних файлов cookie

Обратите внимание, что блокировка сторонних файлов cookie затрудняет сохранение сеанса в iframe. Актуальную информацию о блокировке файлов cookie в различных браузерах см. на сайте https://www.cookiestatus.com . Конечно, эта проблема касается не только дополнений для Google Класса и затрагивает все веб-сайты, размещающие сторонние файлы cookie в iframe. Многие наши партнёры уже столкнулись с этой проблемой.

Вот некоторые общие решения:

• Откройте новую вкладку, чтобы создать файл cookie в контексте основной стороны. Некоторые браузеры предоставляют доступ к файлам cookie, созданным в контексте основной стороны, в контексте третьей стороны.
• Попросите пользователя разрешить использование сторонних файлов cookie. Это может быть не всегда возможно для всех пользователей.
• Создавайте одностраничные веб-приложения, не использующие файлы cookie.

Ожидается, что в будущих версиях браузера будут введены дополнительные ограничения на использование файлов cookie. Создавайте запросы на добавление функций , чтобы отправлять в Google отзывы о том, как снизить нагрузку, требуемую партнёрами.

Обеспечить возможность обнаружения дополнений с помощью регулярных выражений URL

Преподаватели часто создают задания с прикрепленными ссылками. Чтобы стимулировать использование вашего дополнения, вы можете указать регулярные выражения, соответствующие URL-адресам ресурсов, к которым можно получить доступ в вашем дополнении. Преподаватель, прикрепляющий ссылку, соответствующую одному из ваших регулярных выражений, увидит диалоговое окно с предложением попробовать ваше дополнение, которое можно закрыть. Это диалоговое окно будет отображаться только в том случае, если дополнение уже установлено в его учетной записи.

Если вы хотите предоставить такую возможность учителям, предоставьте своим контактам Google соответствующие регулярные выражения . Если предоставленные вами регулярные выражения слишком общие или конфликтуют с другим дополнением, их можно изменить, сделав более ограниченными или чёткими.

Рисунок 1. Преподаватель выбирает ссылку-вложение для нового задания.

Рисунок 2. Учитель вставляет ссылку из стороннего источника. Учитель уже установил стороннее дополнение Classroom.

Рисунок 3. Интерактивный диалог, отображаемый для преподавателя, когда вставленная ссылка соответствует регулярному выражению, указанному сторонним разработчиком.

Если преподаватель выбирает «Попробовать сейчас» во всплывающем окне, как показано на рисунке 3, он перенаправляется в iframe обнаружения вложений вашего дополнения.