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

教師がサードパーティのコンテンツを Classroom に追加する方法の一つとして、課題作成ページにリンクをリンク添付として貼り付ける方法があります。教師がすでに慣れている機能に基づいて、教師がリンクアタッチメントをアドオンアタッチメントにアップグレードできるようにアドオンを設定できるようになりました。

概要

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

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

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

最初の 4 つのクエリパラメータは、アタッチメント検出の iframe で開始されるクエリパラメータと同様です。urlToUpgrade クエリパラメータは新しいもので、アドオンアタッチメントの作成方法の評価に役立ちます。次に、他のクエリパラメータを使用して、ユーザーがログインしているかどうかを確認し、itemType 値に基づいて CreateAddOnAttachment メソッドの courseWork、courseWorkMaterials、または announcements を呼び出します。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 は有効なホストではありません。
- パス接頭辞コンポーネント間のワイルドカードは、単一のコンポーネントにのみ一致します。スラッシュで区切られた複数のコンポーネントには一致しません。ホスト 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 パターンに対して有効な一致ではありません。

開発プロセス

テスト用または本番環境用アドオンのリンクアップグレード iframe URL と URL パターンを classroom-link-upgrade-external@google.com にメールで送信します。

Classroom アドオンを表すすべての Google Cloud プロジェクトに対して構成を提供できます。最初に非公開の公開設定をアドオンに指定して、本番環境のユーザーに影響を与えることなく、デモドメインで開発とテストを行うことをおすすめします。

構成が有効になると、メールで返信が届きます。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: Classroom が検出してアップグレードを試行する HOST_2 に関連付けられたパス接頭辞。

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

この機能を実装する際は、次の点にご留意ください。

教師の余計な手間を省く

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

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

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