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

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

рекомендации по безопасности iframe

Ожидается, что партнеры будут следовать лучшим отраслевым практикам для защиты своего iframe. Чтобы защитить iframe, наша команда безопасности рекомендует следующее:

• Требуется HTTPS . Мы настоятельно рекомендуем использовать TLS 1.2 или более позднюю версию и включить HTTP Strict Transport Security . См. соответствующую статью MDN о строгой транспортной безопасности.

• Включите строгую политику безопасности контента . См. эту статью OWASP и соответствующую статью MDN о политике безопасности контента .

• Включите атрибут «Безопасный файл cookie» . См. атрибут HttpOnly и соответствующую статью MDN о файлах cookie .

Конфигурация URI iFrame

URI настройки вложений — это то, что загружается iframe обнаружения вложений, и именно с него преподаватели начинают процесс создания дополнительных вложений к публикации Класса. Его можно настроить в консоли проекта Google Cloud. Установите этот URI на странице API и сервисов вашего проекта Google Cloud > Google Workspace Marketplace SDK > Конфигурация приложения .

Префиксы URI разрешенных вложений используются для проверки URI, установленных в AddOnAttachment, с помощью методов *.addOnAttachments.create и *.addOnAttachments.patch . Проверка представляет собой буквальное совпадение префикса строки и в настоящее время не позволяет использовать подстановочные знаки.

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

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

Параметры, связанные с вложением

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

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

Значение courseId является идентификатором курса.

Включено во все iframe.

Идентификатор сообщения (устарело)

Значение postId — это идентификатор публикации (объявления, курсовой работы или материала курсовой работы), к которой прикреплено это вложение.

Включено во все 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 Link Upgrade .

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

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

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

login_hint — это уникальный идентификатор Google пользователя.

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

Существует два возможных варианта использования параметра login_hint :

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

Включено во все iframe.

Примечание. Дополнительную информацию о реализации параметра login_hint и процессе входа можно найти на страницах пошаговых инструкций SSO , Frictionless вход и Обработка повторных входов в систему .

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

Измерение	Описание
Необходимый	Да
URI	Указано в метаданных дополнения.
Параметры запроса	courseId , postId (устарело), itemId , itemType , addOnToken и login_hint .
Высота	Высота окна 80 % минус 60 пикселей для верхнего заголовка.
Ширина	Максимум 1600 пикселей Ширина окна 90 %, если ширина окна <= 600 пикселей. Ширина окна 80 %, если ширина окна > 600 пикселей.

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

1. Надстройка для Класса регистрируется в Google Workspace Marketplace с URI обнаружения вложений https://example.com/addon .
2. Учитель устанавливает это дополнение и создает новое объявление, задание или материал в рамках одного из своих курсов. Например, itemId=234 , itemType=courseWork и courseId=123 .
3. При настройке этого элемента преподаватель выбирает вновь установленное дополнение в качестве вложения.
4. Класс создает iframe с URL-адресом источника, установленным на https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 .
   1. Учитель выполняет работу в iframe, чтобы выбрать вложение.
5. При выборе вложения надстройка отправляет сообщение postMessage в Класс, чтобы закрыть iframe.

iframe TeacherViewUri и StudentViewUri

Измерение	Описание
Необходимый	Да
URI	teacherViewUri или studentViewUri
Параметры запроса	courseId , postId (устарело), itemId , itemType , attachmentId и login_hint .
Высота	100% высота окна минус 140 пикселей для верхнего заголовка.
Ширина	100% ширина окна

StudentWorkReviewUri iframe

Измерение	Описание
Необходимый	Нет (определяет, является ли это вложением типа действия)
URI	studentWorkReviewUri
Параметры запроса	courseId , postId (устарело), itemId , itemType , attachmentId , submissionId и login_hint .
Высота	100 % высота окна минус 168 пикселей для верхнего заголовка.
Ширина	100% ширина окна минус ширина боковой панели<> боковая панель составляет 312 пикселей в развернутом виде и 56 пикселей в свернутом.

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

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

Измерение	Описание
Необходимый	Да, если обновление ссылок на вложения дополнений поддерживается вашим дополнением.
URI	Указано в метаданных дополнения.
Параметры запроса	courseId , postId (устарело), itemId , itemType , addOnToken , urlToUpgrade и login_hint .
Высота	Высота окна 80 % минус 60 пикселей для верхнего заголовка.
Ширина	Максимум 1600 пикселей Ширина окна 90 %, если ширина окна <= 600 пикселей. Ширина окна 80 %, если ширина окна > 600 пикселей.

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

1. Надстройка Класса регистрируется с помощью URI обновления ссылки https://example.com/upgrade . Вы предоставили следующие шаблоны префиксов хоста и пути для вложений ссылок , которые Класс должен попытаться обновить до дополнительных вложений :
   • Хост — example.com , а префикс пути — /quiz .
2. Учитель создает новое объявление, задание или материал в рамках одного из своих курсов. Например, itemId=234 , itemType=courseWork и courseId=123 .
3. Учитель вставляет ссылку https://example.com/quiz/5678 в диалоговое окно «Вложение ссылки», соответствующую указанному вами шаблону URL-адреса. Затем учителю будет предложено обновить ссылку до дополнительного вложения.

4. Класс запускает iframe Link Upgrade с URL-адресом, установленным на https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 .

5. Вы оцениваете параметры запроса, передаваемые в iframe, и вызываете конечную точку CreateAddOnAttachment . Обратите внимание, что параметр запроса urlToUpgrade представляет собой кодировку URI при передаче в iframe. Вам необходимо декодировать параметр, чтобы получить его в исходном виде. Например, JavaScript предлагает функцию decodeURIComponent() .

6. При успешном создании дополнительного вложения по ссылке вы отправляете сообщение postMessage в Класс, чтобы закрыть iframe.

Закройте iframe

iframe можно закрыть из инструмента обучения, отправив сообщение postMessage с полезной нагрузкой {type: 'Classroom', action: 'closeIframe'} . Класс принимает это postMessage только от имени_хоста+порта, соответствующего исходному 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

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

Некоторые общие обходные пути:

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

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

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

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

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

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

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

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

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