Box Embed

Box Embed is a HTML-based framework that allows embedding the entire Box Web App experience in a custom-made application. Box Embed provides the ability to upload, search, comment, share, tag, and edit files using Box Edit. You can also embed Box Hubs AI Chat for a focused chatbot experience.

開始する前に

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

• Set an embeddable element, such as a folder, file, hub, note, or app for sharing.
• ビューアー以上の権限がある。

ウェブアプリの使用

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

ファイルとフォルダ

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

Hub

1. Navigate to the chosen hub.
2. Click on the ellipsis menu in the upper-right corner.
3. [Hubを埋め込む] をクリックします。

メモ

1. Navigate to the chosen note.
2. 省略記号メニューをクリックします。
3. [埋め込みウィジェット] をクリックします。

アプリ

1. Navigate to the chosen app or Box App View.
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 Chat embedding

In addition to embedding the complete Box Hub experience, you can embed only the AI-powered chat interface. This mode provides a focused chatbot experience powered by the files within a specific hub, without navigation or content browsing options.

前提条件

To access a hub embedded in AI Chat mode:

• The enterprise that owns the hub must have Box AI for Hubs enabled.
• The user must be authenticated and have Box AI for Hubs enabled at their enterprise.
• The user needs at least Viewer permissions on the hub.

Creating an AI Chat embed

1. Navigate to the hub that will serve as the knowledge source for the AI Chat.

2. Click the ellipsis menu in the upper-right corner.

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

4. Select the Hub AI Chat tab.

5. Select chat mode:

   • Chat button
   • Chat widget

6. Copy the embed code.

Chat button

In Chat button mode, the AI chat widget opens after the user clicks the button. It is generated as a Box-hosted script and displays a floating chat button on your page.

Chat button parameters

The Chat button mode supports the following parameters:

The following example shows a fully configured chat button with all available parameters:

<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>

Chat widget

In Chat widget mode, the AI chat widget is embedded directly on page load. It is generated as an iframe and displays the full chat interface immediately.

Chat widget parameters

In Chat widget mode, the AI chat widget is embedded directly on the page using an iframe. You can customize the behavior by adding URL parameters to the iframe's src attribute:

The following example shows a fully configured chat widget with all available parameters:

<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>

Using the close button

When embedding the Box AI chat directly with iframe (without using the provided script), you can enable a close button within the chat interface that communicates with your parent application through postMessage.

Enabling the close button

To display a close button (✕) in the corner of the iframe, add the showCloseButton=true query parameter to your iframe URL as follows: https://app.box.com/ai-chat?hubId=YOUR_HUB_ID&showCloseButton=true

How it works

1. When showCloseButton=true is set, an X button appears in the corner of the chat iframe.
2. When a user clicks this button, the iframe sends a postMessage event to the parent window.
3. The event contains event.data.type set to "BOX_AI_CHAT_CLOSE".
4. Your hosting application listens for this event and handles the closing logic.

Implementation example

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();
    }
});

Event reference

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

ファイルの場合、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 (ダウンロードオプションや印刷オプションなど) はモバイルブラウザに表示されない可能性があります。