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値は、アタッチメントの識別子です。teacherViewUri、studentViewUri、studentWorkReviewUriiframe に含まれています。- 提出 ID
submissionId値は生徒の課題の ID ですが、特定の課題の生徒の課題を識別するにはattachmentIdと組み合わせて使用する必要があります。studentWorkReviewUriに含まれています。
- アドオン トークン
addOnToken値は、認証トークンの作成に使用される認証トークンで、addOnAttachments.createを呼び出して、アドオンを作成します。アタッチメント検出 iframe と リンクのアップグレード iframe に含まれます。
- アップグレードする URL
urlToUpgrade値が存在する場合は、教師が課題にリンク添付を追加し、アドオン添付にアップグレードすることに同意している。この機能をまだ設定していない場合は、アドオン アタッチメントへのリンクのアップグレードに関するガイドで詳細をご確認ください。
リンク アップグレード iframe に含まれています。
ログイン関連のパラメータ
login_hint クエリ パラメータには、アドオンのウェブページにアクセスした Classroom ユーザーに関する情報が提供されます。このクエリ パラメータは、iframe src URL で指定します。ユーザーがアドオンを以前に使用したことがあり、エンドユーザーのログイン手間を軽減するために送信されます。このクエリ パラメータは、アドオンの実装で処理する必要があります。
- ログイン ヒント
login_hintは、ユーザーの Googleアカウント] をタップします。ユーザーがアドオンに初めてログインすると、同じユーザーがアドオンにアクセスするたびに
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 アドオンが 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 内で作業を行い、添付ファイルを選択します。
- 添付ファイルを選択すると、アドオンは Classroom に
postMessageを送信して 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 と新しいタブ間の通信を独自に処理し、最終的に iframe に閉じる postMessage イベントの発行を任せる方法があります。なお、今後ユーザーがこの方法でタブを作成しないように、[パートナー名で開く] ハイパーリンクは廃止されます。
制限事項
すべての 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 にリダイレクトされます。