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

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

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

パートナーは、業界のベスト プラクティスに沿って iframe を保護することが期待されます。iframe を保護するため、Google のセキュリティ チームは次の方法をおすすめします。

iframe URI の構成

アタッチメントの設定 URI は、アタッチメント検出 iframe が読み込む URI です。教師は、Classroom の投稿にアドオンの添付ファイルを作成するフローをここで開始します。これは Google Cloud プロジェクト コンソールで設定できます。この URI を、Google Cloud プロジェクトの [API とサービス] > [Google Workspace Marketplace SDK] > [アプリの構成] ページで設定します。

iframe URI の構成

許可されるアタッチメント 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 値は、アタッチメントの識別子です。

teacherViewUristudentViewUristudentWorkReviewUri 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

ディメンション 説明
必須 はい
URI アドオンのメタデータで指定
クエリ パラメータ courseIditemIditemTypeaddOnTokenlogin_hint
高さ ウィンドウの高さの 80% から上部ヘッダーの 60 ピクセルを差し引いた値
最大 1,600 ピクセル
ウィンドウの幅が 600 ピクセル以下の場合はウィンドウ幅の 90%
ウィンドウの幅が 600 ピクセルを超える場合はウィンドウ幅の 80%

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

  1. Classroom アドオンが Google Workspace Marketplace に登録され、アタッチメント検出 URI が https://example.com/addon です。
  2. 教師がこのアドオンをインストールし、いずれかのコース内に新しいお知らせ、課題、または教材を作成します。たとえば、itemId=234itemType=courseWorkcourseId=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

ディメンション 説明
必須 はい
URI teacherViewUri または studentViewUri
クエリ パラメータ courseIditemIditemTypeattachmentIdlogin_hint
高さ ウィンドウの高さの 100% から上部ヘッダーの 140 ピクセルを差し引いた値
ウィンドウの幅 100%

studentWorkReviewUri iframe

ディメンション 説明
必須 いいえ(アクティビティ タイプのアタッチメントかどうかを判断)
URI studentWorkReviewUri
クエリ パラメータ courseIditemIditemTypeattachmentIdsubmissionIdlogin_hint
高さ ウィンドウの高さの 100% から上部ヘッダーの 168 ピクセルを差し引いた値
ウィンドウ幅の 100% からサイドバーの幅を差し引いた値<> サイドバーは、展開時は 312 ピクセル、閉じると 56 ピクセル

ディメンション 説明
必須 はい。アドオンでリンクをアドオンの添付ファイルにアップグレードがサポートされている場合。
URI アドオンのメタデータで指定
クエリ パラメータ courseIditemIditemTypeaddOnTokenurlToUpgradelogin_hint
高さ ウィンドウの高さの 80% から上部ヘッダーの 60 ピクセルを差し引いた値
最大 1,600 ピクセル
ウィンドウの幅が 600 ピクセル以下の場合はウィンドウ幅の 90%
ウィンドウの幅が 600 ピクセルを超える場合はウィンドウ幅の 80%
  1. Classroom アドオンが、リンク アップグレード URI https://example.com/upgrade で登録されています。Classroom がアドオン アタッチメントへのアップグレードを試行するリンク アタッチメントに、次のホストとパスの接頭辞パターンを指定しました。
    • ホストは example.com で、パスの接頭辞は /quiz です。
  2. 教師がコース内で新しいお知らせ、課題、または資料を作成します。たとえば、itemId=234itemType=courseWorkcourseId=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 のブロックにより、iframe でログイン セッションを維持することが難しくなることにご注意ください。さまざまなブラウザでの Cookie ブロックの現在の状態については、https://www.cookiestatus.com をご覧ください。もちろん、この問題は Google Classroom アドオンに固有のものではなく、サードパーティの iframe を使用するすべてのウェブサイトに影響します。多くのパートナーがすでにこの問題に遭遇しています。

一般的な回避策は次のとおりです。

  • 新しいタブを開き、ファーストパーティ コンテキストで Cookie を作成します。一部のブラウザでは、サードパーティ コンテキストでファーストパーティ コンテキストで作成された Cookie へのアクセスを許可しています。
  • サードパーティ Cookie を許可するようお客様に伝えます。ただし、すべてのユーザーでこの方法が利用できるとは限りません。
  • Cookie に依存しない単一ページ ウェブ アプリケーションを設計する。

今後のブラウザ バージョンでは、Cookie の制限がさらに強化される予定です。機能リクエストを作成して、パートナーが必要な費用を削減する方法について Google にフィードバックを送信します。

URL 正規表現を使用してアドオンの見つけやすさを有効にする

教師は、リンクの添付ファイルを含む課題を頻繁に作成します。アドオンの使用を促進するには、アドオンでアクセスできるリソースの URL に一致する正規表現を指定します。教師が正規表現のいずれかに一致するリンクを添付すると、閉じることができるダイアログが表示され、アドオンの試用を促されます。ダイアログは、アカウントにアドオンがすでにインストールされている場合にのみ表示されます。

教師にこの動作を提供するには、適切な正規表現を Google の担当者に提供してください。指定した正規表現が広範すぎる場合や、別のアドオンと競合する場合は、より制限された正規表現または明確な正規表現に変更されることがあります。

教師がリンク アタッチメントを選択している様子 図 1. 新しい課題にリンク アタッチメントを選択する教師。

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

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

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