Getting Started on .NET


Warning

As of 17 August 2022, we’re sunsetting PSPDFKit Library for .NET and replacing it with PSPDFKit GdPicture.NET Library. For more information, see our blog announcement.

Integrate into the .NET Framework

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Your First Application Using .NET

After installation, we recommend looking at our code samples to see some examples of how GdPicture.NET is used.

Adding a Reference to GdPicture.NET to Your Application

To use GdPicture.NET in your application, add a reference by following these steps:

  • Start Visual Studio .NET.

  • Begin a new project using your favorite programming language.

  • Select Project > Add Reference…

  • Choose the Browse tab and select the GdPicture.NET.14.dll library, which can be found in [INSTALLATION FOLDER]\Redist\GdPicture.NET\GdPicture.NET.14.dll.

  • Add a link to the GdPicture namespace where you want to use the DLL:

    • In C#, add the appropriate using directive to the code file(s) where you want to use the DLL (using GdPicture14).

    • In VB.NET, add the appropriate Imports directive to the code file(s) where you want to use the DLL (Imports GdPicture14).

Integrate into .NET Core

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Your First Application Using .NET

After installation, we recommend looking at our code samples to see some examples of how GdPicture.NET is used.

Adding a Reference to GdPicture.NET to Your Application

To use GdPicture.NET in your application, add a reference by following these steps:

  • Start Visual Studio .NET.

  • Begin a new project using your favorite programming language.

  • Select Project > Add Reference…

  • Choose the Browse tab and select the GdPicture.NET.14.dll library, which can be found in [INSTALLATION FOLDER]\Redist\GdPicture.NET\GdPicture.NET.14.dll.

  • Add a link to the GdPicture namespace where you want to use the DLL:

    • In C#, add the appropriate using directive to the code file(s) where you want to use the DLL (using GdPicture14).

    • In VB.NET, add the appropriate Imports directive to the code file(s) where you want to use the DLL (Imports GdPicture14).

Integrate into Visual Basic 6

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Your First Application Using COM

GdPicture.NET includes a COM edition that can be used like a COM/ActiveX component with IntelliSense support in environments supporting this technology (e.g. Visual Basic 6, Visual C++ with MFC, HTML pages, Delphi, Visual FoxPro, and more).

This edition is automatically registered on your computer when installing the GdPicture.NET package.

The DLL is located in [INSTALLATION FOLDER]\Redist\COM Interop\, and it can be registered on other computers using the regasm command with admin privileges, like this:

  • %SystemRoot%\Microsoft.NET\Framework\v4.0.30319\ **regasm.exe** GdPicture.NET.14.dll /codebase /tlb

The DLL can be unregistered using regasm.exe /u, like this:

  • %SystemRoot%\Microsoft.NET\Framework\v4.0.30319\ **regasm.exe /u** GdPicture.NET.14.dll /codebase /tlb

Visual Basic 6

This section provides you with a step-by-step guide to getting started using GdPicture.NET with Microsoft Visual Basic 6.

You can find three sample projects demonstrating the use of several GdPicture.NET features using COM Interop in the [INSTALLATION FOLDER]\Samples\WinForm\vb6 folder.

Information

IntelliSense is fully supported in Visual Basic 6.

Integration

  1. Start with a new project (or open an existing project) and click OK.

New Project

  1. Click Project in the application menu, and then select References…

Project > References

  1. Scroll through the list of available references, check the GdPicture.NET 14 - Document Imaging SDK entry, and click OK.

Selecting GdPicture.NET 14 - Document Imaging SDK

  1. Using the Object Browser (accessed with the F2 shortcut), you’ll see all the classes, enumerations, methods, properties, etc…

Using the Object Browser

  1. Now you can use GdPicture.NET like any other object in your code.

Integrate into Visual C++ and MFC

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Visual C++ with MFC

This section provides you with a step-by-step guide to getting started using GdPicture.NET with Visual C++ (up to VS 2017) with an MFC environment.

You can find an example using COM Interop in the [INSTALLATION FOLDER]\Samples\WinForm\c++ mfc folder.

Information

IntelliSense is fully supported in Visual C++.

Integration

  1. Start a new project in Visual Studio > File > New > Project. Then select MFC/ATL > MFC Application.

Visual Studio > MFC/ATL > MFC Application

  1. Set your Application Type to Dialog based.

Dialog based Application Type

  1. Copy GdPicture.NET.14.dll and GdPicture.NET.14.tlb to your application folder.

  2. To import the DLL, use Project > Class Wizard (available until VS 2017), choose the Add Class… dropdown, and select MFC Class From TypeLib…

Select MFC Class From TypeLib…

  1. Under Add class from: in the wizard dialog, select File. Then, click the … button on the right-hand side, next to the Location field, to select the GdPicture.NET.14.tlb file located in [INSTALLDIR]/Redist/COM Interop or in your application directory if you copied it.

  2. Select the interfaces you need from the list to generate the C++ wrappers.

Add class and select interfaces

Information

Each GdPicture class, which also contains events, will be split into two classes: one defining events, and another one defining properties and methods. For example, to import the `GdPicturePDF` class, select `__GdPicturePDF` and `GdPicturePDF`.

  1. Change the way the DLL is imported in generated header files (if needed). Change no_namespace to raw_interfaces_only in the #import code line in the generated headers.

Change <code>no_namespace</code> to <code>raw_interfaces_only</code>

  1. Initialize COM objects in your application by adding HRESULT hr = CoInitialize(NULL); under the main function.

Initialize COM objects

  1. Include the generated headers in your file and build the application.

Include the generated headers

GdViewer Integration in Visual C++ with MFC

This section provides you with a step-by-step guide to getting started creating a simple MFC application using GdPicture.NET with Visual C++ (up to VS 2017) and containing a GdViewer ActiveX component.

You can find an example using COM Interop in the [INSTALLATION FOLDER]\Samples\WinForm\c++ mfc folder.

Information

IntelliSense is fully supported in Visual C++.

Integration

  1. Start a new project in Visual Studio > File > New > Project. Then select Visual C++ > MFC/ATL > MFC Application. Write the project name and confirm.

Start a new project in Visual Studio

  1. Set your Application Type to Dialog based. Copy GdPicture.NET.14.(64).dll and GdPicture.NET.14.tlb to your application folder.

Set Application Type and copy files

  1. To import the installed GdPicture.NET toolkit (DLL) and to integrate the GdViewer control, you need to follow two steps.

To import as an ActiveX control:

  • Use Project > Class Wizard (available until VS 2017) and select the Add Class dropdown. Then, choose MFC Class From ActiveX Control… This is necessary for controls like GdViewer.

  • The window with the wizard will appear, and from the Available ActiveX controls list, choose GdPicture14.GdViewer.

Setting up in the Class Wizard

  • From the Interfaces list, choose IGdViewer and add it to the Generated classes list. Then click Finish and press OK.

Add IGdViewer to the Generated classes list

To import from TypeLib:

  • Use Project > Class Wizard (available until VS 2017) and select the Add Class dropdown. Then, choose MFC Class From TypeLib…

  • The window with the wizard will appear, and from the Available type libraries list, choose GdPicture14 - Document Imaging.

Choose GdPicture14 - Document Imaging from Available type libraries

  • From the Interfaces list, choose ILicenseManager and __GdViewer and add them to the Generated classes list. Then click Finish and press OK.

  1. Initialize COM objects in your application by adding HRESULT hr = CoInitialize(NULL); under the main function.

Initialize COM objects

Here’s the adapted source code:

BOOL CdemoApp::InitInstance()
 {
   ...
   InitCtrls.dwICC = ICC_WIN95_CLASSES;
   InitCommonControlsEx(&InitCtrls);

   CWinApp::InitInstance();
   HRESULT hr = CoInitialize(NULL);
   ...
 }
  1. Include the generated headers in your file and build the application.

Here’s the adapted source code:

// Add GdViewer control to the `demoDlg.h` file:
  class CdemoDlg : public CDialogEx
  {
  // Construction
  public:
      CGdViewer sampleView;
      ...
  }

  // Include headers in the `demoDlg.cpp` file:
  #include "C_GdViewer.h"
  #include "CLicenseManager.h"

Include the generated headers

Adding Code to Initialize the GdViewer Component

  1. Your default solution will look like what’s shown below. In Resource View, select Dialog/IDD_DEMO_DIALOG.

Solution Explorer

  1. When the form appears, choose Button from the toolbox on the left side and place it on the form.

  2. Double-click the form, and the method for the button click will appear.

  3. Update it with this code:

const int CTRL_ID = 280;
void CdemoDlg::OnBnClickedButton1()
 {
      // TODO: Add your control notification handler code here.
      CLicenseManager oLicenseManager;
      oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
      oLicenseManager.RegisterKEY(L" XXX ");
      
      // Create the control, but make sure to use `WS_CHILD` and `WS_VISIBLE`.
      if (!sampleView.Create(L"PdfWnd", WS_CHILD | WS_VISIBLE, CRect(0, 0, 200, 200), this, CTRL_ID))
          {
            AfxMessageBox(L"Failed to create GdViewer control");
             return;
         }
      
      // Sample init settings — not necessary.
      sampleView.put_EnableMenu(false);
      sampleView.put_ContinuousViewMode(TRUE);
      sampleView.put_MouseWheelMode(2);
      sampleView.put_ScrollBars(TRUE);
      sampleView.DisplayFromFile(L"image.jpg");
      sampleView.Redraw();
}

Adding Code to Dispose of the GdViewer Component

The following example shows how you can release the GdViewer component. What’s important to note is that you need to dispose of the objects properly.

  1. Add a new method for handling the Close() message by choosing Resource View > Demo > Dialog > IDD_DEMO_DIALOG.

  2. Select the form that appears.

  3. Click the messages icon in the properties bar.

  4. Double-click the field next to WM_CLOSE. This will give you the option to create a method for handling Close() messages.

  5. Add the following code to the method you just created:

    • sampleView.CloseDocument();

    • sampleView.Dispose();

Adding code to dispose of the component

To handle the Close() message, use the following code:

// The result will look like this:
void CdemoDlg::OnClose()
{
    // TODO: Add your message handler code here and/or call default.
    CDialogEx::OnClose();
    sampleView.CloseDocument();
    sampleView.Dispose();
}

Integrate into Delphi and C++Builder

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Delphi and C++Builder

This section provides you with a step-by-step guide to getting started using GdPicture.NET with Delphi and C++Builder.

You can find two sample projects that demonstrate the use of GdPicture.NET features. These are located in the [INSTALLATION FOLDER]\Samples\WinForm\delphi folder and use COM Interop.

Information

IntelliSense is fully supported in Delphi and C++Builder.

Integration

You have two integration options, outlined below.

Importing as ActiveX Controls

  1. Start a new project in your Delphi environment and select Component > Import Component > Import ActiveX Control > Next.

Select Component > Import Component > Import ActiveX Control > Next

  1. Scroll through the list until you find GdPicture.NET 14 - Document Imaging SDK. Select it and click Next.

Select GdPicture.NET 14 - Document Imaging SDK and click Next

  1. In the Class Name(s) field, you’ll see all the classes available for import. Ensure Palette Page is set to ActiveX, and check that Unit Dir Name is how you want it. Select the Generate Component Wrappers checkbox and click Next. Then, select the Install to New Package option and click Next again.

Import Component

  1. Browse for the proper path and add it as the Package name. Then click Finish. Finally, add and confirm the framework by clicking Yes.

Add the package name and confirm

  1. Build the package. Change all instances of UIntPtr to Cardinal in the GdPicture_NET_14_TLB.pas file. After you’ve successfully built the package, you need to install it.

Build and install the package

  1. Finally, create your project, select your favorite components from the ActiveX palette, and use them in your application.

Select palettes

Information

  • Turn off floating-point exceptions.
  • In a Delphi 32-bit app, use `Set8087CW($133f);`.
  • In a Delphi 64-bit app, use `SetExceptionMask(exAllArithmeticExceptions);`. To use this, you first need to import the math runtime library.
  • In C++Builder, add `Set8087CW(0x133f);` to the `WTypes.h` file.

Example Use

The following code snippet demonstrates how to load a TIFF file and save it as a BMP:

procedure Test;
var TiffImageID, Status  : Integer;
begin
     LicenseManager1.RegisterKEY('XXX');    //Please, replace XXX by a valid demo or commercial KEY
     TiffImageID  := GdPictureImaging1.CreateGdPictureImageFromFile('d:\test.tif');
     Status := GdPictureImaging1.SaveAsBMP(TiffImageID, 'd:\output.bmp');
     if Status  <> 0 then
          MessageBox(0,Pchar('Error saving file. Status: ' + inttostr(Status)),'', 0)
     else
          MessageBox(0,Pchar('Done'),'', 0);
end;

Importing a Type Library

  1. Start a new project in your Delphi environment and select Component > Import Component… > Import a Type Library > Next.

Select Component > Import Component… > Import a Type Library > Next

  1. Scroll through the list until you find GdPicture.NET 14 - Document Imaging SDK. Select this and click Next.

Select GdPicture.NET 14 - Document Imaging SDK and click Next

  1. In the Class Name(s) field, you’ll see all the classes available for import. Check that Unit Dir Name is how you want it. Leave the Generate Component Wrappers checkbox empty, and then click Next. Then, select the Create Unit option and click Finish.

Import Component

  1. Include the generated unit in your files using the standard uses command, and build the application.

Include the unit and build the application

Example Use

The following code snippet demonstrates how to load a TIFF file and save it as a BMP:

procedure Test;
var
  LicenseManager1: Variant;
  GdPictureImaging1: _GdPictureImaging;
  TiffImageID  : Integer;
  Status: Integer;
begin
  LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
  LicenseManager1.RegisterKey('XXX');  //Please, replace XXX by a valid demo or commercial KEY
  GdPictureImaging1 := CreateComObject(CLASS_GdPictureImaging) as _GdPictureImaging;
  TiffImageID  := GdPictureImaging1.CreateGdPictureImageFromFile('d:\test.tif');
  Status := GdPictureImaging1.SaveAsBMP(TiffImageID, 'd:\output.bmp');
        if Status  <> 0 then
          MessageBox(0,Pchar('Error saving file. Status: ' + inttostr(Status)),'', 0)
        else
           MessageBox(0,Pchar('Done'),'', 0);
end;

Integrate into Microsoft Access

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Microsoft Access

Currently, we only provide examples in the [INSTALLATION FOLDER]\Samples\WinForm\msaccess folder using COM Interop .

Information

IntelliSense is fully supported in Microsoft Access.

If you want to resize GdPicture controls, here’s a helpful trick:

  • Use the menu at the top to insert an ActiveX control. Pick the GdPicture.NET user control. It’ll be the default size.

  • Then, select the lower-right corner and drag the size of the control to what you want. Save the form, close it, and then double-click to open it.

  • Be sure you also set the anchoring to the top-left corner of the control so Windows doesn’t try to resize it based on the form size.

Integrate into Visual FoxPro

Operating Requirements

GdPicture.NET runs on Microsoft Windows operating systems. It offers support dating back to Windows Vista and Windows Server 2008 in both 32-bit and 64-bit versions.

GdPicture.NET is available as a .NET Framework 4.5 and a .NET Core 3.0 assembly.

Both GdPicture.NET versions are compiled using the AnyCPU platform target.

Installing

Download the latest release

Once downloaded, follow the installation wizard, which will guide you through the installation process.

It’s recommended to install the toolkit in a destination such as D:\GdPicture.NET\ or C:\GdPicture.NET\.

Evaluating

The trial license lets you try the GdPicture.NET software package for free for 60 days. This includes full access and technical support.

How to Obtain a Trial License Key

To obtain your key, follow these steps:

  1. Go to the folder where you installed GdPicture.NET.

  2. Run licenseManager.exe.

  3. Click Request a trial key.

Request a trial key button

  1. Fill in the required fields, and then press Send Request.

Fill in fields and press Send Request

You’ll receive a trial key by email.

Information

If you don’t immediately receive a key via email, or if the application can’t be run on a system that allows web requests, contact the GdPicture sales team.

  1. Back in the License Manager, click the Register a key button and enter the trial key you received in your email.

Activating Your Commercial License for Development Purposes

When you acquire a commercial license, you need to activate it for development purposes.

If you don’t activate your license key properly, you’ll see an error message like the one below.

Activation error

Activation is mandatory for several reasons: It binds the license key to the developer, automatically creates their account for technical support, assigns the relevant service-level agreement (SLA), and allows development.

Warning

Activation requires access to ORPALIS servers. If your company has a mandatory proxy to access the internet, please configure it in the Proxy Settings menu before trying to activate your license key.

The licenseManager.exe Application

You’ll find the activation application (licenseManager.exe) in the installation folder of the SDK.

  • You need to launch it using administrator privileges.

  • When starting, the license key and license type will be #undefined#, so you’ll need to register a key. Click the Register a key button to access the registration form.

License manager

  • Enter your personal information in the fields. Be sure to enter a valid email address you have access to, because you’ll use it for technical support.

  • Once you’ve entered your information, click Register.

Key registration

When your license key is successfully activated, instead of #undefined#, you’ll see the key, along with its type, in the licenseManager.exe application main window.

Unlocking GdPicture.NET

Unlocking the GdPicture.NET toolkit is done via code in your application.

First create a LicenseManager object, and then call the RegisterKEY() method with the license key you own.

You need to do this when loading your application, before you use any of the functions or features of the GdPicture.NET toolkit.

Information

If your key is a trial license key, all the features of GdPicture will be activated.

Using Your License Key

You won’t be able to use the SDK for development purposes until it has been properly installed and activated through the LicenseManager.exe application located in the installation folder.

Here’s how to use your license key:

// Creating a `LicenseManager` object.
LicenseManager oLicenseManager = new LicenseManager();
oLicenseManager.RegisterKEY("LICENSE_KEY");
'Creating a `LicenseManager` object.
Dim oLicenseManager As New LicenseManager
oLicenseManager.RegisterKEY("LICENSE_KEY")
CLicenseManager oLicenseManager;
oLicenseManager.CreateDispatch(L"GdPicture14.LicenseManager");
oLicenseManager.RegisterKEY(L"LICENSE_KEY");
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager(__uuidof(LicenseManager));
   VARIANT_BOOL result = oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
}
BSTR bstrLicense = ::SysAllocString(L"LICENSE_KEY");
if (bstrLicense != NULL)
{
   _LicenseManagerPtr oLicenseManager;
   oLicenseManager = (_LicenseManagerPtr)CreateComObject(CLSID_LicenseManager);
   oLicenseManager->RegisterKEY(bstrLicense);
   ::SysFreeString(bstrLicense);
   bstrLicense = NULL;
}
var
   LicenseManager1: Variant;
begin
   LicenseManager1 := CreateOleObject('GdPicture14.LicenseManager');
   LicenseManager1.RegisterKey('LICENSE_KEY');
var oLicenseManager;
oLicenseManager = new ActiveXObject("GdPicture14.LicenseManager");
oLicenseManager.RegisterKey("LICENSE_KEY");
long ll_result
OLEObject oLicenseManager
oLicenseManager = CREATE OLEObject
ll_result = oLicenseManager.ConnectToNewObject("GdPicture14.LicenseManager")
oLicenseManager.RegisterKey("LICENSE_KEY")
Dim oLicenseManager As New LicenseManager
Call oLicenseManager.RegisterKEY("LICENSE_KEY")
Dim oLicenseManager As New GdPicture_NET_14.LicenseManager
oLicenseManager.RegisterKey ("LICENSE_KEY")

Visual FoxPro

Currently, we only provide examples in the [INSTALLATION FOLDER]\Samples\WinForm\vfp folder using COM Interop.

Information

IntelliSense is fully supported in Visual FoxPro.

We suggest adding the following line of code in the initialization of your program: application.AutoYield = .F.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Installing Node.js

If you haven’t installed Node.js, head to the official guides and follow the instructions. By the end of the installation process, you should be able to run the following command:

node --version

The output should be something like v14. You can ignore any subsequent number.

Generating the Application

You’ll use Express, one of the most common Node.js web frameworks. To create a new Express application, you can use the official generator.

Run:

npx express-generator pspdfkit_example --view=ejs

This command will generate a project structure and instruct you on the steps to follow to install dependencies and start the project.

Once you’ve followed all the steps, you should be able to visit http://localhost:3000 to confirm the application is working as expected.

Adding a Page to View the Document

You need to create a page that will show a document stored inside PSPDFKit Server.

You’ll want this page to be available at http://localhost:3000/documents/:id, where the document ID is the ID automatically assigned by PSPDFKit Server when uploading a document.

To achieve this, create a new route to display a document and mount it in the application.

  1. Create the documents route:

./routes/documents.js
var express = require("express");
var router = express.Router();

router.get("/:documentId", function (req, res, next) {
  res.render("documents/show", { documentId: req.params.documentId });
});

module.exports = router;

Inside the route, retrieve the ID captured by the routing logic and assign it to a documentId variable you can refer to in the view.

  1. Create a corresponding view with some minimal HTML that prints the document ID:

./views/documents/show.ejs
<h1>Show document <%= documentId %></h1>

  1. Mount the new route in the application:

./app.js
var indexRouter = require('./routes/index');
 var usersRouter = require('./routes/users');
+var documentsRouter = require("./routes/documents");
 // ...
 // rest of the file
 // ...
 app.use('/', indexRouter);
 app.use('/users', usersRouter);
+app.use("/documents", documentsRouter);

Stop and restart the Express server.

You can now visit http://localhost:3000/documents/:id, replacing :id with the ID of the document you uploaded to the PSPDFKit Server dashboard.

The page should contain the text Show document, followed by your document ID.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of JWTs to authenticate and authorize a viewer session against PSPDFKit Server.

To create JWTs, install the jsonwebtoken dependency:

npm install --save jsonwebtoken

Stop and restart the Express server.

Working with JWTs requires a private and public key pair. The private key is used by the Express application, while the public key is used by PSPDFKit Server.

The public key has already been configured in the PSPDFKit Server docker-compose.yml file via the JWT_PUBLIC_KEY environment variable.

To configure the private key, create a config/pspdfkit/jwt.pem file with the following contents:

./config/pspdfkit/jwt.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

Update ./routes/documents.js to read the private key so that it can be used to sign JWTs and pass them to the view.

In the claims, you pass the document ID, the set of permissions you want to have, and an expiry of one hour:

./routes/documents.js
var express = require("express");
 var router = express.Router();
+var fs = require("fs");
+var path = require("path");
+var jwt = require("jsonwebtoken");
+var jwtKey = fs.readFileSync(
+  path.resolve(__dirname, "../config/pspdfkit/jwt.pem")
+);

 router.get("/:documentId", function (req, res, next) {
+  var jwt = prepareJwt(req.params.documentId);
-  res.render("documents/show", { documentId: req.params.documentId });
+  res.render("documents/show", { documentId: req.params.documentId, jwt: jwt });
 });
+
+var prepareJwt = function (documentId) {
+  var claims = {
+    document_id: documentId,
+    permissions: ["read-document", "write", "download"],
+  };
+
+  return jwt.sign(claims, jwtKey, {
+    algorithm: "RS256",
+    expiresIn: 3 * 24 * 60 * 60, // 3 days
+  });
+};

 module.exports = router;

The encoded JWT is then assigned to the jwt variable, which can be referenced in the view:


./views/documents/show.ejs
<h1>Show document <%= documentId %></h1>
+<h1>JWT <%= jwt %></h1>

Stop and restart the Express server, and then refresh the page. You should now see a fairly long token printed on the page.

Loading an Existing Document

Update the view to load the SDK, passing the document ID and the JWT:

./views/documents/show.ejs
+<script src="http://localhost:5000/pspdfkit.js"></script>
 <h1>Show document <%= documentId %></h1>
 <h1>JWT <%= jwt %></h1>
+<!-- 2. Element where PSPDFKit will be mounted. -->
+<div id="pspdfkit" style="width: 100%; max-width: 800px; height: 480px;"></div>
+<!-- 3. Initialize PSPDFKit. -->
+<script>
+  PSPDFKit.load({
+    container: "#pspdfkit",
+    documentId: "<%= documentId %>",
+    authPayload: { jwt: "<%= jwt %>" },
+    instant: true
+  })
+    .then(function(instance) {
+      console.log("PSPDFKit loaded", instance);
+    })
+    .catch(function(error) {
+      console.error(error.message);
+    });
+</script>

Refresh the page, and you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Adding a Page to View the Document

You need to create a page that will show a document stored inside PSPDFKit Server.

You’ll want this page to be available at http://localhost:3000/documents/:id, where the document ID is the ID automatically assigned by PSPDFKit Server when uploading a document.

To achieve this, create a new route to display a document and mount it in the application.

  1. Create the documents route:

./routes/documents.js
var express = require("express");
var router = express.Router();

router.get("/:documentId", function (req, res, next) {
  res.render("documents/show", { documentId: req.params.documentId });
});

module.exports = router;

Inside the route, retrieve the ID captured by the routing logic and assign it to a documentId variable you can refer to in the view.

  1. Create a corresponding view with some minimal HTML that prints the document ID:

./views/documents/show.ejs
<h1>Show document <%= documentId %></h1>

  1. Mount the new route in the application:

./app.js
var indexRouter = require('./routes/index');
 var usersRouter = require('./routes/users');
+var documentsRouter = require("./routes/documents");
 // ...
 // rest of the file
 // ...
 app.use('/', indexRouter);
 app.use('/users', usersRouter);
+app.use("/documents", documentsRouter);

Stop and restart the Express server.

You can now visit http://localhost:3000/documents/:id, replacing :id with the ID of the document you uploaded to the PSPDFKit Server dashboard.

The page should contain the text Show document, followed by your document ID.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of JWTs to authenticate and authorize a viewer session against PSPDFKit Server.

To create JWTs, install the jsonwebtoken dependency:

npm install --save jsonwebtoken

Stop and restart the Express server.

Working with JWTs requires a private and public key pair. The private key is used by the Express application, while the public key is used by PSPDFKit Server.

The public key has already been configured in the PSPDFKit Server docker-compose.yml file via the JWT_PUBLIC_KEY environment variable.

To configure the private key, create a config/pspdfkit/jwt.pem file with the following contents:

./config/pspdfkit/jwt.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

Update ./routes/documents.js to read the private key so that it can be used to sign JWTs and pass them to the view.

In the claims, you pass the document ID, the set of permissions you want to have, and an expiry of one hour:

./routes/documents.js
var express = require("express");
 var router = express.Router();
+var fs = require("fs");
+var path = require("path");
+var jwt = require("jsonwebtoken");
+var jwtKey = fs.readFileSync(
+  path.resolve(__dirname, "../config/pspdfkit/jwt.pem")
+);

 router.get("/:documentId", function (req, res, next) {
+  var jwt = prepareJwt(req.params.documentId);
-  res.render("documents/show", { documentId: req.params.documentId });
+  res.render("documents/show", { documentId: req.params.documentId, jwt: jwt });
 });
+
+var prepareJwt = function (documentId) {
+  var claims = {
+    document_id: documentId,
+    permissions: ["read-document", "write", "download"],
+  };
+
+  return jwt.sign(claims, jwtKey, {
+    algorithm: "RS256",
+    expiresIn: 3 * 24 * 60 * 60, // 3 days
+  });
+};

 module.exports = router;

The encoded JWT is then assigned to the jwt variable, which can be referenced in the view:


./views/documents/show.ejs
<h1>Show document <%= documentId %></h1>
+<h1>JWT <%= jwt %></h1>

Stop and restart the Express server, and then refresh the page. You should now see a fairly long token printed on the page.

Loading an Existing Document

Update the view to load the SDK, passing the document ID and the JWT:

./views/documents/show.ejs
+<script src="http://localhost:5000/pspdfkit.js"></script>
 <h1>Show document <%= documentId %></h1>
 <h1>JWT <%= jwt %></h1>
+<!-- 2. Element where PSPDFKit will be mounted. -->
+<div id="pspdfkit" style="width: 100%; max-width: 800px; height: 480px;"></div>
+<!-- 3. Initialize PSPDFKit. -->
+<script>
+  PSPDFKit.load({
+    container: "#pspdfkit",
+    documentId: "<%= documentId %>",
+    authPayload: { jwt: "<%= jwt %>" },
+    instant: true
+  })
+    .then(function(instance) {
+      console.log("PSPDFKit loaded", instance);
+    })
+    .catch(function(error) {
+      console.error(error.message);
+    });
+</script>

Refresh the page, and you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Installing Ruby and Ruby on Rails

If you haven’t installed Ruby and Ruby on Rails, head to the official guides and follow the instructions. By the end of the installation process, you should be able to run the following command:

rails --version

The output should be something like Rails 6.1. You can ignore any subsequent number.

Generating the Application

You can start by generating a vanilla Rails application.

Run:

rails new pspdfkit_example

This command will take a minute or two. Once done, you should be able to cd pspdfkit_example and run:

bin/rails server

You can then visit http://localhost:3000 to confirm the application is working as expected.

Adding a Page to View the Document

You need to create a page that will show a document stored inside PSPDFKit Server.

You’ll want this page to be available at http://localhost:3000/documents/:id, where the document ID is the ID automatically assigned by PSPDFKit Server when uploading a document.

To achieve this, you need to update your routes and create a controller and view.

  1. Add a new route to the application:

./config/routes.rb
Rails.application.routes.draw do
   # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
+  resources :documents, only: :show
end

  1. Create a corresponding controller:

./app/controllers/documents_controller.rb
class DocumentsController < ApplicationController
  def show
    @document_id = params['id']
  end
end

Inside the controller, retrieve the ID captured by the routing logic and assign it to a @document_id instance variable you can refer to in the view.

  1. Create a corresponding view with some minimal HTML that prints the document ID:

./app/views/documents/show.html.erb
<h1>Show document <%= @document_id %></h1>

You can now visit http://localhost:3000/documents/:id, replacing :id with the ID of the document you uploaded to the PSPDFKit Server dashboard.

The page should contain the text Show document, followed by your document ID.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of JWTs to authenticate and authorize a viewer session against PSPDFKit Server.

To create JWTs, add the jwt dependency to the project Gemfile:

./Gemfile
# Use Active Model has_secure_password
 # gem 'bcrypt', '~> 3.1.7'
+gem 'jwt', '~> 2.2', '>= 2.2.2'

Stop the Rails server with Control-C, run bundle install to install the dependency, and then run bin/rails server to restart it.

Working with JWTs requires a private and public key pair. The private key is used by the Rails application, while the public key is used by PSPDFKit Server.

Create a config/pspdfkit/jwt.pem file with the following contents:

./config/pspdfkit/jwt.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

Add an initializer that will read the private key and store it in the application configuration so that it can be used to sign JWTs.

./config/initializers/pspdfkit.rb
Rails.configuration.x.pspdfkit.jwt_key = OpenSSL::PKey::RSA.new(Rails.root.join("config", "pspdfkit", "jwt.pem").read)

Then update DocumentsController to create a JWT to view the document:

./app/controllers/documents_controller.rb
class DocumentsController < ApplicationController
   def show
     @document_id = params['id']
+    @jwt = prepare_jwt(@document_id)
+  end
+
+  private
+
+  def prepare_jwt(document_id)
+    config = Rails.application.config.x.pspdfkit
+
+    claims = {
+      document_id: document_id,
+      permissions: %w[read-document write download],
+      exp: Time.now.to_i + 60 * 60
+    }
+
+    JWT.encode(claims, config.jwt_key, 'RS256')
   end
 end

In the claims, you pass the document ID, the set of permissions you want to have, and an expiry of one hour.

The encoded JWT is then assigned to the @jwt instance variable, which can be referenced in the view:

./app/views/documents/show.html.erb
<h1>Show document <%= @document_id %></h1>
+<h1>JWT <%= @jwt %></h1

If you refresh the page, you should now see a fairly long token printed on the page.

Loading an Existing Document

Update the view to load the SDK, passing the document ID and the JWT:

./app/views/documents/show.html.erb
+<script src="http://localhost:5000/pspdfkit.js"></script>
 <h1>Show document <%= @document_id %></h1>
 <h1>JWT <%= @jwt %></h1>
+<!-- 2. Element where PSPDFKit will be mounted. -->
+<div id="pspdfkit" style="width: 100%; height: 480px;"></div>
+<!-- 3. Initialize PSPDFKit. -->
+<script>
+  PSPDFKit.load({
+    container: "#pspdfkit",
+    documentId: "<%= @document_id %>",
+    authPayload: { jwt: "<%= @jwt %>" },
+    instant: true
+  })
+    .then(function(instance) {
+      console.log("PSPDFKit loaded", instance);
+    })
+    .catch(function(error) {
+      console.error(error.message);
+    });
+</script>

Refresh, and you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Adding a Page to View the Document

You need to create a page that will show a document stored inside PSPDFKit Server.

You’ll want this page to be available at http://localhost:3000/documents/:id, where the document ID is the ID automatically assigned by PSPDFKit Server when uploading a document.

To achieve this, you need to update your routes and create a controller and view.

  1. Add a new route to the application:

./config/routes.rb
Rails.application.routes.draw do
   # For details on the DSL available within this file, see https://guides.rubyonrails.org/routing.html
+  resources :documents, only: :show
end

  1. Create a corresponding controller:

./app/controllers/documents_controller.rb
class DocumentsController < ApplicationController
  def show
    @document_id = params['id']
  end
end

Inside the controller, retrieve the ID captured by the routing logic and assign it to a @document_id instance variable you can refer to in the view.

  1. Create a corresponding view with some minimal HTML that prints the document ID:

./app/views/documents/show.html.erb
<h1>Show document <%= @document_id %></h1>

You can now visit http://localhost:3000/documents/:id, replacing :id with the ID of the document you uploaded to the PSPDFKit Server dashboard.

The page should contain the text Show document, followed by your document ID.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of JWTs to authenticate and authorize a viewer session against PSPDFKit Server.

To create JWTs, add the jwt dependency to the project Gemfile:

./Gemfile
# Use Active Model has_secure_password
 # gem 'bcrypt', '~> 3.1.7'
+gem 'jwt', '~> 2.2', '>= 2.2.2'

Stop the Rails server with Control-C, run bundle install to install the dependency, and then run bin/rails server to restart it.

Working with JWTs requires a private and public key pair. The private key is used by the Rails application, while the public key is used by PSPDFKit Server.

Create a config/pspdfkit/jwt.pem file with the following contents:

./config/pspdfkit/jwt.pem
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

Add an initializer that will read the private key and store it in the application configuration so that it can be used to sign JWTs.

./config/initializers/pspdfkit.rb
Rails.configuration.x.pspdfkit.jwt_key = OpenSSL::PKey::RSA.new(Rails.root.join("config", "pspdfkit", "jwt.pem").read)

Then update DocumentsController to create a JWT to view the document:

./app/controllers/documents_controller.rb
class DocumentsController < ApplicationController
   def show
     @document_id = params['id']
+    @jwt = prepare_jwt(@document_id)
+  end
+
+  private
+
+  def prepare_jwt(document_id)
+    config = Rails.application.config.x.pspdfkit
+
+    claims = {
+      document_id: document_id,
+      permissions: %w[read-document write download],
+      exp: Time.now.to_i + 60 * 60
+    }
+
+    JWT.encode(claims, config.jwt_key, 'RS256')
   end
 end

In the claims, you pass the document ID, the set of permissions you want to have, and an expiry of one hour.

The encoded JWT is then assigned to the @jwt instance variable, which can be referenced in the view:

./app/views/documents/show.html.erb
<h1>Show document <%= @document_id %></h1>
+<h1>JWT <%= @jwt %></h1

If you refresh the page, you should now see a fairly long token printed on the page.

Loading an Existing Document

Update the view to load the SDK, passing the document ID and the JWT:

./app/views/documents/show.html.erb
+<script src="http://localhost:5000/pspdfkit.js"></script>
 <h1>Show document <%= @document_id %></h1>
 <h1>JWT <%= @jwt %></h1>
+<!-- 2. Element where PSPDFKit will be mounted. -->
+<div id="pspdfkit" style="width: 100%; height: 480px;"></div>
+<!-- 3. Initialize PSPDFKit. -->
+<script>
+  PSPDFKit.load({
+    container: "#pspdfkit",
+    documentId: "<%= @document_id %>",
+    authPayload: { jwt: "<%= @jwt %>" },
+    instant: true
+  })
+    .then(function(instance) {
+      console.log("PSPDFKit loaded", instance);
+    })
+    .catch(function(error) {
+      console.error(error.message);
+    });
+</script>

Refresh, and you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Integrate Server-Backed (for Web) with OpenShift

A version of PSPDFKit for Web Server-Backed that’s compatible with the OpenShift platform is currently in development.

Integrate Server-Backed (for Web) with OpenShift

A version of PSPDFKit for Web Server-Backed that’s compatible with the OpenShift platform is currently in development.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Generating the Application

Now, the application using PSPDFKit Server needs to be provisioned.

To use PSPDFKit Server, you’ll need a web application library or framework. Depending on the chosen technology, different steps might be necessary. Please refer to the technology/framework-specific guidelines for setting up the project.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of a JSON Web Token (JWT) to authenticate and authorize a viewer session against PSPDFKit Server.

You can generate JWTs using one of the libraries available in the programming language of your choice. The list of available libraries can be found at jwt.io.

When generating the JWT, make sure to use the RS256 signing algorithm and the private key below:

private key
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

When it comes to claims, you must provide the document ID, the set of permissions, and an expiry time in the future. Please note that some libraries might automatically inject the exp (expiration time) field, while other ones expect the field to be present in the payload. Please check the documentation of the chosen JWT library to see how it’s handled:

claims
{
  "document_id": documentId,
  "permissions": ["read-document", "write", "download"]
}

Loading an Existing Document

To view the document in the browser, first you need to load the PSPDFKit for Web JavaScript library. Please add the following script tag to the page that will present the document:

<script src="http://localhost:5000/pspdfkit.js"></script>

Then, on the same page, add the div element where the PSPDFKit for Web viewer will be mounted:

<!-- Element where PSPDFKit will be mounted. -->
<div id="pspdfkit" style="width: 100%; max-width: 800px; height: 480px;"></div>

Finally, add a script that will initialize the viewer:

<script>
  PSPDFKit.load({
    container: "#pspdfkit",
    documentId: documentId,
    authPayload: { jwt: jwt },
    instant: true
  })
    .then(function(instance) {
      console.log("PSPDFKit loaded", instance);
    })
    .catch(function(error) {
      console.error(error.message);
    });
</script>

There are two variables that need to be passed in: documentId and jwt. Please refer to the documentation of the web application framework you use to see how to pass variables to the page, or use hardcoded values. When you open the page, you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Requirements

PSPDFKit Server runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Server is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Setting Up PSPDFKit Server

Copy the code snippet below and save it anywhere on your computer in a file called docker-compose.yml:

version: "3.8"

services:
  pspdfkit:
    image: pspdfkit/pspdfkit:latest
    environment:
      PGUSER: pspdfkit
      PGPASSWORD: password
      PGDATABASE: pspdfkit
      PGHOST: db
      PGPORT: 5432
      API_AUTH_TOKEN: secret
      SECRET_KEY_BASE: secret-key-base
      JWT_PUBLIC_KEY: |
        -----BEGIN PUBLIC KEY-----
        MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA2gzhmJ9TDanEzWdP1WG+
        0Ecwbe7f3bv6e5UUpvcT5q68IQJKP47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24
        QvitzLNFphHdwjFBelTAOa6taZrSusoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwr
        t6HlY7dgO9+xBAabj4t1d2t+0HS8O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSo
        rgyJJSPCpNhSq3AubEZ1wMS1iEtgAzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt
        3O6q29kTtjXlMGXCvin37PyX4Jy1IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9Rrn
        AwIDAQAB
        -----END PUBLIC KEY-----
      JWT_ALGORITHM: RS256
      DASHBOARD_USERNAME: dashboard
      DASHBOARD_PASSWORD: secret
    ports:
      - 5000:5000
    depends_on:
      - db
  db:
    image: postgres:13.1
    environment:
      POSTGRES_USER: pspdfkit
      POSTGRES_PASSWORD: password
      POSTGRES_DB: pspdfkit
      POSTGRES_INITDB_ARGS: --data-checksums
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starting PSPDFKit Server

Now open a terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Go to the directory where you saved the docker-compose.yml file:

cd <path-to-directory-with-docker-compose-yml>

Run the following:

docker-compose up

This command might take a while to run, depending on your internet connection speed. Wait until you see the following message in the terminal:

pspdfkit_1  | Access the web dashboard at http://localhost:5000/dashboard

The PSPDFKit Server is now up and running!

Uploading a Document to PSPDFKit Server

With PSPDFKit Server running, visit http://localhost:5000/dashboard and authenticate using “dashboard” for the username and “secret” for the password. Choose Add Document and upload the document you want to work with.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

Once the document is uploaded, visit http://localhost:5000/dashboard/documents to see the list of available documents. Each document is identified by an ID. Take note of the ID of the document you just uploaded, as you’ll need it shortly.

Screenshot showing the create document modal window in the PSPDFKit Server Dashboard

The ID should look similar to 7KPS8X13JRB2G841X4V7EQ3T2J.

Creating a JSON Web Token (JWT)

PSPDFKit requires the use of a JSON Web Token (JWT) to authenticate and authorize a viewer session against PSPDFKit Server.

You can generate JWTs using one of the libraries available in the programming language of your choice. The list of available libraries can be found at jwt.io.

When generating the JWT, make sure to use the RS256 signing algorithm and the private key below:

private key
-----BEGIN RSA PRIVATE KEY-----
MIIEpQIBAAKCAQEA2gzhmJ9TDanEzWdP1WG+0Ecwbe7f3bv6e5UUpvcT5q68IQJK
P47AQdBAnSlFVi4X9SaurbWoXdS6jpmPpk24QvitzLNFphHdwjFBelTAOa6taZrS
usoFvrtK9x5xsW4zzt/bkpUraNx82Z8MwLwrt6HlY7dgO9+xBAabj4t1d2t+0HS8
O/ed3CB6T2lj6S8AbLDSEFc9ScO6Uc1XJlSorgyJJSPCpNhSq3AubEZ1wMS1iEtg
AzTPRDsQv50qWIbn634HLWxTP/UH6YNJBwzt3O6q29kTtjXlMGXCvin37PyX4Jy1
IiPFwJm45aWJGKSfVGMDojTJbuUtM+8P9RrnAwIDAQABAoIBAQDSKxhGw0qKINhQ
IwQP5+bDWdqUG2orjsQf2dHOHNhRwJoUNuDZ4f3tcYzV7rGmH0d4Q5CaXj2qMyCd
0eVjpgW0h3z9kM3RA+d7BX7XKlkdQABliZUT9SUUcfIPvohXPKEzBRHed2kf6WVt
XKAuJTD+Dk3LjzRygWldOAE4mnLeZjU61kxPYriynyre+44Gpsgy37Tj25MAmVCY
Flotr/1WZx6bg3HIyFRGxnoJ1zU1MkGxwS4IsrQwOpWEHBiD5nvo54hF5I00NHj/
ccz+MwpgGdjyl02IGCy1fF+Q5SYyH86DG52Mgn8VI9dseGmanLGcgNvrdJFILoJR
SZW7gQoBAoGBAP+D6ZmRF7EqPNMypEHQ5qHHDMvil3mhNQJyIC5rhhl/nn063wnm
zhg96109hVh4zUAj3Rmjb9WqPiW7KBMJJdnEPjmZ/NOXKmgjs2BF+c8oiLQyTQml
xB7LnptvBDi8MnEd3uemfxNuZc+2siuSzgditshNru8xPG2Sn99JC271AoGBANp2
xj5EfdlqNLd11paLOtJ7dfREgc+8FxQCiKSxbaOlVXNk0DW1w4+zLnFohj2m/wRr
bBIzSL+eufoQ9y4BT/AA+ln4qxOpC0isOGK5SxwIjB6OHhCuP8L3anj1IFYM+NX0
Xr1/qdZHKulgbS49cq+TDpB74WyKLLnsvQFyINMXAoGABR5+cp4ujFUdTNnp4out
4zXasscCY+Rv7HGe5W8wC5i78yRXzZn7LQ8ohQCziDc7XXqadmYI2o4DmrvqLJ91
S6yb1omYQCD6L4XvlREx1Q2p13pegr/4cul/bvvFaOGUXSHNEnUKfLgsgAHYBfl1
+T3oDZFI3O/ulv9mBpIvEXUCgYEApeRnqcUM49o4ac/7wZm8czT5XyHeiUbFJ5a8
+IMbRJc6CkRVr1N1S1u/OrMqrQpwwIRqLm/vIEOB6hiT+sVYVGIJueSQ1H8baHYO
4zjdhk4fSNyWjAgltwF2Qp+xjGaRVrcYckHNUD/+n/VvMxvKSPUcrC7GAUvzpsPU
ypJFxsUCgYEA6GuP6M2zIhCYYeB2iLRD4ZHw92RfjikaYmB0++T0y2TVrStlzXHl
c8H6tJWNchtHH30nfLCj9WIMb/cODpm/DrzlSigHffo3+5XUpD/2nSrcFKESw4Xs
a4GXoAxqU44w4Mckg2E19b2MrcNkV9eWAyTACbEO4oFcZcSZOCKj8Fw=
-----END RSA PRIVATE KEY-----

When it comes to claims, you must provide the document ID, the set of permissions, and an expiry time in the future. Please note that some libraries might automatically inject the exp (expiration time) field, while other ones expect the field to be present in the payload. Please check the documentation of the chosen JWT library to see how it’s handled:

claims
{
  "document_id": documentId,
  "permissions": ["read-document", "write", "download"]
}

Loading an Existing Document

To view the document in the browser, first you need to load the PSPDFKit for Web JavaScript library. Please add the following script tag to the page that will present the document:

<script src="http://localhost:5000/pspdfkit.js"></script>

Then, on the same page, add the div element where the PSPDFKit for Web viewer will be mounted:

<!-- Element where PSPDFKit will be mounted. -->
<div id="pspdfkit" style="width: 100%; max-width: 800px; height: 480px;"></div>

Finally, add a script that will initialize the viewer:

<script>
  PSPDFKit.load({
    container: "#pspdfkit",
    documentId: documentId,
    authPayload: { jwt: jwt },
    instant: true
  })
    .then(function(instance) {
      console.log("PSPDFKit loaded", instance);
    })
    .catch(function(error) {
      console.error(error.message);
    });
</script>

There are two variables that need to be passed in: documentId and jwt. Please refer to the documentation of the web application framework you use to see how to pass variables to the page, or use hardcoded values. When you open the page, you should see the PSPDFKit for Web viewer showing the document you just uploaded. If you annotate the document and refresh the page, all changes will be automatically persisted.

Please select the build system you’re using:

Gradle Build System

  1. In your top-level build.gradle file, add the PSPDFKit Maven repository:

allprojects {
	repositories {
		maven {
				url 'https://customers.pspdfkit.com/maven/'
		}
	}
}
  1. In the depending module’s build.gradle file, add the PSPDFKit dependency:

    dependencies {
        implementation 'com.pspdfkit:libraries-java:1.4.1'
    }
  2. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Add the new package dependency to your build.gradle file:

dependencies {
...
    implementation 'com.pspdfkit:libraries-java-ocr:1.4.1'
}

Maven Build System

  1. In your top-level pom.xml file, add the PSPDFKit Maven repository:

<repositories>
	<repository>
		<id>pspdfkit</id>
		<name>PSPDFKit Maven</name>
		<url>https://customers.pspdfkit.com/maven/</url>
	</repository>
</repositories>
  1. In the depending module’s pom.xml file, add the PSPDFKit dependency:

<dependencies>
	<dependency>
		<groupId>com.pspdfkit</groupId>
		<artifactId>libraries-java</artifactId>
		<version>1.4.1</version>
	</dependency>
</dependencies>
  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Add the new package dependency to your project pom.xml file:

<dependencies>
    ...
    <dependency>
        <groupId>com.pspdfkit</groupId>
        <artifactId>libraries-java-ocr</artifactId>
        <version>1.4.1</version>
    </dependency>

Using the PSPDFKit Java Library

  1. Now that the PSPDFKit Java Library is added, you can use the SDK in your application. You need to initialize the SDK prior to calling any other PSPDFKit method. Use the initializeTrial method if you haven’t yet bought a license key, or the initialize method if you have a key:

public void initializePSPDFKit() throws PSPDFKitInitializeException {
    PSPDFKit.initializeTrial();
}
@Throws(PSPDFKitInitializeException::class)
fun initializePSPDFKit() : Void {
    PSPDFKit.initializeTrial();
}
  1. Load a document with:

File file = new File("path/to/document.pdf");
PdfDocument document = PdfDocument.open(new FileDataProvider(file));
val file = File("path/to/document.pdf")
val document = PdfDocument.open(FileDataProvider(file))
  1. Once you have a document loaded, you can use the rest of the library. See the API docs and guides for more information, or try out the Catalog examples (see below).

Building and Running the Catalog App

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

gradlew.bat runJava

Only use the manual method if absolutely necessary. Otherwise, please refer to the main Integrating PSPDFKit Java Library guide for more details.

Please select the build system you’re using:

Gradle Build System

If you’re using the Gradle build system, a good example of how to integrate the PSPDFKit Java Library can be seen in the Catalog example distributed in the downloaded ZIP.

Complete the following steps for manual Gradle integration.

  1. Create a folder within your project named libs.

  2. Download the latest release.

  3. In the downloaded ZIP file, there will be a JAR file, pspdfkit-1.4.1.jar. Copy this JAR file into the libs folder you just created.

  4. In your project’s build.gradle folder, add a dependency to the copied JAR file (replace the wildcards with the version number):

dependencies {
	...
	implementation files('libs/pspdfkit-1.4.1.jar')

	// Required by PSPDFKit.
	implementation 'org.json:json:20180813'
	implementation 'org.apache.httpcomponents:httpclient:4.5.9'
	...
}

Now your Gradle project will depend upon the PSPDFKit JAR. More information about declaring dependencies can be found in the Gradle documentation.

  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Maven Build System

To use the PSPDFKit Java Library with Maven, it’s first necessary to install the PSPDFKit JAR to a Maven repository. Only when this is done can it be a reference for a Maven project.

  1. Download the latest release.

  2. Extract the files from PSPDFKit-Java-binary-1.4.1.zip into a known location.

  3. Within your project, using mvn on the command line, add the PSPDFKit JAR to a repository, replacing both the version (where necessary) and the path to the JAR and POM (extracted from PSPDFKit-Java-binary-1.4.1.zip):

mvn install:install-file -Dfile=/path/to/jar/pspdfkit-*.*.*.jar -DpomFile=/path/to/pom/pspdfkit-pom.xml

This will install the JAR to a local repository. It’s also possible to publish this JAR remotely; please see the Maven guides if this is a requirement.

  1. Add the PSPDFKit Java Library as a dependency of your project. In your project’s pom.xml, add the following, replacing the version with the target version:

...
<dependencies>
	<dependency>
		<groupId>com.pspdfkit.api</groupId>
		<artifactId>pspdfkit</artifactId>
		<version>1.4.1</version>
	</dependency>
</dependencies>
...

Now your Maven project will depend on the PSPDFKit JAR published to the chosen repository.

  1. Add the OCR dependency (optional). This is only necessary if you plan to use the OCR feature.

To use the PSPDFKit OCR feature with the PSPDFKit Java Library, a separate package, libraries-java-ocr, is required.

Using the PSPDFKit Java Library

  1. Now that the PSPDFKit Java Library is added, you can use the SDK in your application. You need to initialize the SDK prior to calling any other PSPDFKit method. Use the initializeTrial method if you haven’t yet bought a license key, or the initialize method if you have a key:

public void initializePSPDFKit() throws PSPDFKitInitializeException {
    PSPDFKit.initializeTrial();
}
@Throws(PSPDFKitInitializeException::class)
fun initializePSPDFKit() : Void {
    PSPDFKit.initializeTrial();
}
  1. Load a document with:

File file = new File("path/to/document.pdf");
PdfDocument document = PdfDocument.open(new FileDataProvider(file));
val file = File("path/to/document.pdf")
val document = PdfDocument.open(FileDataProvider(file))
  1. Once you have a document loaded, you can use the rest of the library. See the API docs and guides for more information, or try out the Catalog examples (see below).

Building and Running the Catalog App

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

./gradlew runJava

The PSPDFKit Java Library comes with an example application called the Catalog app, which contains many useful examples for exploring the different features of PSPDFKit and getting started quickly. You can find the app in the Example folder of the SDK ZIP file.

To build and run the Catalog app, follow these steps.

  1. Download the latest release.

  2. Extract PSPDFKit-Libraries-java_binary-{version}.zip to your desired location and cd into the root of its directory.

  3. cd into the Catalog (cd catalog).

  4. Build and run the Catalog application:

gradlew.bat runJava

This guide walks you through the steps necessary to start PSPDFKit Processor. It also shows you how to use it to process documents. By the end, you’ll be able to merge two PDF documents into one using Processor’s HTTP API from PHP.

Requirements

PSPDFKit Processor runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Processor is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Starting PSPDFKit Processor

First, open your terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Now run the following command:

docker run --rm -t -p 5000:5000 pspdfkit/processor:latest

This command might take a while to run, depending on your internet connection speed. Wait until you see a message like this in the terminal:

[info]  2021-03-02 18:56:45.286  Running PSPDFKit Processor version 2021.1.0. pid=<0.1851.0>

The PSPDFKit Processor is now up and running!

Installing PHP

The interaction with Processor happens via its HTTP API: You send documents and commands in the request and receive the resulting file in the response. To do this, you’ll invoke the API from the PHP script. But first, you need to install PHP for your operating system:

The easiest way to install PHP on macOS is via Homebrew. Follow the instructions on the Homebrew website to install it. Then, to install PHP, run:

brew install php@7.4 && brew link php@7.4

Verify the installation by running the following command in the terminal:

php --version

The output should start with PHP 7.4 — you can ignore the rest of the message.

ℹ️ Note: If the output doesn’t match the above, try restarting your terminal app by typing exit and opening it again.

  1. Download the PHP ZIP archive from the PHP website (pick the x86 Thread Safe build of the 7.4 release).

  2. Create a folder anywhere on your C: drive.

  3. Extract the ZIP archive into the folder you just created.

  4. Open the terminal and switch to that folder:

cd C:\path\to\directory

Now run the .\php.exe --version command. The output should start with PHP 7.4 — you can ignore the rest of the message.

To proceed, you’ll also need to create a PHP configuration file to enable a specific extension. So in the same directory, create a php.ini file with the following content:

[PHP]
extension=curl

Save the file, as you’ll need it shortly.

You can install PHP using your distribution’s package manager:

apt-get update && apt-get install -y php
dnf install -y php

Now run the php --version command. The output should start with PHP 7.4 — you can ignore the rest of the message.

Handling File Uploads

In this example project, the PDF files you’ll merge will be uploaded through a simple webpage via a standard HTML form. Create a file called index.php with the following content:

<!DOCTYPE html>
<html>
<head>
    <title>Merge PDFs with PSPDFKit Processor</title>
</head>
<body>
    <p>Upload the files to merge:</p>
    <form enctype="multipart/form-data" action="merge.php" method="post">
        <div>File 1: <input name="file1" type="file" accept="application/pdf"></div>
        <div>File 2: <input name="file2" type="file" accept="application/pdf"></div>
        <input type="submit" value= "Merge PDFs">
    </form>
</body>
</html>

Now open the terminal and type the following command in the same directory where you created the index.php file:

php -S localhost:8000
.\php.exe -c php.ini -S localhost:8000
php -S localhost:8000

Go to http://localhost:8000 in the browser. You should see a webpage similar to this:

A webpage with a form with two file inputs

When you choose files and click the Merge PDFs button, you’ll receive an error. This is because you haven’t yet written any code to handle the form submission.

Create a merge.php file in the same directory and add the following content to it:

<?php
$file1 = $_FILES['file1'];
$file2 = $_FILES['file2'];

echo $file1['name'], ", ", $file2['name'];
?>

Now when you go back to http://localhost:8000, choose the files, and submit the form, you should see the names of the files you picked printed on the screen:

A webpage with two file names

Merging PDFs

You can now use Processor’s API to merge the files uploaded from the browser. Replace the contents of the merge.php file with:

<?php
$file1 = $_FILES["file1"];
$file2 = $_FILES["file2"];

$headers = ["Content-Type" => "multipart/form-data"];
$postFields = [];
$postFields["file"] = curl_file_create(
    $file1["tmp_name"],
    $file1["type"],
    $file1["name"]
);

$postFields["file_to_import"] = curl_file_create(
    $file2["tmp_name"],
    $file2["type"],
    $file2["name"]
);

$postFields["operations"] = json_encode([
    "operations" => [
        [
            "type" => "importDocument",
            "document" => "file_to_import",
            "afterPageIndex" => "last",
        ],
    ],
]);

$request = curl_init();
curl_setopt($request, CURLOPT_URL, "http://localhost:5000/process");
curl_setopt($request, CURLOPT_HTTPHEADER, $headers);
curl_setopt($request, CURLOPT_POST, true);
curl_setopt($request, CURLOPT_POSTFIELDS, $postFields);
curl_setopt($request, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($request);

$status = curl_getinfo($request, CURLINFO_RESPONSE_CODE);
$file_size = curl_getinfo($request, CURLINFO_CONTENT_LENGTH_DOWNLOAD);
curl_close($request);

if ($status != 200) {
    echo "Request to Processor failed with status code " .
        $status .
        ': "' .
        $response .
        '".';
} else {
    header("Content-type: application/pdf");
    header('Content-Disposition: attachment; filename="result.pdf"');
    header("Content-Transfer-Encoding: binary");
    header("Content-Length: " . $file_size);
    header("Accept-Ranges: bytes");
    echo $response;
}
?>

Most of this code, up until you call curl_exec function, constructs a request that will be sent to Processor. Include an input file ("file"), a file you want to import ("file_to_import"), and a list of instructions for Processor so that it knows what to do with these files ("operations"). The operations you send tell Processor that it should import "file_to_import" after the last page of the input file ("file"). In your case, this means the second file will be appended to the first file.

The rest of the code deals with error handling, and if everything goes well, it returns the resulting file back to the browser.

You can check how it works in practice yourself! Go to http://localhost:8000, pick any two PDFs on your disk (or use these two if you don’t have any: file1.pdf, file2.pdf), and click Merge PDFs again. Depending on your browser, it will either automatically download the file for you or ask you for permission to download. In any case, look for the result.pdf file in the downloads folder on your computer. Open that file in any PDF viewer application. If you used the two files from the links above, you should see a five-page PDF document like this:

The result merging document with a cover page

That’s it! Now you know how to use Processor from PHP to perform operations on documents.

This guide walks you through the steps necessary to start PSPDFKit Processor. It also shows you how to use it to process documents. By the end, you’ll be able to merge two PDF documents into one using Processor’s HTTP API from Python.

Requirements

PSPDFKit Processor runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Processor is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Starting PSPDFKit Processor

First, open your terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Now run the following command:

docker run --rm -t -p 5000:5000 pspdfkit/processor:latest

This command might take a while to run, depending on your internet connection speed. Wait until you see a message like this in the terminal:

[info]  2021-03-02 18:56:45.286  Running PSPDFKit Processor version 2021.1.0. pid=<0.1851.0>

The PSPDFKit Processor is now up and running!

Installing Python

The interaction with Processor happens via its HTTP API: You send documents and commands in the request and receive the resulting file in the response. To do this, you’ll invoke the API from the Python script. But first, you need to install Python for your operating system:

To install Python, first you need to install the Xcode Command Line Tools. Install them by running the following command:

xcode-select --install

The easiest way to install Python on macOS is via Homebrew. Follow the instructions on the Homebrew website to install it. Then, to install Python, run:

brew install python

Verify the installation by running the following command in the terminal:

python3 --version

The output should start with Python 3.9 — you can ignore the rest of the message.

ℹ️ Note: ️If the output doesn’t match the above, try restarting the terminal app by typing exit and opening it again.

  1. Go to the Python downloads website.

  2. Scroll down to the bottom of the page until you find the Windows installer (64-bit) entry. Click on the link to download the installer.

  3. Open the installer. Make sure to check the Add Python 3.9 to PATH checkbox at the bottom of the window, and click Install Now.

  4. Complete the installation process.

Now start the terminal and run the python --version command. The output should start with Python 3.9 — you can ignore the rest of the message.

You can install Python using your distribution’s package manager:

apt-get update && apt-get install -y python3.9 python3-pip && ln -s /usr/bin/python3.9 /usr/bin/python3
dnf install -y python3 python3-pip

Now run the python3 --version command. The output should start with Python 3.9 — you can ignore the rest of the message.

Merging PDFs

To make HTTP requests to Processor’s API, you need an HTTP client library. For this scenario, you’ll use the excellent Requests package. Install it by running the following command:

python3 -m pip install requests==2.25.1
python -m pip install requests==2.25.1
python3 -m pip install requests==2.25.1

Now you can create a script to merge the PDFs. It’ll take two file paths as command-line arguments, send the files to Processor to merge them, and save the result in another file on disk. Create a merge.py file with the following content:

import sys
import json
import requests

if len(sys.argv) < 3:
    print("Too few arguments.")
    exit(1)

file1 = sys.argv[1]
file2 = sys.argv[2]

parts = {
    "file": open(file1, "rb"),
    "file_to_import": ("file_to_import.pdf", open(file2, "rb"), "application/pdf"),
    "operations": json.dumps(
        {
            "operations": [
                {
                    "type": "importDocument",
                    "afterPageIndex": "last",
                    "document": "file_to_import",
                }
            ]
        }
    ),
}

response = requests.post("http://localhost:5000/process", files=parts)

if response.status_code == 200:
    with open("result.pdf", "wb") as f:
        f.write(response.content)
else:
    print(
        f"Request to Processor failed with status code {response.status_code}: '{response.text}'."
    )

First, the script verifies that the number of arguments is correct and prepares the request data. Include an input file ("file"), a file you want to import ("file_to_import"), and a list of instructions for Processor so that it knows what to do with these files ("operations"). The operations you send tell Processor that it should import "file_to_import" after the last page of the input file ("file"). In your case, this means file2 will be appended to file1.

The rest of the code deals with error handling, and if everything goes well, it saves the result in the result.pdf file in the current working directory.

You can check how it works in practice yourself! Pick any two PDFs on your computer (or use these two if you don’t have any: file1.pdf, file2.pdf), and run the script:

python3 merge.py path/to/file1.pdf path/to/file2.pdf
python merge.py path/to/file1.pdf path/to/file2.pdf
python3 merge.py path/to/file1.pdf path/to/file2.pdf

Make sure to replace path/to/file1.pdf and path/to/file2.pdf with the actual location of the PDF files on your computer.

If you used the two files from the links above, you should see a five-page PDF document like this:

The result merging document with a cover page

That’s it! Now you know how to use Processor from Python to perform operations on documents.

This guide walks you through the steps necessary to start PSPDFKit Processor. It also shows you how to use it to process documents. By the end, you’ll be able to merge two PDF documents into one using Processor’s HTTP API via curl.

Requirements

PSPDFKit Processor runs on a variety of platforms. The following operating systems are supported:

  • macOS Monterey, Mojave, Catalina, or Big Sur

  • Windows 10 Pro, Home, Education, or Enterprise 64-bit

  • Ubuntu, Fedora, Debian, or CentOS. Ubuntu and Debian derivatives such as Kubuntu or Xubuntu are supported as well. Currently only 64-bit Intel (x86_64) processors are supported.

Regardless of your operating system, you’ll need at least 4 GB of RAM.

Installing Docker

PSPDFKit Processor is distributed as a Docker container. To run it on your computer, you need to install a Docker runtime distribution for your operating system.

Install and start Docker Desktop for Mac. Please refer to the Docker website for instructions.

Install and start Docker Desktop for Windows. Please refer to the Docker website for instructions.

Install and start Docker Engine. Please refer to the Docker website for instructions on how to install it for your Linux distribution.

After you install Docker, use these instructions to install Docker Compose.

Starting PSPDFKit Processor

First, open your terminal emulator.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use Terminal.app or iTerm2.

Use the terminal emulator integrated with your code editor or IDE. Alternatively, you can use PowerShell.

Use the terminal emulator integrated with your code editor or IDE, or one bundled with your desktop environment.

Now run the following command:

docker run --rm -t -p 5000:5000 pspdfkit/processor:latest

This command might take a while to run, depending on your internet connection speed. Wait until you see a message like this in the terminal:

[info]  2021-03-02 18:56:45.286  Running PSPDFKit Processor version 2021.1.0. pid=<0.1851.0>

The PSPDFKit Processor is now up and running!

Installing curl

The interaction with Processor happens via its HTTP API: You send documents and commands in the request and receive the resulting file in the response. To do this, you’ll first install curl so that it can call the API.

curl is bundled with macOS, so there are no extra steps you need to take to install it.

  1. Go to the curl website and download the curl for 64 bit package.

  2. Create a folder anywhere on your C: drive. Unzip the downloaded package and copy the curl.exe executable from the bin subfolder into the folder you just created.

  3. Open the terminal and switch to the directory where you placed the curl executable:

cd C:\path\to\directory

Now run the .\curl.exe --version command. The output should start with curl 7 — you can ignore the rest of the message.

curl is bundled with most desktop Linux distributions. You can check if it’s installed by running the curl --version command in the terminal. If you get an error, you can install it using your distribution’s package manager:

apt-get update && apt-get install -y curl
dnf install -y curl

Now run the curl --version command. The output should start with curl 7 — you can ignore the rest of the message.

Merging PDFs

Now that everything is set up, you can start using Processor to merge PDFs. More specifically, you’ll add a cover page to the existing document.

Download the example files using the following links: document, cover page. Now move both files to the same directory (if you’re running on Windows, use the same folder where you placed the curl.exe executable), and run the following command to merge the PDFs:

curl -X POST http://localhost:5000/process \
  -F file=@document.pdf \
  -F 'cover-page=@cover.pdf;type=application/pdf' \
  -F operations='{
  "operations": [
    {
      "type": "importDocument",
      "beforePageIndex": "first",
      "document": "cover-page"
    }
  ]
}' \
  -o result.pdf
curl.exe -X POST http://localhost:5000/process `
  -F file=@document.pdf `
  -F 'cover-page=@cover.pdf;type=application/pdf' `
  -F operations='{
  ""operations"": [
    {
      ""type"": ""importDocument"",
      ""beforePageIndex"": ""first"",
      ""document"": ""cover-page""
    }
  ]
}' `
  -o result.pdf
curl -X POST http://localhost:5000/process \
  -F file=@document.pdf \
  -F 'cover-page=@cover.pdf;type=application/pdf' \
  -F operations='{
  "operations": [
    {
      "type": "importDocument",
      "beforePageIndex": "first",
      "document": "cover-page"
    }
  ]
}' \
  -o result.pdf

Open the result.pdf file in any PDF viewer — you should see a five-page PDF document like this:

The result merging document with a cover page

That’s it! Now you know how to use Processor to perform operations on documents.