The Box Content Preview library allows developers to easily embed high quality and interactive previews of Box files in desktop and mobile web applications. This library powers the preview experience in the main Box web application as well as the various ways a platform developer can embed a preview inside their own application. This guide will describe and help you choose among the four methods: Expiring Embed via the 'Get Embed Link' API endpoint, the Content Preview library, the Content Preview Box Element, and the Box Embed Widget.
Getting an expiring embed link via the 'Get Embed Link' API endpoint and using an iframe to embed this link in your application is the easiest way to get started using Preview.
Expiring embed supports applications with app users and/or managed users, service accounts, and New Box View. While you do need to generate an access token with at least preview permissions, you don't need to manage client-side access tokens since the expiring embed link contains a self-encrypted and file-scoped token that Box generates.
Expiring embed is the easiest way to get started using Preview in your platform application—you just make a 'Get Embed Link' API request and then embed the returned link in an iframe. You can append query parameters to that embedded URL to customize two options—whether the download/print button are shown and whether annotations are enabled. Additionally, you can contact your Customer Success Manager to use a custom logo in the upper left of the header.
If you need to customize the Preview experience further, e.g. to enable or disable specific types of annotations, to enable or disable specific viewers or previews of specific file types, to hide the header, to modify the appearance of Preview, or other modifications, you must use either the Content Preview library or Element. You also must generate a new expiring embed link every time you wish to show a Preview since the generated link is only valid for 60 seconds. If you need a permanent embeddable Preview for an intranet post, blog post or similar non-dynamic web page, please use the Box Embed Widget.
The Content Preview library contains the most functionality and is the most extensible out of the three methods. Expiring embeds, the Content Preview Element, and Box embed widgets all use this library underneath and are essentially different wrappers around the base library.
The Content Preview library supports applications with app users and/or managed users, service accounts, and New Box View. To use this library, you must generate and pass access tokens to the client. Please read https://developer.box.com/docs/box-content-preview#section-scopes for documentation on how to properly downscope access tokens to prevent privileged access tokens from being leaked client-side.
The Content Preview library is the most feature-rich and extensible way to use Preview. However, you must know all of the domains in which your application will run because these domains need to be whitelisted in your Box application's CORS configuration so the library can make Box API requests. We are planning to modify our CORS behavior to remove this restriction later this year.
Content Preview supports Use the library directly when you need to customize the Preview experience, e.g. to enable or disable specific types of annotations, to enable/disable specific viewers or previews of specific file types, to hide the header, to modify the appearance of Preview, and/or many other possibilities. To see some example customizations in action, see: https://codepen.io/box-platform/pens/tags/?grid_type=list&selected_tag=box+content+preview.
Developers can use the Box Element framework to add features from the main Box web application into their own applications. Every Element, including Preview, exposes both vanilla ES5 and React component interfaces for usage in non-React and React applications respectively. The Content Preview library mentioned above is Preview's vanilla ES5 interface and the Box Elements codebase includes Preview's React interface. If your application is written in React, you may want to use this React component, which has more functionality and is more performant than the 'Get Embed Link', and easier to use within a React environment than the vanilla ES5 library.
Visit https://github.com/box/box-content-preview-demo for a minimal React application that uses the Content Preview Element.
The Content Preview Element supports applications with app users and/or managed users, service accounts, and New Box View. To use this library, you must generate and pass access tokens to the client. Please read https://developer.box.com/docs/box-content-preview#section-scopes for documentation on how to properly downscope access tokens to prevent privileged access tokens from being leaked client-side.
Use the Content Preview Element if your application is written in React, you know all of the domains in which your application will run so they can be whitelisted for CORS, and you don't need direct access to the various methods and properties in the Preview library.
The Box embed widget allows anyone to embed a Box file or folder into a web page that supports HTML iframe code. The embedded experience is a miniaturized view of the preview you would see in the main Box web application.
The Box Embed Widget does not work with app users, service accounts, or New Box View. The file being previewed must have a shared link and access to the file depends on the shared link's access settings. Anyone can view an embed of a file with an open shared link but if the link settings are restricted to company-only or people collaborated on the file, users must log into their Box account to preview the file.
Use the Box Embed Widget if you have a Box web application account, have the file you wish to embed uploaded to your account, and want a permanent embed for an intranet post, blog post, social network post, or any other web site that supports HTML iframe embeds. Annotations are not available and you cannot customize the experience beyond the embed size.