iframe とクエリ パラメータの詳細

Classroom アドオンは iframe 内に読み込まれるため、エンドユーザーにシームレスで便利なユーザー エクスペリエンスを提供できます。iframe には 5 つのタイプがあります。各 iframe の目的と外観の概要については、ユーザー ジャーニー ディレクトリの iframe ページをご覧ください。

iframe のセキュリティに関するガイドライン

デベロッパーは、業界のベスト プラクティスに沿って iframe を保護する必要があります。ただし、有効な認証情報があることを確認し、コース内のユーザーの役割を正しく識別できるように、ユーザーフローにも特定の API 操作を組み込む必要があります。

サーバー アプリケーションの構成

iframe を保護するには、次のサーバー構成をおすすめします。

• HTTPS が必要です。TLS 1.2 以降を使用し、HTTP Strict Transport Security（HSTS）を有効にすることを強くおすすめします。Strict Transport Security に関する関連する MDN の記事をご覧ください。
• 厳格なコンテンツ セキュリティ ポリシー（厳格な CSP）を有効にします。OWASP の記事と、関連する コンテンツ セキュリティ ポリシーの MDN の記事をご覧ください。
• Secure cookie 属性を有効にします。HttpOnly 属性と、関連する Cookie の MDN 記事をご覧ください。

クエリ パラメータ

iframe は、重要な情報をクエリ パラメータとしてアドオンに渡します。パラメータには、アタッチメント関連とログイン関連の 2 つのカテゴリがあります。

アタッチメント関連のパラメータ

アタッチメント関連のパラメータは、コース、課題、アドオン アタッチメント、生徒の提出、承認トークンに関する情報をアドオンに提供します。

コース ID

courseId の値はコースの識別子です。

すべての iframe に含まれます。

アイテム ID

itemId 値は Announcement の識別子です。

CourseWork、またはこの添付ファイルが接続されている CourseWorkMaterial。

すべての iframe に含まれます。

アイテムの型

itemType 値は、この

添付されています。渡される文字列値は、"announcements"、"courseWork"、"courseWorkMaterials" のいずれかです。

すべての iframe に含まれます。

添付ファイル ID

attachmentId 値は、アタッチメントの識別子です。

teacherViewUri、studentViewUri、studentWorkReviewUri iframe に含まれています。

提出 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 つの用途があります。

1. 認証フロー中に login_hint 値を渡して、ログイン ダイアログが表示されたときにユーザーが認証情報を入力しなくて済むようにします。ユーザーは自動的にログインされません。
2. ユーザーがログインした後、このパラメータを使用して、アドオンにすでにログインしているユーザーの値と比較します。一致が見つかった場合は、ユーザーをログインしたままにして、ログイン フローを表示しないようにできます。パラメータがログイン中のユーザーのいずれとも一致しない場合は、Google ブランドのログインボタンを使用してログインするようユーザーに促します。

すべての iframe に含まれます。

添付ファイルの検出 iframe

添付ファイル検出のシナリオの例

1. Classroom アドオンが Google Workspace Marketplace に登録され、アタッチメント検出 URI が https://example.com/addon です。
2. 教師がこのアドオンをインストールし、いずれかのコース内に新しいお知らせ、課題、または教材を作成します。たとえば、itemId=234、itemType=courseWork、courseId=123 です。
3. そのアイテムを構成する際に、教師は新しくインストールしたアドオンを添付として選択します。
4. Classroom は、src URL が https://example.com/addon?courseId=123&itemId=234&itemType=courseWork&addOnToken=456 に設定された iframe を作成します。
   1. 教師が iframe 内で作業を行い、添付ファイルを選択します。
5. 添付ファイルを選択すると、アドオンは Classroom に postMessage を送信して iframe を閉じます。

teacherViewUri と studentViewUri の iframe

studentWorkReviewUri iframe

リンクのアップグレード iframe

リンク アップグレード シナリオの例

1. Classroom アドオンが、リンク アップグレード URI https://example.com/upgrade で登録されています。Classroom がアドオン アタッチメントへのアップグレードを試行するリンク アタッチメントに、次のホストとパスの接頭辞パターンを指定しました。
   • ホストは example.com で、パスの接頭辞は /quiz です。
2. 教師がコース内で新しいお知らせ、課題、または資料を作成します。たとえば、itemId=234、itemType=courseWork、courseId=123 です。
3. 教師は、指定した URL パターンに一致するリンク https://example.com/quiz/5678 を [リンク アタッチメント] ダイアログに貼り付けます。リンクをアドオン添付にアップグレードするよう求めるメッセージが表示されます。

4. Classroom は、URL が https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678 に設定されたリンク アップグレード iframe を起動します。

5. iframe で渡されたクエリ パラメータを評価し、CreateAddOnAttachment エンドポイントを呼び出します。urlToUpgrade クエリ パラメータは、iframe で渡されるときに URI エンコードされます。パラメータをデコードして元の形式で取得する必要があります。たとえば、JavaScript には decodeURIComponent() 関数があります。

6. リンクからアドオンの添付ファイルを正常に作成したら、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-popups
• allow-popups-to-escape-sandbox
• allow-forms
• allow-scripts
• allow-storage-access-by-user-activation
• allow-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 にリダイレクトされます。