Skip to main content
The Bigdata document viewer widget loads as a single script - no separate CSS file to host. You mount it on a container element and point it at a URL you control - your backend adds your Bigdata API credentials and forwards requests to the document and content APIs. The UI renders the document (including PDF) in an open Shadow DOM so the host page’s own CSS does not restyle the viewer’s internals.

​
How it fits together

Traffic for document data goes through your backend: the widget only calls proxyUrl - your server holds the Bigdata credentials, reaches Bigdata’s Documents and Content APIs, and returns JSON (and file URLs) the viewer can use. Where each part runs - the document viewer and your proxy live on your side; file storage, annotation, and catalog APIs run in Bigdata’s infrastructure. What happens at each step - the browser issues GET requests to your proxyUrl; your server adds the API key, calls Bigdata, and returns RPJSON and signed URLs. Time-limited URLs are often re-fetched through /proxy-document on your side so the browser does not need direct cross-origin access to signed storage or your key.
Never put your Bigdata API key in frontend code or expose it in the browser. The widget is designed to call your proxy. The proxy must attach your API key when calling Bigdata.

​
Why you need a backend endpoint

End users can open developer tools and read any secret shipped to the page. The widget therefore sends only to proxyUrl. Your server (or serverless function, or BFF) should:
  1. Authenticate the end user if needed (cookie, session, or signed token).
  2. Add the Bigdata API key to the outbound request when you call Bigdata.
  3. Forward the external paths the widget uses GET /proxy-document?url=… when dealing with a signed URL (without adding authentication).

​
Browser compatibility

The script bundle targets modern evergreen browsers. It is not supported in Internet Explorer or other legacy engines without current Web APIs. Supported browsers
BrowserGuidance
ChromeRecent stable (desktop and Android).
EdgeRecent stable (Chromium-based).
FirefoxRecent stable.
Safari16.4 or newer on macOS and iOS. Earlier versions lack reliable support for constructible stylesheets and adoptedStyleSheets on the widget’s Shadow DOM, which the bundle uses to inject CSS.
Environment expectations
  • JavaScript enabled - the widget mounts via script and does not render without JS.
  • CORS to your proxyUrl - if the embed and the API are on different origins, allow GET (and preflight when getHeaders adds non-simple request headers). Misconfigured CORS is a common “nothing loads” symptom, see Troubleshooting.
  • Third-party cookies - not required for the default embed pattern - auth is between the visitor’s browser and your proxyUrl (or headers from getHeaders, or cookies you set on that origin).
For audiences on older locked-down browsers, contact support to discuss feasibility.

​
Quickstart

1

Add a sized container

Add a wrapper element and give it the size you want (fixed pixels, percentage, flex, grid, or min-height-whatever fits your page). The widget mounts inside it and stretches to fill the container’s box.
<div id="document-viewer" style="width: 100%; min-height: 480px;"></div>
2

Load the script

Use the widget script URL from Bigdata. Example shape (version path may differ). Load it before the inline script that constructs the widget so BigdataDocumentViewer is defined:
<script src="https://app.bigdata.com/widgets/document-viewer/v1.0.0/document-viewer.min.js"></script>
3

Initialize the widget

Create the widget with BigdataDocumentViewer.init({ ... }) (or new BigdataDocumentViewer.BigdataDocumentWidget({ ... })). At minimum set container and proxyUrl. Set openDocument when you know which file to show first, and add theme and getHeaders as needed-see the configuration reference below.
<script>
  BigdataDocumentViewer.init({
    container: "#document-viewer",
    instanceId: "main-doc",
    proxyUrl: "https://your-backend.com/bff/bigdata",
    openDocument: {
      documentId: "YOUR_PUBLIC_DOCUMENT_ID",
      isPrivate: false,
    },
    theme: {
      preset: "light",
    },
  })
</script>
The Bigdata web app’s Widget Playground (under Playground → Widgets) loads the same UMD and wires getHeaders to the signed-in user-use it as a live example when you integrate auth.

​
Global API: BigdataDocumentViewer

After the bundle loads, the UMD global BigdataDocumentViewer exposes init, BigdataDocumentWidget, and (for multiple widgets) BigdataWidgetManager. init(config) is equivalent to new BigdataDocumentWidget(config); both return the mounted instance. UMD BigdataDocumentViewer members
Property / methodTypeDescription
BigdataDocumentViewer.initfunctioninit(config): pass the config object in Configuration reference.
BigdataDocumentViewer.BigdataDocumentWidgetclassConstructor: pass the same config as above.
BigdataDocumentViewer.BigdataWidgetManagerclassOptional. Shared manager and base theme across widgets.
Store the instance from BigdataDocumentViewer.init(...) (or new ...BigdataDocumentWidget(...)) if you need to call destroy() or use addListener / emit.

​
Proxy contract (summary)

What your BFF should serve (per path)
AspectExpected behavior
Public docGET {proxyUrl}/v1/documents/{documentId}. The response is either a limited view or includes a signed url for the full annotated content - the widget may follow with /proxy-document to load RPJSON. Align with Fetch document.
Private docGET {proxyUrl}/contents/v1/documents/{documentId}/annotated. The JSON includes a signed url; the viewer loads RPJSON via /proxy-document. See Get annotated document.
Proxy pass-throughGET {proxyUrl}/proxy-document?url={encodeURIComponent(signedUrl)} - your server fetches signedUrl, returns the body to the client (RPJSON or bytes). Required when the browser must not call the signed host directly.
Original fileGET {proxyUrl}/contents/v1/documents/{documentId}/original for PDF / download flows, as used by the file URL helper. Match Get original document style responses.
Headers - if you set getHeaders, the widget merges the returned map onto requests the HTTP client makes to your proxyUrl (for example Authorization: Bearer ...). Buffering and JSON - if the viewer stays on “loading” while your proxy already finished, check that your framework is not transforming or stripping the JSON body, and that CORS and proxy-document are implemented for GET.

​
Configuration reference

​
Top-level options

config options (top level)
OptionTypeDescription
containerstring or HTMLElementRequired. Where the widget mounts: a CSS selector that document.querySelector resolves, or a DOM element.
proxyUrlstringRequired (for loading documents). The base of your BFF. Without it, the inner queries for RPJSON will not run.
instanceIdstringOptional. Stable id for this instance when several widgets share a page; if omitted, the implementation uses “document”.
managerBigdataWidgetManagerOptional. Shared manager across widgets for coordinated events and a common base theme.
getHeadersfunctionOptional. () => Promise<Record<string, string>> - merged onto requests to your origin (e.g. bearer for your BFF).
openDocumentobjectOptional. Initial documentId, isPrivate, and optional matchesInformation; see openDocument (shape) .
themeobjectOptional. Visual settings; see theme .

​
openDocument (shape)

openDocument fields
FieldTypeDescription
documentIdstringRequired when you open a document. The public document id or private content id your backend uses.
isPrivatebooleantrue = private Content flow ( /contents/v1/…/annotated); false = public GET /v1/documents/{id} path.
matchesInformationobjectOptional highlighting: { cqsChunks: […] } or { cnums: number[] } from your search or app, when you need chunk alignment.
Later navigation - call instance.emit("opendocument", { documentId, isPrivate, matchesInformation? }) to load another document (same instance).

​
theme

The widget runs inside an open Shadow DOM, so host-page CSS does not change its internal layout or colors. Size the mount container in your page - the widget fills that container. You can also set theme.width and theme.height if you need explicit dimensions on the widget instead of relying on the container alone. Theme values are merged with defaults. preset chooses a base palette before overrides: theme.preset values
presetBehavior
lightLight background and text colors.
darkDark background and text colors.
autoFollows the user’s system preference ( prefers-color-scheme).
theme field reference
FieldTypeDescription
primaryColorstringAccents (controls, highlights).
backgroundColorstringWidget background.
surfaceColorstringSurfaces and panels.
textColorstringPrimary text.
textSecondaryColorstringMuted text.
borderColorstringBorders and dividers.
fontFamilystringFont stack; can default like the chat widget to inherit the host.
fontSizestringBase size; defaults in the same family as the chat widget (e.g. 16px).
borderRadiusstringCorner radius (e.g. 8px).
widthstringOptional fixed width when not using a fully sized container.
heightstringOptional fixed height when not using a fully sized container.
preset”light” | “dark” | “auto”Base palette; see the table above.

​
Multiple widgets and shared theming

Create one BigdataWidgetManager with an optional shared theme, pass it as manager in each BigdataDocumentViewer.init / BigdataDocumentWidget config, and give each widget a distinct instanceId. That way instances stay isolated but can share base styling-including when you add the chat widget and document viewer widget on the same page.

​
Instance lifecycle and events

  • destroy() - Unmounts React, clears the shadow root, and unregisters the instance. Call this when removing the widget from the page.
  • addListener(event, handler) / removeListener(event, handler) - Subscribe to widget events.
Event payloads include instanceName, timestamp, and data: data payload (summary) per event
Eventdata shape (summary)
ready{ widgetName: “BIGDATA_DOCUMENT_WIDGET” } (fires after mount).
opendocumentSame as openDocument: documentId, isPrivate, optional matchesInformation.
(For parity with the chat bus, the same type names exist across widgets. The document viewer widget is typically driven with opendocument to change what is on screen, see openDocument (shape) in Top-level options.)

​
Troubleshooting

Confirm the script URL loads (network tab, no 404). Ensure container matches an existing element. Check the browser console for validation errors (for example invalid proxyUrl). The inner fetch also needs a valid openDocument / emit("opendocument", ...) with a documentId, and a configured proxyUrl, or nothing will request RPJSON.
Your proxyUrl origin must allow the site origin that embeds the widget (Access-Control-Allow-Origin and related headers for GET and, if you use getHeaders, the necessary preflight).
The proxy is rejecting the request before Bigdata. Verify server-side auth and that forwarded credentials and getHeaders match what your BFF expects.
For Content-originated files, set isPrivate: true and the content_id your proxy expects. For public catalog content, set isPrivate: false and the id you would pass to Fetch document. Mixing public vs private flags is a frequent cause of 404s at the proxy.
A missing or incorrect /proxy-document is common: the first response returns a signed url that the browser must not call cross-origin. Ensure GET .../proxy-document?url= downloads the server-side and returns the JSON. If your BFF is slow but correct, also confirm you are not stripping or buffering the response body. Check upstream API key pass-through for /v1/documents/... and /contents/.../annotated.
For personalized help, use Support.