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

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

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

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

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

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

• HTTPS is required . Мы настоятельно рекомендуем использовать TLS 1.2 или выше и включить HTTP Strict Transport Security (HSTS). См. эту связанную статью MDN о Strict Transport Security.
• Включить строгую политику безопасности контента (Strict CSP). См. эту статью OWASP и эту связанную статью MDN о политике безопасности контента .
• Включите атрибут Secure cookie . Смотрите атрибут HttpOnly и эту связанную статью MDN Cookies .

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

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

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

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

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

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

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

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

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

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

Тип товара

Значение itemType определяет тип ресурса, к которому прикреплено это вложение. Переданное строковое значение — одно из "announcements" , "courseWork" или "courseWorkMaterials" .

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

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

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

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

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

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

Включено в studentWorkReviewUri .

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

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

Входит в состав фрейма Attachment Discovery и фрейма Link Upgrade .

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

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

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

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

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

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

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

Параметр 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 зарегистрировано с URL-адресом обновления ссылок https://example.com/upgrade . Вы указали следующие шаблоны префиксов хоста и пути для вложений Link , которые Classroom должен попытаться обновить до вложения надстройки :
   • Хост — example.com , а префикс пути — /quiz .
2. Преподаватель создает новое объявление, задание или материал в рамках одного из своих курсов. Например, itemId=234 , itemType=courseWork и courseId=123 .
3. Учитель вставляет ссылку https://example.com/quiz/5678 в диалоговое окно Link Attachment, которое соответствует указанному вами шаблону URL. Затем учителю предлагается обновить Link до дополнительного вложения.

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 можно закрыть из инструмента обучения, отправив 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

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

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

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

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

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

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

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

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

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

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

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