Skip to content

README.md

Latest commit

 

History

History
209 lines (153 loc) · 5.88 KB

README.md

File metadata and controls

209 lines (153 loc) · 5.88 KB
Raw



Add a powerful PDF editor directly into your website.



Read more about SimplePDF Embed »

Join Our Discord · Follow us on Twitter



Open PDF files with SimplePDF, using a simple script tag.

Show me an example!

How to use

I don't have an account on SimplePDF:

Add this script in the head of your webpage:

<script src="https://unpkg.com/@simplepdf/web-embed-pdf" defer></script>

I have an account on SimplePDF:

Replace companyIdentifier with your own

<script
  src="https://unpkg.com/@simplepdf/web-embed-pdf"
  companyIdentifier="yourcompany"
  defer
></script>

See Data Privacy & companyIdentifier for details on how data is handled.

How does it work?

Anchor links (a) with an href pointing to a PDF file (.pdf, in any case, with or without a query string or fragment) or SimplePDF forms are automatically opened in SimplePDF

I don't want every PDF document to be opened in SimplePDF

Exclude any anchor tags from opening SimplePDF by adding the class exclude-simplepdf:

<a href="/example.pdf" class="exclude-simplepdf">Doesn't open with SimplePDF</a>

My PDF file doesn't have a .pdf extension

Add a class simplepdf to any anchor tag to open them with SimplePDF:

<a href="/example_without_pdf_extension" class="simplepdf">Open with SimplePDF</a>

Advanced usage

In case you want to have more control over how the modal for editing PDFs is invoked, you can directly interact with the simplePDF global variable that is injected in the window by the script.

Overriding the automatic locale detection

SimplePDF automatically detects the language of the page (using the lang attribute) and supports the following languages:

  • English (en)
  • German (de)
  • Spanish (es)
  • French (fr)
  • Italian (it)
  • Japanese (ja)
  • Dutch (nl)
  • Portuguese (pt)

If you wish to override the automatic detection, you can specify the locale attribute on the script tag as follows:

<script
  src="https://unpkg.com/@simplepdf/web-embed-pdf"
  companyIdentifier="yourcompany"
  locale="fr"
  defer
></script>

In-browser agents (WebMCP)

While the editor is open, an agent running in the visitor's browser (ChatGPT's browser, Chrome with WebMCP) finds the editor's operations as tools on your page: read and fill fields, move between pages, submit. Every call goes through the same permissions as any other integration. Nothing happens in browsers without an agent.

To turn it off, add webmcp="false" to the script tag (any value other than true or false turns it off and logs an error):

<script
  src="https://unpkg.com/@simplepdf/web-embed-pdf"
  companyIdentifier="yourcompany"
  webmcp="false"
  defer
></script>

Or from JavaScript:

// Turn it off
window.simplePDF.setConfig({ webMCP: { enabled: false } });

// Keep it on, but withhold the operations a person must do themselves
window.simplePDF.setConfig({ webMCP: { enabled: true, exclude: ['submit'] } });

The option applies to the next editor opened: an editor already open keeps the tools it registered until it closes.

Opening the editor programmatically

Open the editor with a specific PDF

window.simplePDF.openEditor({ href: 'publicly_available_url_pdf' });

Let your customers pick the PDF on their computer

window.simplePDF.openEditor({ href: null });

Closing the editor programmatically

window.simplePDF.closeEditor();

Specifying a context

The context is sent as part of the submission via the webhooks integration: read more

Use-cases:

  • Link a submission back to a customer
  • Specify the environment / configuration of the editor

Do not store sensitive information in the context (!!) as it is available locally to anyone inspecting the code

window.simplePDF.openEditor({
  href: 'publicly_available_url_pdf',
  context: {
    customer_id: '123',
    environment: 'prod',
  },
});

Updating the configuration programmatically

Use-cases:

  • Change the locale at run time
  • Enabling / Disabling Auto Open: automatically opening the editor for anchor tags pointing to PDF files. By default enabled when SimplePDF is added as a script
  • Change the company identifier at run time
window.simplePDF.setConfig({
  locale: 'fr',
  autoOpen: false,
});

Viewer Mode (Read-Only)

To use SimplePDF as a PDF viewer with all editing features disabled:

<script src="https://unpkg.com/@simplepdf/web-embed-pdf" companyIdentifier="viewer" defer></script>

Or programmatically:

window.simplePDF.setConfig({ companyIdentifier: 'viewer' });
window.simplePDF.openEditor({ href: 'https://example.com/document.pdf' });

See the main README for more details on what's disabled in viewer mode.