リンクの添付ファイルを Classroom アドオンの添付ファイルにアップグレードする

教師が Classroom にサードパーティのコンテンツを追加する 1 つの方法は、課題の作成ページにリンク添付ファイルとしてリンクを貼り付けることです。教師がすでに使い慣れた機能を拡張するために、教師がリンクの添付ファイルをアドオンの添付ファイルにアップグレードできるようにアドオンを構成できるようになりました。

概要

この機能を使用してアドオンを構成すると、教師が課題の作成ページでリンクの添付ファイルを貼り付けたときに、アドオンの添付ファイルへのリンクをアップグレードするよう求められます。教師には、アドオンがすでにインストールされている場合にのみ、追加するように求められます。

教師がアドオン添付ファイルへのリンクのアップグレードに同意すると、次のクエリパラメータを指定して Link Upgrade iframe が起動します。

courseId
itemId
itemType
addOnToken
urlToUpgrade
login_hint（ユーザーがアプリをすでに承認している場合のみ）

最初の 4 つのクエリパラメータは、Attachment Discovery iframe で起動されたクエリパラメータをミラーリングします。urlToUpgrade クエリパラメータは新しいもので、アドオンアタッチメントの作成方法の評価に役立ちます。次に、他のクエリパラメータを使用してユーザーがログインしているかどうかを確認し、itemType の値に基づいて courseWork、courseWorkMaterials、または announcements の CreateAddOnAttachment メソッドを呼び出します。iframe 内に読み込み画面を表示して、アドオンの添付ファイルが作成されていることを教師に示すことができます。

アドオンの添付ファイルが作成されると、iframe が閉じられ、教師は通常どおり課題の添付ファイルを表示できます。

技術的な実装の詳細

このセクションでは、この機能の重要な技術的詳細について説明します。

`urlToUpgrade` クエリパラメータを読み取る

urlToUpgrade クエリパラメータは、リンクアップグレード iframe に渡されるときに URI エンコードされます。元の形式で取得するには、URL をデコードする必要があります。たとえば JavaScript を使用している場合は、decodeURIComponent() 関数を使用できます。

リンクアップグレードの iframe を閉じる

この機能のユーザーエクスペリエンスを最適化するには、アドオンアタッチメントが正常に作成されたら postMessage を送信します。これにより、iframe が終了します。詳しくは、iframe 実装の詳細ページをご覧ください。

構成の詳細

この機能をアドオンに統合するには、次の構成が必要です。

リンクアップグレード iframe の URL: これは、教師がアップグレードに同意したときに iframe で開く URL です。
Classroom が検出してアップグレードを試みる URL パターン: URL パターンは、ホストと複数のパス接頭辞で構成できます。
- 複数の URL パターンを指定できます。
- パスの接頭辞を指定しない場合は、ホストに一致するすべての URL がアップグレードされます。
- アップグレードできるのは、https スキームを使用した URL のみです。
- URL パターンに localhost を含めることはできません。
- パスの接頭辞にクエリパラメータや URL フラグメントを含めることはできません。
- 現時点では、パス接頭辞ではワイルドカードを使用できますが、ホストでは次のことができません。
  - example.com は有効なホストで、/foo と /bar/*/baz は有効なパス接頭辞です。
  - example.*.host.com は有効なホストではありません。
- パス接頭辞のコンポーネント間のワイルドカードは、1 つのコンポーネントにのみ一致します。スラッシュで区切られた複数のコンポーネントには一致しません。ホスト example.com とパス接頭辞 /bar/*/baz を含む URL パターンについて考えてみましょう。
  - https://example.com/bar/123/baz は、URL パターンとの有効な一致です。
  - https://example.com/bar/123/baz/456/789 は、URL パターンに対して有効な一致です。
  - パス接頭辞のワイルドカードは /123/456/ と一致しないため、https://example.com/bar/123/456/baz は URL パターンに対して有効な一致ではありません。

開発プロセス

テストまたは本番環境用のアドオン用の Link Upgrade iframe URL と URL パターンを、classroom-link-upgrade-external@google.com 宛てにメールで送信してください。

まず、非公開アドオンと、所有しているテスト環境または開発環境の構成を用意します。Classroom チームは、本番環境の構成を有効にする前にこれらのテスト構成を有効にして、デモドメインでフローをテストできます。構成が有効になると、メールが届きます。localhost を使用する URL パターンは、この機能ではサポートされていません。

次の内容を含むメールを作成します。

Google Cloud Project number: GCP_PROJECT_NUMBER

Link Upgrade iframe URL: LINK_UPGRADE_IFRAME_URL

URL Patterns:
- Host:HOST_1
- Path prefixes:
  - PATH_PREFIX_1
  - PATH_PREFIX_2

- Host:HOST_2
- Path prefixes:
  - PATH_PREFIX_3
  - PATH_PREFIX_4

// add more hosts and path prefixes as needed

次のように置き換えます。

GCP_PROJECT_NUMBER: アドオンが関連付けられている Google Cloud プロジェクトの番号。
LINK_UPGRADE_IFRAME_URL: リンクアップグレード iframe で開く URL。
HOST_1: Classroom が検出するホスト。https スキームのみがサポートされています。
PATH_PREFIX_1、PATH_PREFIX_2: HOST_1 に関連付けられたパス接頭辞。Classroom が検出してアップグレードを試行します。
HOST_2: Classroom が検出するホスト。https スキームのみがサポートされています。
PATH_PREFIX_3、PATH_PREFIX_4: HOST_2 に関連付けられたパス接頭辞。Classroom が検出してアップグレードを試行します。

推奨されるユーザーエクスペリエンス

この機能を実装する際は、次の推奨事項を検討してください。

教師の余計な手間を省く

必要に応じて、iframe を使用してログインを容易にするか、読み込みインジケーターを表示することを強くおすすめします。最適なユーザーエクスペリエンスを実現するため、貼り付けたリンクをアドオンの添付ファイルにアップグレードすることに同意した後は、追加情報の入力を求められることはありません。ただし、アドオンでこれができない場合は、Link Upgrade iframe を使用して、必要な追加情報を収集できます。また、iframe を使用して、リンクをアップグレードできない場合やエラーが発生した場合に教師に通知することもできます。

ユーザーフレンドリーなアクセスに関するエラーメッセージを含める

教師がアクセスできないリンクを貼り付けてアップグレードする場合は、教師が問題を認識できるように、iframe にユーザーフレンドリーなエラーメッセージを表示します。iframe を使用して、コンテンツにアクセスするための適切な権限を教師に付与することもできます。