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

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

概要

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

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

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

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

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

技術的な実装の詳細

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

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

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

この機能で最適なユーザー エクスペリエンスを実現するには、アドオン添付が正常に作成されたら 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 パターンと一致します。
      • 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: HOST_1 に関連付けられたパス接頭辞。Classroom が検出してアップグレードを試みます。
  • HOST_2: Classroom が検出するホスト。https スキームのみがサポートされています。
  • PATH_PREFIX_3 と PATH_PREFIX_4: HOST_2 に関連付けられたパス接頭辞。Classroom が検出してアップグレードを試みます。

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

教師の作業を増やさない

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

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

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