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
itemId値はAnnouncementの識別子です。このアタッチメントが接続されている
CourseWorkまたはCourseWorkMaterial。すべての iframe に付属。
- アイテムの型
itemType値は、このリソースが含まれているリソースタイプを添付されています。渡される文字列値は、
"announcements"、"courseWork"、"courseWorkMaterials"のいずれかです。すべての iframe に付属。
- 添付ファイル ID
attachmentId値はアタッチメントの識別子です。teacherViewUriiframe、studentViewUriiframe、studentWorkReviewUriiframe に含まれています。- 送信 ID
submissionId値は生徒の提出物の識別子ですが、特定の課題に対する生徒の提出物を識別するためにattachmentIdと組み合わせて使用する必要があります。studentWorkReviewUriに含まれています。
- アドオン トークン
addOnToken値は、認証トークンの作成に使用される認証トークンで、addOnAttachments.createを呼び出してアドオンを作成します。- アップグレードする URL
urlToUpgrade値が存在する場合は、教師が課題にリンクの添付ファイルを含め、それをアドオンの添付ファイルにアップグレードすることに合意した場合。この機能をまだ構成していない場合は、アドオン アタッチメントへのリンクのアップグレードに関するガイドをご覧ください。
リンク アップグレード iframe に付属。
ログイン関連のパラメータ
login_hint クエリ パラメータは、アドオンのウェブページにアクセスした Classroom ユーザーに関する情報を提供します。このクエリ パラメータは、iframe の src URL で提供されます。エンドユーザーがスムーズにログインできるように、ユーザーが以前にアドオンを使用したことがあれば送信されます。このクエリ パラメータは、アドオンの実装で処理する必要があります。
- ログインのヒント
login_hintは、ユーザーの Google Cloud ID の一意の識別子アカウント] をタップします。ユーザーが初めてアドオンにログインした後、同じユーザーがアドオンにアクセスするたびに
login_hintパラメータが渡されます。login_hintパラメータには、次の 2 つの用途があります。- 認証フロー中に
login_hint値を渡すことで、ログイン ダイアログが表示されたときにユーザーが認証情報を入力する必要がなくなります。ユーザーは自動的にログインされません。 - ユーザーがログインした後、このパラメータを使用して、すでにアドオンにログイン済みのユーザーと値を比較します。一致するものが見つかった場合は、ユーザーをログインしたままにして、ログインフローを表示しないようにすることができます。パラメータがログイン中のユーザーと一致しない場合は、Google ブランドのログインボタンを使用してログインするようユーザーに促します。
すべての iframe に付属。
- 認証フロー中に
添付ファイルの検出 iframe
| ディメンション | 説明 |
|---|---|
| 必須 | ○ |
| URI | アドオンのメタデータで提供 |
| クエリ パラメータ | courseId、itemId、itemType、addOnToken、login_hint。 |
| 高さ | トップヘッダーは、ウィンドウの高さの 80% から 60 ピクセルを差し引いた値 |
| 幅 | 1,600 ピクセル以下 ウィンドウの幅が 600 ピクセル以下の場合は 90% ウィンドウの幅が 600 ピクセルを超える場合はウィンドウ幅 80% |
添付ファイルの検出シナリオの例
- Classroom アドオンは、添付ファイルの検出 URI として
https://example.com/addonを使用して Google Workspace Marketplace に登録されます。 - 教師がこのアドオンをインストールして、いずれかのコースに新しいお知らせ、課題、資料を作成します。たとえば、
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、itemId、itemType、attachmentId、login_hint。 |
| 高さ | トップヘッダーのウィンドウの高さ 100% から 140 ピクセルを引いた値 |
| 幅 | ウィンドウ幅 100% |
studentWorkReviewUri iframe
| ディメンション | 説明 |
|---|---|
| 必須 | いいえ（アクティビティ タイプの添付ファイルかどうかを判断します） |
| URI | studentWorkReviewUri |
| クエリ パラメータ | courseId、itemId、itemType、attachmentId、submissionId、login_hint。 |
| 高さ | トップヘッダーのウィンドウの高さ 100% から 168 ピクセルを引いた値 |
| 幅 | ウィンドウの幅 100% からサイドバーの幅を引いた値<> は、開いた状態では 312 ピクセル、折りたたんだ状態では 56 ピクセル |
iframe のアップグレードをリンク
| ディメンション | 説明 |
|---|---|
| 必須 | はい。アドオンでアドオン添付ファイルへのリンクのアップグレードがサポートされている場合は可能です。 |
| URI | アドオンのメタデータで提供 |
| クエリ パラメータ | courseId、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&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678に設定してリンク アップグレード iframe が起動します。iframe で渡されたクエリ パラメータを評価し、
CreateAddOnAttachmentエンドポイントを呼び出します。なお、urlToUpgradeクエリ パラメータは、iframe に渡すときに URI エンコードされます。パラメータを元の形式で取得するには、デコードする必要があります。たとえば、JavaScript ではdecodeURIComponent()関数を使用できます。リンクからアドオンの添付ファイルを作成したら、Classroom に
postMessageを送信して iframe を閉じます。
iframe を閉じる
ペイロード {type: 'Classroom', action: 'closeIframe'} を含む postMessage を送信することで、学習ツールから iframe を閉じることができます。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 に示すように、教師がポップ内で [今すぐ試す] を選択すると、アドオンの Attachment Discovery iframe にリダイレクトされます。