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

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

概要

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

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

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

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

アドオンアタッチメントが作成されると、iframe が閉じられ、教師は通常どおりに課題のアタッチメントを表示できます。

技術的な実装の詳細

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

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

urlToUpgrade クエリパラメータは、リンクアップグレード iframe で渡されるときに URI エンコードされます。URL を元の形式で取得するには、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: Classroom が検出してアップグレードを試行する HOST_1 に関連付けられたパス接頭辞。
HOST_2: Classroom が検出するホスト。https スキームのみがサポートされています。
PATH_PREFIX_3 と PATH_PREFIX_4: Classroom が検出してアップグレードを試行する HOST_2 に関連付けられたパス接頭辞。

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

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

教師の負担を軽減する

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

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

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