сведения о параметрах 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 о политике безопасности контента .
• Включите атрибут Secure cookie . См. атрибут HttpOnly и соответствующую статью на MDN о файлах cookie .

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

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

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

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

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

Значение 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-модуля при обновлении ссылки .

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

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

Подсказка для входа в систему

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

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

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

Входит в состав всех iframe-элементов.

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.

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

Ограничения

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

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

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

• allow="microphone *"

Блокировка файлов cookie третьих лиц

Be aware that third-party cookie blocking makes it difficult to maintain a signed in session in an iframe. Refer to https://www.cookiestatus.com on the current state of cookie blocking across different browsers. Of course, this issue is not unique to Google Classroom add-ons and affects all websites that iframe third-parties. Many of our partners have already encountered this issue.

Вот несколько общих способов решения проблемы:

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

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

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

Teachers frequently create assignments with link attachments. To promote the use of your add-on, you can specify regular expressions that match URLs of resources that can be accessed in your add-on. A teacher attaching a link that matches one of your regular expressions sees a dismissible dialog encouraging them to try your add-on. They only see the dialog if the add-on is already installed for their account.

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

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

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

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

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