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

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

概要

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

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

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

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

アドオン添付が作成されると、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: に関連付けられたパス接頭辞。Classroom が検出してアップグレードを試みる必要があります。HOST_2

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

教師の作業を減らす

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

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

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