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

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

iframe のセキュリティ ガイドライン

デベロッパーは、業界のベスト プラクティスに沿って iframe を保護する必要があります。また、有効な認証情報を持っていることと、コース内のユーザーのロールを正しく識別できることを確認するために、ユーザーフローに特定の API インタラクションを組み込む必要があります。

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

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

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

クエリ パラメータ

iframe は、重要な情報をクエリ パラメータ としてアドオンに渡します。 パラメータには、添付ファイル関連のパラメータとログイン関連のパラメータの 2 種類があります。

添付ファイル関連のパラメータ

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

コース ID

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

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

商品アイテム ID

itemId の値は、この添付ファイルが添付されている Announcement、 CourseWork、または CourseWorkMaterial の識別子です。

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

アイテムの型

itemType の値は、この添付ファイルが添付されているリソースタイプを識別します。渡される文字列値は、"announcements"、 "courseWork"、または "courseWorkMaterials" のいずれかです。

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

添付ファイル ID

attachmentId の値は、添付ファイルの識別子です。

teacherViewUri、studentViewUri、 studentWorkReviewUri の iframe に含まれます。

提出物 ID

submissionId の値は生徒の課題の識別子ですが、特定の課題の生徒の課題を識別するには、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. 添付ファイルを選択すると、アドオンは postMessage を Classroom に送信して 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 が に設定されたリンクのアップグレード iframe を起動します https://example.com/upgrade?courseId=123&itemId=234&itemType=courseWork&addOnToken=456&urlToUpgrade=https%3A%2F%2Fexample.com%2Fquiz%2F5678。

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

6. リンクからアドオンの添付ファイルが正常に作成されたら、 postMessage を Classroom に送信して iframe を閉じます。

iframe を閉じる

iframe は、postMessage を送信することで、学習ツールから閉じることができます。 ペイロード {type: 'Classroom', action: 'closeIframe'} を含む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 が close 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 の担当者に適切な正規表現を提供してください 。指定した正規表現が広すぎる場合や、別のアドオンと競合する場合は、より制限的または明確になるように変更されることがあります。

[Figure 1.]教師が新しい課題にリンクの添付ファイルを選択しています。

図 2.教師がサードパーティのソースからリンクを貼り付けています。教師はすでにサードパーティの Classroom アドオンをインストールしています。

図 3.貼り付けたリンクがサードパーティ デベロッパーが指定した正規表現と一致した場合に教師に表示されるインタラクティブ ダイアログ。

教師が図 3 のポップアップで [今すぐ試す] を選択すると、 アドオンの [添付ファイルの検出 iframe] にリダイレクトされます。