Getting started with the PDF Viewer SDK

Get started with a compact, high-performance PDF document viewer by following this guide.

Run a sample

Learn how to run the PDF Viewer SDK sample:

1. Download or clone the sample repository.

2. From the root of the repository, navigate to a sample at:

   examples/vanilla-typescript/view-pdf

3. Install dependencies:

   npm install

4. Build the project:

   npm run build

5. Run the server:

   npm run dev

6. Open http://localhost:4567/ in your browser.

samples

Run other samples in the same way. Review the /examples directory for more samples in the downloaded or cloned sample repository.

Integrate the SDK into your application

The following sections guide you through the installations, deployment, and integration of the PDF Viewer SDK.

Install and deploy

Prerequisite

The npm package complies with Node.js version 14 or higher.

The PDF Viewer SDK is distributed as an npm package or as a ZIP archive containing an example JavaScript web application.

The npm package is provided through npmjs.com and can be installed with:

npm i @pdf-tools/four-heights-pdf-web-viewer --save

The package contains the following directories:

Directory	Description
css	The compiled CSS
docs	Documentation
es6	Source code
pdfwebviewer	Static assets. See Static asset management.
scss	Sass CSS source files
umd	Main JavaScript and source code mappings
wasm	WebAssembly and data files
LICENSE.md	General licensing agreement
README.md	Quickstart read-me file

You can also obtain the PDF Viewer SDK from the Pdftools My PDF Tools Portal as a self-contained example JavaScript web application in the form of a ZIP archive with the following content:

Subdirectory	Description
doc	License terms and documentation
webapp	minimal.html: A minimal HTML with the default WebViewerOptions index.html: An example HTML with a wide range of WebViewerOptions .htaccess, web.config: Server configuration files for Apache and Windows IIS
webapp/pdfwebviewer	Includes static assets. Review Static asset management for more information. Development source code mapping files: pdf-web-viewer.development.js pdf-web-viewer.development.map.js

Review WebViewerOptions reference documentation.

Static asset management

It's necessary to serve the static assets for the PDF Viewer SDK to function. Among the static assets, you can find predefined language files with translations that are ready for use. These languages include English, German, French, and Italian. You can exclude and add your own custom translation files. The static assets are contained in the package subdirectory pdfwebviewer:

• Main JavaScript file: pdf-web-viewer.min.js
• Compiled CSS: pdf-web-viewer.css
• WebAssembly, associated JavaScript, and data files:
  • PdfViewing.data
  • PdfViewing_Main.js, PdfViewing_Main.wasm
  • PdfViewing_Worker.js, PdfViewing_Worker.wasm
• Translation files:
  • translations.en.json
  • translations.de.json
  • translations.fr.json
  • translations.it.json

After installing or updating the PDF Viewer SDK:

1. Copy the static assets from the pdfwebviewer subdirectory to the base URL location.

note

You can exclude unused translation files and custom translation files can be added. Review Custom translations for more information.

Base URL

Serve the static assets with the targeted application from a base URL. The base URL is configured by setting the JavaScript property window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL. The base URL can be a path relative to the main HTML file or an absolute path. For example:

• ./path/to/pdfwebviewer: File path relative to the index.html.
• /file/viewer/pdfwebviewer: Absolute file path.
• file:///e:/electron-app/pdfwebviewer: Absolute file path.

The base URL must be set prior to loading the PDF Viewer SDK. For example, in the head element of the main HTML file as:

<script type="text/javascript">
  window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL = './pdfwebviewer/'
</script>

Manual copying

Not recommended: It is possible to manually copy the asset files. However, if you need to copy the files again before the build, you can forget to do so. For example, when using the npm package, PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL is defined as ./pdfwebviewer/, and your main directory for static assets is static.

cp -R ./node_modules/@pdf-tools/four-heights-pdf-web-viewer/pdfwebviewer ./static

If you need to copy specific asset files, use tools such as the CopyWebpackPlugin instead of manual copying. For more information, review the following section Automated copying.

Automated copying

When using the npm package, it is recommended to use a bundler which copies the static assets during the build process. See the following examples:

For Webpack:

const path = require('path')
const CopyWebpackPlugin = require('copy-webpack-plugin')
const pdfwebviewerDir = path.join(
    path.dirname(require.resolve('@pdf-tools/four-heights-pdf-web-viewer')),
    '../pdfwebviewer'
)
module.exports = {
    ...
    plugins: [
        new CopyWebpackPlugin({
            patterns: [
                {
                    from: '**/*',
                    to: 'pdfwebviewer', // Match with PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL
                    context: pdfwebviewerDir,
                }
            ],
        }),
    ],
}

For Angular in angular.json:

"projects": {
    "angular": {
        "architect": {
            "build": {
                "options": {
                    "assets": [
                        {
                            "glob": "**/*",
                            "input":
                                "./node_modules/@pdf-tools/four-heights-pdf-web-viewer/pdfwebviewer",
                            "output":
                                "./pdfwebviewer" // Match with PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL
                        },
                    ],
                },
            },
        },
    },
}

Basic usage

A simple web application that uses the PDF Viewer SDK with the default WebViewerOptions is implemented as follows.

In the index.html:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <script type="text/javascript">
      // path to static assets must be set before the viewer is loaded
      window.PDFTOOLS_FOURHEIGHTS_PDFVIEWING_BASEURL = './pdfwebviewer/'
    </script>
    <link rel="stylesheet" type="text/css" href="./pdfwebviewer/pdf-web-viewer.css" />
    <title>PDF Web Viewer</title>
  </head>
  <body>
    <!-- HTM element containing the PdfWebViewer. -->
    <div id="pdfviewer" style="height: 100vh; width: 100vw"></div>
  </body>
</html>

License key

In the index.js set a valid license key in the const license = ''. Without a valid license key the output files are watermarked. Get in touch with the Pdftools sales team through the Contact page to get a full license.

In the index.js:

import { PdfWebViewer } from '@pdf-tools/four-heights-pdf-web-viewer'

const element = document.getElementById('pdfviewer')
const license = ''

// use default options
const options = {}

const pdfViewer = new PdfWebViewer(element, license, options)

Server configuration

It is necessary to configure the correct content types for the *.wasm and the *.data files.

Windows IIS

The content types can be configured for a Windows Internet Information Services (IIS) web server by means of the following web.config file:

<?xml version="1.0" encoding="UTF-8"?>
  <configuration>
    <system.webServer>
      <staticContent>
        <mimeMap fileExtension=".mem" mimeType="application/octet-stream" />
        <mimeMap fileExtension=".data" mimeType="application/octet-stream" />
        <mimeMap fileExtension=".wasm" mimeType="application/wasm" />
      </staticContent>
    </system.webServer>
  </configuration>

tip

In the web.config file, you can also configure caching settings for the PDF Viewer SDK static assets.

Apart from web.config there is also %SYSTEMROOT%\System32\inetsrv\Config\applicationHost.config. Depending on the IIS version, this file already contains some of the MIME type mapping entries. In this case, remove the duplicate entries from web.config.

Apache

The content types can be configured for an Apache web server by means of the following.htaccess file:

AddType application/octet-stream ".mem"
AddType application/octet-stream ".data"
AddType application/wasm         ".wasm"

In this file, you can also configure caching settings for the PDF Viewer SDK static assets.

License keys

The PDF Viewer SDK can without a license key with watermarked results. To remove the watermark, request an evaluation or full license key from the Pdftools sales team through the Contact page.

Use the license key

To enter the license key, pass the license key as a second argument of the PdfWebViewer constructor (in the const license = ''). Review Basic usage for detailed information.

Troubleshooting

For troubleshooting of issues related to the license key, review PDF Viewer license documentation.