Classroom アドオンは iframe 内に読み込まれ、 シームレスな体験をエンドユーザーに提供しますChronicle には 4 つの iframe タイプユーザー ジャーニー ディレクトリの iframe ページをご覧ください。 ここでは、各 iframe の目的と外観について概要を説明します。
iframe セキュリティ ガイドライン
パートナーには、業界のベスト プラクティスに従って iframe を保護することが求められます。 iframe を保護するために、Google のセキュリティ チームでは次のことを推奨しています。
HTTPS が必須です。そのため、TLS 1.2 以降と HTTP Strict Transport Security を有効にする。関連する MDN Strict Transport Security に関する記事をご覧ください。
[厳格なコンテンツ セキュリティ ポリシー] を有効にします。こちらの OWASP の記事と、関連するコンテンツ セキュリティ ポリシー MDN の記事をご覧ください。
Secure cookie 属性を有効にします。HttpOnly 属性と 関連する Cookie MDN の記事をご覧ください。
iframe URI 設定
Attachment Setup URI は、Attachment Discovery iframe で読み込まれるものです。 ここから、教師がアドオンの添付ファイルを作成するフローを Classroom への投稿。Google Cloud プロジェクト コンソールで設定できます。 Google Cloud プロジェクトの API でこの URI を設定し、サービス > Google Workspace Marketplace SDK >[App Configuration] ページ。
許可されるアタッチメント URI 接頭辞は、Terraform で設定された URI を検証するために使用されます。
AddOnAttachment（*.addOnAttachments.create と
*.addOnAttachments.patch メソッド。検証はリテラル文字列の接頭辞
ワイルドカードは使用できません。
クエリ パラメータ
iframe は、重要な情報をクエリ パラメータとしてアドオンに渡します。 パラメータには、添付ファイル関連とログイン関連という 2 つのカテゴリがあります。 あります。
添付ファイル関連のパラメータ
添付ファイル関連のパラメータは、アドオンに添付ファイルに関する情報を提供します。 コース、課題、アドオンの添付ファイル、生徒の提出物、 あります。
- コース ID
courseId値はコースの識別子です。すべての iframe に付属。
- アイテム ID
itemId値はAnnouncementの識別子です。このアタッチメントに関連付けられている
CourseWorkまたはCourseWorkMaterialあります。すべての iframe に付属。
- アイテムの型
itemType値は、このリソースが含まれているリソースタイプを添付されています。渡される文字列値が
"announcements"のいずれかである。"courseWork"または"courseWorkMaterials"。すべての iframe に付属。
- 添付ファイル ID
attachmentId値はアタッチメントの識別子です。- 送信 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% ワイド ウィンドウ幅の 80%（ウィンドウ > のとき）幅 600 ピクセル |
添付ファイルの検出シナリオの例
- Classroom アドオンが Google Workspace に登録されている
添付ファイルの検出 URI が
https://example.com/addonの Marketplace。 - 教師がこのアドオンをインストールして、新しいお知らせ、課題、または投稿を作成します。
受講者の能力を証明できます。例:
itemId=234itemType=courseWorkとcourseId=123。 - そのアイテムの設定中に、新しくインストールしたアドオンを選択します。 。
- Classroom によって、ソース URL が「
https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456。- 教師が 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 ピクセル、折りたたみ時は 56 ピクセル |
iframe のアップグレードをリンク
| ディメンション | 説明 |
|---|---|
| 必須 | ○（アドオン添付ファイルへのリンクのアップグレード） ご確認ください |
| URI | アドオンのメタデータで提供 |
| クエリ パラメータ | courseId さん、itemId さん、itemType さん、
addOnToken、urlToUpgrade、login_hint。 |
| 高さ | トップヘッダーは、ウィンドウの高さの 80% から 60 ピクセルを差し引いた値 |
| 幅 | 1,600 ピクセル以下 ウィンドウの幅が 600 ピクセル以下の場合は 90% ワイド ウィンドウ幅の 80%（ウィンドウ > のとき）幅 600 ピクセル |
リンク アップグレードのシナリオの例
- Classroom アドオンはリンク アップグレード URI で登録されています。
https://example.com/upgrade。次のホストとパスが指定されています Classroom で追加すべきリンクの添付ファイルの接頭辞パターン アドオンの添付ファイルへのアップグレードを試みる: <ph type="x-smartling-placeholder">- </ph>
- ホストは
example.comで、パスの接頭辞は/quizです。
- ホストは
- 教師がいずれかの期間内に新しいお知らせ、課題、資料を作成すると、
説明します。たとえば、
itemId=234、itemType=courseWork、courseId=123。 - 教師がリンク
https://example.com/quiz/5678を [リンク] に貼り付けます。 添付ファイル ダイアログが表示されます。この教師は アドオン添付ファイルへのリンクのアップグレードを求めるメッセージが表示されます。 Classroom で、URL が設定された Link Upgrade iframe が起動される から
https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678。iframe で渡されたクエリ パラメータを評価し、
CreateAddOnAttachmentエンドポイント。urlToUpgradeクエリは、 パラメータは、iframe に渡すときに URI エンコードされます。デコード関数を パラメータを使って元の形式で取得します。たとえば JavaScript ではdecodeURIComponent()関数を使用します。リンクからアドオンの添付ファイルが正常に作成されると、
postMessageで Classroom に移動し、iframe を閉じます。
iframe を閉じる
次のように postMessage を送信することで、学習ツールから iframe を閉じることができます。
ペイロード {type: 'Classroom', action: 'closeIframe'}。
Classroom は、host_name+port からこの postMessage のみを受け付けます。
開かれた元の URI に対応する 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 イベントを送信するページのドメインとポートは同じである必要があります。
domain+port は 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 内で確認できます。詳しくは、https://www.cookiestatus.com さまざまなブラウザでの Cookie ブロックの現状もちろん、これは この問題は Google Classroom アドオンに固有のものではなく、 使用できます。多くのパートナー様はすでにこの問題に遭遇しています。
一般的な回避策は次のとおりです。
- 新しいタブを開いてファーストパーティ コンテキストの Cookie を作成します。一部のブラウザ 作成時にファーストパーティ コンテキストで作成された Cookie に サードパーティ コンテキストで識別されます。
- サードパーティ Cookie を許可するようにユーザーに依頼します。これが常に可能とは限りません 共有することもできます。
- Cookie に依存しない単一ページのウェブ アプリケーションを設計する。
今後のブラウザ バージョンでは、Cookie の制限がさらに強化される予定です。作成 機能リクエスト: 必要なリフトを減らす方法について Google にフィードバックを送信できます 。
URL 正規表現を使用してアドオンを検出できるようにする
教師は頻繁に課題を作成し、リンクを添付します。使用を促進するため 指定すると、リソースの URL と照合する正規表現を アドオンでアクセスできます1 つに一致するリンクを添付している教師 正規表現を使用して、会話の試行を促すダイアログが 追加します。このダイアログは、アドオンがすでにインストールされている できます。
教師に対してこのような行動を実践したい場合は、Google 適切な正規表現を使用して連絡先を取得します。正規表現で 範囲が広すぎる場合や、他のアドオンと競合する場合は、 より限定的または区別しやすいように変更します。
図 1.リンクを選択している教師
新しい課題に添付します。
図 2.サードパーティのリンクを貼り付ける教師
あります。教師は、すでにサードパーティ製の
Classroom アドオン。
図 3.表示されるインタラクティブ ダイアログ
正規表現で指定された正規表現に一致する場合に、教師に公開されます。
サードパーティ開発者に通知されます。
教師が [今すぐ試す] を選択した場合図 3 に示すように アドオンの添付ファイルの検出 iframe にリダイレクトされます。