Box Embed

Box EmbedはHTMLベースのフレームワークで、これにより、独自に作成したアプリケーションにBoxウェブアプリの機能全体を埋め込むことができます。Box Embedを使用すると、ファイルのアップロード、検索、コメント付け、共有、タグ付けに加え、Box Editを使用したファイルの編集も可能になります。また、Box HubsのAIチャットを埋め込むことで、焦点を絞ったチャットボットエクスペリエンスも実現できます。

開始する前に

ウィジェットを作成するには、以下のことが必要です。

• 共有用の埋め込み可能な要素 (フォルダ、ファイル、Hub、メモ、アプリなど) を設定する。
• ビューアー以上の権限がある。

ウェブアプリの使用

BoxウェブアプリからBox埋め込みウィジェットのコードを取得するには、以下の手順を実行します。

ファイルとフォルダ

1. 選択したファイルまたはフォルダに移動します。
2. そのフォルダの横にある省略記号をクリックします。
3. [その他の操作] > [埋め込みウィジェット] に移動します。

Hub

1. 選択したHubに移動します。
2. 右上にある省略記号メニューをクリックします。
3. [Hubを埋め込む] をクリックします。

メモ

1. 選択したメモに移動します。
2. 省略記号メニューをクリックします。
3. [埋め込みウィジェット] をクリックします。

アプリ

1. 選択したアプリまたはBoxアプリビューに移動します。
2. 省略記号メニューをクリックします。
3. [埋め込む] をクリックします。

次の手順では、埋め込み可能な要素のパラメータを構成します。

埋め込みウィジェットのカスタマイズが完了したら、埋め込みコードをコピーして自分のサイトまたはウェブアプリに貼り付けます。

プログラムを使用して構成

Box Embedをさらにカスタマイズする場合は、プログラムを使用して実行できます。埋め込みのスニペットの形式は次のとおりです。

<iframe
  src="https://{custom_domain}.app.box.com/embed/s/{shared link value}?view={list or icon}&sortColumn={name, date, or size}&sortDirection=ASC"
  width="{pixels}"
  height="{pixels}"
  frameborder="0"
  <!-- Optionally replace * with your enterprise-specific domain (for example, mycompanydomain.app.box.com) -->
  allow="local-network-access *; clipboard-read *; clipboard-write *" 
  allowfullscreen
  webkitallowfullscreen
  msallowfullscreen>
</iframe>

ブラウザの権限

Google Chrome 142以上およびMicrosoft Edge 143以上では、allow属性を使用して、クリップボードの操作やローカルネットワークへのアクセスを有効にします。この属性は、これらのブラウザバージョン用に設計されていますが、すべてのブラウザに対して安全に含めることができます。他のブラウザでは無視されます。

この属性がないと、埋め込まれたBoxコンテンツは、Box Tools、デバイストラスト、またはクリップボードのコピーボタンで機能しない可能性があります。

共有リンクの値の検索

プログラムを使用して埋め込みiframeを構築するには、まず、共有リンクの値を生成または検索します。この値を検索する1つの方法として、Boxウェブアプリを使用します。

また、PUT /files/:file_idまたはPUT /files/:file_idを使用して、APIで共有リンクを作成する方法もあります。

その後、GET /files/:idまたはGET /folders/:idエンドポイントを使用してクエリパラメータfields=shared_linkを渡すことにより、この共有リンクの値を検索できます。

curl https://api.box.com/2.0/folders/12345?fields=shared_link \
    -H "authorization: Bearer ACCESS_TOKEN"

"shared_link": {
  "url": "https://app.box.com/s/dsbJFzdO7qZxdfOHFzdO7qZxdfOH",
  "download_url": null,
  "vanity_url": null,
  ...
}

ページをルートフォルダ/[すべてのファイル] ページに設定することもできます。URLを共有リンク<iframe src=“https://app.box.com/embed/folder/0”….></iframe>ではなく/folder/0に設定してください。

パラメータ

次に、表示のカスタマイズオプションを選択します。構成可能なパラメータ (省略可) のリストを以下に示します。

Boxが提供するアプリのURLにあるカスタム検索パラメータはすべて、埋め込みウィジェットウィンドウとコンテンツプレビューに渡されます。

全画面表示機能

Box Embedスニペットの全画面表示機能を有効にするために、オブジェクトを全画面に表示可能にする場合は、以下のパラメータの1つ以上を<iframe>に含めてください。

• allowfullscreen
• webkitallowfullscreen
• mozallowfullscreen
• oallowfullscreen
• msallowfullscreen

Box HubsのAIチャットの埋め込み

Box Hubの機能全体を埋め込むことに加えて、AIを活用したチャットインターフェースのみを埋め込むことも可能です。このモードでは、特定のHub内のファイルを利用した焦点を絞ったチャットボックスエクスペリエンスが提供され、ナビゲーションやコンテンツ閲覧のオプションは提供されません。

前提条件

AIチャットモードに埋め込まれたHubにアクセスするには、以下の前提条件があります。

• Hubを所有する企業では、Box AI for Hubsが有効になっている必要があります。
• ユーザーは、認証済みで、所属する企業でBox AI for Hubsが有効になっている必要があります。
• ユーザーには、Hubに対してビューアー以上の権限が必要です。

AIチャットの埋め込みの作成

1. AIチャットのナレッジベースのソースとして機能するHubに移動します。

2. 右上にある省略記号メニューをクリックします。

3. [Hubを埋め込む] をクリックします。

4. [Hub AIチャット] タブを選択します。

5. チャットモードを選択します。

   • チャットボタン
   • チャットウィジェット

6. 埋め込みコードをコピーします。

チャットボタン

チャットボタンモードでは、ユーザーがボタンをクリックするとAIチャットウィジェットが開きます。これは、Boxでホストされるscriptとして生成され、ページ上にフローティングチャットボタンを表示します。

チャットボタンのパラメータ

チャットボタンモードでは、以下のパラメータがサポートされています。

次の例は、利用可能なすべてのパラメータを使用したチャットボタンの構成全体を示します。

<script 
  src="https://cdn01.boxcdn.net/embeddable-ai-chat-script/2.8.0/box_integrations_ai_chat_button.js" 
  data-hub-id="123456789" 
  data-custom-box-domain="mycompanydomain.app.box.com" 
  data-shared-link="abcdefghijklmnopqrst123" 
  data-button-text="Ask our HR chatbot">
</script>

チャットウィジェット

チャットウィジェットモードでは、ページ読み込み時に、AIチャットウィジェットが直接埋め込まれます。これは、iframeとして生成され、チャットインターフェース全体をすぐに表示します。

チャットウィジェットのパラメータ

チャットウィジェットモードでは、iframeを使用すると、AIチャットウィジェットが直接ページに埋め込まれます。iframeのsrc属性にURLパラメータを追加して、動作をカスタマイズできます。

次の例は、利用可能なすべてのパラメータを使用したチャットウィジェットの構成全体を示します。

<iframe 
  src="https://yourcompanydomain.app.box.com/ai-chat?hubId=123456789&sharedLink=abcdefghijklmnop123&showCloseButton=false" 
  width="800" 
  height="550" 
  frameBorder="0" 
  <!-- Optionally replace * with your enterprise-specific domain (for example, mycompanydomain.app.box.com) -->  
  allow="local-network-access *; clipboard-read *; clipboard-write *"  
  allowfullscreen 
  webkitallowfullscreen 
  msallowfullscreen>
</iframe>

閉じるボタンの使用

(提供されたスクリプトを使用せず) iframeを使用して直接Box AIチャットを埋め込む場合は、チャットインターフェース内で閉じるボタンを有効化できます。このボタンは、postMessageを通じて親アプリケーションと通信します。

閉じるボタンの有効化

iframeの隅に閉じるボタン (✕) を表示するには、次のように、iframe URLにshowCloseButton=trueクエリパラメータを追加します: https://app.box.com/ai-chat?hubId=YOUR_HUB_ID&showCloseButton=true

仕組み

1. showCloseButton=trueを設定すると、Xボタンがチャットのiframeの隅に表示されます。
2. ユーザーがこのボタンをクリックすると、iframeから親ウィンドウにpostMessageイベントが送信されます。
3. このイベントには、"BOX_AI_CHAT_CLOSE"に設定されたevent.data.typeが含まれています。
4. ホストしているアプリケーションは、このイベントをリッスンし、閉じるロジックを処理します。

実装例

window.addEventListener('message', (event) => {
    // Optional: validate origin is from Box for additional security
    // if (event.origin !== 'https://app.box.com') return;

    if (event.data && event.data.type === 'BOX_AI_CHAT_CLOSE') {
        closeChat();
    }
});

イベントのリファレンス

有効期限付き埋め込みリンク

ファイルの場合、GET /files/:idを呼び出し、fieldsクエリパラメータを使用してexpiring_embed_linkをリクエストすることもできます。

curl https://api.box.com/2.0/files/12345?fields=expiring_embed_link \
    -H "authorization: Bearer ACCESS_TOKEN"

{
  "etag": "1",
  "expiring_embed_link": {
    "token": {
      "access_token": "1!rFppcinUwwwDmB4G60nah7z...",
      "expires_in": 3646,
      "restricted_to": [
        {
          "object": {
            "etag": "1",
            "file_version": {
              "id": "34567",
              "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00",
              "type": "file_version"
            },
            "id": "12345",
            "name": "Image.png",
            "sequence_id": "1",
            "sha1": "1b8cda4e52cb7b58b354d8da0068908ecfa4bd00",
            "type": "file"
          },
          "scope": "base_preview"
        },
        ...
      ],
      "token_type": "bearer"
    },
    "url": "https://cloud.app.box.com/preview/expiring_embed/...."
  },
  "id": "12345",
  "type": "file"
}

url属性を<iframe>内で使用すると、自動で期限切れになるBox Embedインターフェースを埋め込むことができます。

<iframe
  src="YOUR-GENERATED-BOX-EMBED-LINK"
  width="{pixels}"
  height="{pixels}"
  frameborder="0"
  allowfullscreen
  webkitallowfullscreen
  msallowfullscreen
/>

パラメータ

UIをカスタマイズするために、このURLにさらにパラメータを追加することもできます。そのためには、以下のパラメータをクエリパラメータとしてurlに追加します。最終的なURLは、次のようになります。

https://app.box.com/preview/expiring_embed/[HASH]?[parameterName]=true

クラウド (雲) ゲーム

クラウド (雲) ゲームとは、クリックジャッキングを防ぐために作成されたウィジェットです。これは、パートナー統合ではない埋め込みサイトに表示されます。クラウド (雲) ゲームでは、ユーザーは、操作の許可を得るためにクラウド (雲) を適切な場所にドラッグする必要があります。このゲームでは、クラウド (雲) の位置とそのドラッグ先がランダムに生成されるため、クリックジャッキングが難しくなります。

postMessage()は、埋め込みとshowCloudGame両方のステータスを取得するためにiframeで使用されます。埋め込まれている場合、document.hasStorageAccess()は、BoxからCookieにアクセスできるかどうかを示します。アクセスでき、ユーザーがログイン済みの場合、クラウド (雲) ゲームが表示されます。showCloudGameのステータスがfalseの場合、ユーザーはログインページに誘導されます。

カスタムロゴ

有料のBoxをお使いの場合は、ファイルのプレビューに表示されるBoxのロゴを削除できます。削除するには、管理コンソールの [Enterprise設定]、[カスタム設定] に移動し、[埋め込みウィジェットのカスタマイズ] をオフに切り替えてBoxのロゴを非表示にします。

制限

Box Embedは、モバイルブラウザ向けには最適化されていないため、モバイルデバイス用に設計されたウェブエクスペリエンスでは使用しないでください。多くのUI Element (ダウンロードオプションや印刷オプションなど) はモバイルブラウザに表示されない可能性があります。