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

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

概要

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

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

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

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

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

技術的な実装の詳細

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

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

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

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

この機能で最適なユーザーエクスペリエンスを実現するため、アドオンの添付ファイルが正常に作成されたら、postMessage を 1 回送信します。これで iframe が閉じます。詳しくは、iframe 実装の詳細ページをご覧ください。

構成の詳細

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

Link Upgrade 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 パターンと有効に一致します。
  - https://example.com/bar/123/456/baz は URL パターンと一致しません。パスのプレフィックスのワイルドカードが /123/456/ と一致しないためです。

開発プロセス

テスト用または本番環境用アドオンのリンクアップグレード 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: Classroom が検出してアップグレードを試みる HOST_1 に関連付けられたパスの接頭辞。
HOST_2: Classroom が検出するホスト。https スキームのみがサポートされています。
PATH_PREFIX_3 と PATH_PREFIX_4: Classroom が検出してアップグレードを試みる HOST_2 に関連付けられたパスの接頭辞。

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

この機能を実装する際に考慮すべき提案事項を次に示します。

教師の負担を軽減する

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

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

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