Classroom アドオンは iframe 内に読み込まれ、エンドユーザーにシームレスで便利なユーザー エクスペリエンスを提供します。iframe には 4 種類あります。各 iframe の目的と外観については、ユーザー ジャーニー ディレクトリの iframe のページをご覧ください。
iframe のセキュリティ ガイドライン
パートナーには、業界のベスト プラクティスに従って iframe を保護することが求められます。iframe を保護するために、Google のセキュリティ チームは以下を推奨しています。
HTTPS が必須です。TLS 1.2 以降を使用し、HTTP Strict Transport Security を有効にすることを強くおすすめします。Strict Transport Security については、MDN の関連記事をご覧ください。
厳格なコンテンツ セキュリティ ポリシーを有効にします。OWASP 記事と、関連するコンテンツ セキュリティ ポリシー MDN 記事をご覧ください。
[Secure cookie 属性] を有効にします。HttpOnly 属性と、関連する Cookie MDN の記事をご覧ください。
iframe URI の設定
添付ファイルのセットアップ URI は、添付ファイルの検出 iframe が読み込むものであり、教師が Classroom の投稿にアドオンの添付ファイルを作成するフローを開始します。Google Cloud プロジェクト コンソールで設定できます。この URI は、Google Cloud プロジェクトの [API とサービス] > [Google Workspace Marketplace SDK] > [アプリの構成] ページで設定します。
許可されたアタッチメント URI 接頭辞は、*.addOnAttachments.create メソッドと *.addOnAttachments.patch メソッドを使用して AddOnAttachment に設定された URI を検証するために使用されます。この検証はリテラル文字列の接頭辞の一致であり、現時点ではワイルドカードを使用できません。
クエリ パラメータ
iframe は重要な情報をクエリ パラメータとしてアドオンに渡します。パラメータには、添付ファイル関連のパラメータとログイン関連のパラメータの 2 つのカテゴリがあります。
添付ファイル関連のパラメータ
添付ファイル関連のパラメータは、コース、課題、アドオンの添付ファイル、学生の提出物、承認トークンに関する情報をアドオンに提供します。
- コース ID
courseId値はコースの識別子です。すべての iframe に搭載されています。
- 投稿 ID（サポート終了）
postId値は、この添付ファイルが添付されている投稿（お知らせ、コースの課題、コースの課題）の識別子です。すべての iframe に搭載されています。
- アイテム ID
itemId値は、このアタッチメントがアタッチされているAnnouncement、CourseWork、またはCourseWorkMaterialの識別子です。すべての iframe に搭載されています。
- アイテムの型
itemType値は、このアタッチメントが接続されているリソースタイプを識別します。渡される文字列値は、"announcements"、"courseWork"、"courseWorkMaterials"のいずれかです。すべての iframe に搭載されています。
- 添付ファイル ID
attachmentId値はアタッチメントの識別子です。teacherViewUri、studentViewUri、studentWorkReviewUriiframe に搭載されています。- 送信 ID
submissionId値は生徒の課題の識別子ですが、attachmentIdと組み合わせて使用すると、特定の課題での生徒の提出物を識別できるようになります。studentWorkReviewUriに含まれています。
- アドオン トークン
addOnToken値は、アドオンを作成するためにaddOnAttachments.create呼び出しを行うために使用される認証トークンです。- アップグレードする URL
urlToUpgradeの値が存在する場合は、教師が課題にリンク添付ファイルを含め、それをアドオン添付ファイルへのアップグレードに同意していることを意味します。この機能をまだ構成していない場合は、アドオン アタッチメントへのリンクのアップグレードに関するガイドで詳細をご確認ください。リンク アップグレード iframe に付属。
ログイン関連のパラメータ
login_hint クエリ パラメータは、アドオンのウェブページにアクセスしている Classroom ユーザーに関する情報を提供します。このクエリ パラメータは、iframe の src URL で提供されます。エンドユーザーがログインしにくくなるよう、ユーザーが以前にアドオンを使用したことがあれば送信されます。このクエリ パラメータは、アドオンの実装で処理する必要があります。
- ログインのヒント
login_hintは、ユーザーの Google ID を表すアカウント] をタップします。ユーザーが初めてアドオンにログインした後、同じユーザーがアドオンにアクセスするたびに
login_hintパラメータが渡されます。login_hintパラメータの用途として次の 2 つが考えられます。- ログイン ダイアログが表示されたときにユーザーが認証情報を入力しなくても済むように、認証フロー中に
login_hint値を渡します。ユーザーは自動的にログインされません。 - ユーザーがログインした後、このパラメータを使用して、すでにアドオンにログインしているユーザーと値を比較します。一致するものが見つかった場合は、ユーザーをログインしたままにして、ログインフローを表示しないようにできます。パラメータがログイン ユーザーと一致しない場合は、Google ブランドのログインボタンでログインするようユーザーに促します。
すべての iframe に搭載されています。
- ログイン ダイアログが表示されたときにユーザーが認証情報を入力しなくても済むように、認証フロー中に
添付ファイルの検出 iframe
| ディメンション | 説明 |
|---|---|
| 必須 | ○ |
| URI | アドオンのメタデータで提供 |
| クエリ パラメータ | courseId、postId（非推奨）、itemId、itemType、addOnToken、login_hint。 |
| 高さ | ウィンドウの高さ 80% から上部のヘッダーの 60 ピクセルを引いた値 |
| 幅 | 最大 1,600 ピクセル ウィンドウ幅 600 ピクセル以下の場合はウィンドウ幅 90% ウィンドウ幅 600 ピクセル超の場合はウィンドウ幅 80% |
添付ファイルの検出シナリオの例
- Classroom アドオンが Google Workspace Marketplace に、添付ファイル検出 URI
https://example.com/addonが登録されます。 - 教師がこのアドオンをインストールして、コース内に新しいお知らせ、課題、資料を作成します。たとえば、
itemId=234、itemType=courseWork、courseId=123です。 - その項目の設定時に、教師は新しくインストールしたアドオンを添付ファイルとして選択します。
- Classroom により、src URL が
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456に設定された iframe が作成されます。- 教師が iframe 内で作業を行い、添付ファイルを選択する。
- 添付ファイルを選択すると、アドオンによって
postMessageが Classroom に送信され、iframe が閉じます。
TeacherViewUri と studentViewUri の iframe
| ディメンション | 説明 |
|---|---|
| 必須 | ○ |
| 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
| ディメンション | 説明 |
|---|---|
| 必須 | はい。アドオンの添付ファイルへのリンクのアップグレードがアドオンでサポートされている場合は可能です。 |
| URI | アドオンのメタデータで提供 |
| クエリ パラメータ | courseId、postId（非推奨）、itemId、itemType、addOnToken、urlToUpgrade、login_hint。 |
| 高さ | ウィンドウの高さ 80% から上部のヘッダーの 60 ピクセルを引いた値 |
| 幅 | 最大 1,600 ピクセル ウィンドウ幅 600 ピクセル以下の場合はウィンドウ幅 90% ウィンドウ幅 600 ピクセル超の場合はウィンドウ幅 80% |
リンクのアップグレードのシナリオ例
- Classroom アドオンは、リンク アップグレード URI
https://example.com/upgradeで登録されます。Classroom がアドオンの添付ファイルへのアップグレードを試みるリンク添付ファイルに対して、以下のホストとパスの接頭辞のパターンが提供されています。- ホストは
example.comで、パスの接頭辞は/quizです。
- ホストは
- 教師がコース内に新しいお知らせ、課題、資料を作成します。たとえば、
itemId=234、itemType=courseWork、courseId=123です。 - 教師が [リンクの添付ファイル] ダイアログに、指定した URL パターンに一致するリンク
https://example.com/quiz/5678を貼り付けます。リンクをアドオンの添付ファイルにアップグレードするよう求められます。 Classroom で、URL が
https://example.com/upgrade?courseId=123&postId=234&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678に設定されたリンク アップグレード iframe が起動します。iframe に渡されたクエリ パラメータを評価し、
CreateAddOnAttachmentエンドポイントを呼び出します。urlToUpgradeクエリ パラメータは、iframe に渡される際に URI エンコードされます。パラメータを元の形式で取得するには、パラメータをデコードする必要があります。たとえば、JavaScript にはdecodeURIComponent()関数があります。リンクからアドオンの添付ファイルが正常に作成されたら、
postMessageを Classroom に送信して iframe を閉じます。
iframe を閉じる
iframe は、ペイロード {type: 'Classroom', action: 'closeIframe'} を含む postMessage を送信することで学習ツールから閉じることができます。Classroom は、最初に開かれた URI に対応する host_name+port からのみ、この postMessage を受け入れます。
<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 イベントを送信するページのドメインとポートは、iframe の起動に使用された URI と同じドメインとポートにする必要があります。同じでない場合、メッセージは無視されます。この問題を回避するには、postMessage イベントを送信するだけの元のドメインのページにリダイレクトします。
新しいタブで iframe を閉じる
クロスドメイン保護を使用していると、こうした動作は回避されます。この問題を回避するには、iframe と新しいタブ間の通信を独自に処理し、最終的に postMessage 終了イベントの発行を iframe に任せるという方法があります。なお、今後ユーザーがこの方法でタブを作成しないように、「パートナー名で開く」ハイパーリンクは削除されます。
制限
すべての iframe は次のサンドボックス属性で開かれます。
allow-popupsallow-popups-to-escape-sandboxallow-formsallow-scriptsallow-storage-access-by-user-activationallow-same-origin
および次の機能ポリシー
allow="microphone *"
サードパーティ Cookie のブロック
サードパーティ Cookie のブロックにより、iframe 内でログイン済みセッションを維持することが困難になります。さまざまなブラウザで Cookie がブロックされている現在の状態については、https://www.cookiestatus.com をご覧ください。もちろん、この問題は Google Classroom アドオンに固有のものではなく、サードパーティで iframe を使用するすべてのウェブサイトに影響します。多くのパートナーがすでにこの問題に遭遇しています。
一般的な回避策は次のとおりです。
- 新しいタブを開き、ファーストパーティ コンテキストで Cookie を作成します。一部のブラウザでは、ファーストパーティのコンテキストで作成された Cookie へのアクセスを、サードパーティのコンテキスト内で許可できます。
- サードパーティ Cookie を許可するようユーザーに依頼します。これは、すべてのユーザーが常に可能であるとは限りません。
- Cookie に依存しないシングルページ ウェブ アプリケーションを設計する。
今後のバージョンのブラウザでは、Cookie の制限がさらに強化される予定です。機能リクエストを作成して、パートナーが必要とする負荷を軽減する方法について Google にフィードバックを送信します。
URL 正規表現を使用してアドオンを検出できるようにする
教師は、リンクを添付した課題を作成することがよくあります。アドオンの使用を促進するために、アドオンでアクセスできるリソースの URL に一致する正規表現を指定できます。正規表現に一致するリンクを添付すると、アドオンを試すよう促すダイアログ（閉じることが可能）が表示されます。このダイアログは、アカウントにすでにアドオンがインストールされている場合にのみ表示されます。
この動作を教師に提供する場合は、Google コンタクトに適切な正規表現を指定します。指定した正規表現の範囲が広すぎる場合、または別のアドオンと競合する場合は、制限や区別を強めるように変更されることがあります。
図 1.教師が新しい課題に添付した
リンクを選択しています
図 2.教師がサードパーティのソースからリンクを
貼り付けているところ教師はサードパーティの
Classroom アドオンをインストール済みです
図 3.貼り付けたリンクがサードパーティのデベロッパーによって指定された正規表現と一致する場合に、教師に表示されるインタラクティブなダイアログ。
教師がポップで [今すぐ試す] を選択すると（図 3 を参照）、アドオンの添付ファイルの検出 iframe にリダイレクトされます。