Skip to content

Commit ff36894

Browse files
bendersejbendersej
committed
docs: update documentation
1 parent 6f1c074 commit ff36894

File tree

7 files changed

+438
-77
lines changed

7 files changed

+438
-77
lines changed

‎README.md‎

Lines changed: 286 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -42,10 +42,250 @@ https://github.com/SimplePDF/simplepdf-embed/assets/10613140/8924f018-6076-4e44-
4242
# Features
4343

4444
- Client-based: the document and data filled in does not leave the browser
45-
- Add text, checkboxes, pictures, signatures to PDF documents
45+
- Add text, checkboxes, pictures, and signatures to PDF documents
4646
- Add, remove, re-arrange, rotate pages
4747
- Automatic detection of pre-existing PDF fields
4848

49+
# Data Privacy & companyIdentifier
50+
51+
SimplePDF Embed operates in two distinct modes with different privacy characteristics:
52+
53+
## Default Mode (Free Editor)
54+
55+
**When `companyIdentifier` is NOT specified or uses a reserved value:**
56+
57+
| Value | Mode | Description |
58+
| ------------------- | ------ | ------------------------------------------ |
59+
| Not set / `"embed"` | Editor | Free editor with full editing capabilities |
60+
| `"react-editor"` | Editor | Same as `embed`, for React integration |
61+
| `"viewer"` | Viewer | Read-only PDF viewer, no editing tools |
62+
| `"react-viewer"` | Viewer | Same as `viewer`, for React integration |
63+
64+
**In default mode:**
65+
66+
- All data stays in the browser - documents never leave the user's device
67+
- Documents are processed entirely client-side
68+
- No server communication for document processing
69+
- No account required
70+
- Includes "Powered by SimplePDF" branding
71+
- Form submissions are NOT collected (download only)
72+
73+
**Privacy Policy:** [What data we don't collect](https://simplepdf.com/privacy_policy#what-data-we-dont-collect)
74+
75+
## Company Mode (Paid Feature)
76+
77+
**When `companyIdentifier` IS specified:**
78+
79+
- Submissions are stored and accessible via your dashboard
80+
- Enables webhook integration for form automation (Basic plan+) - [learn more](https://simplepdf.com/help/how-to/configure-webhooks-pdf-form-submissions)
81+
- Custom branding - remove "Powered by SimplePDF", add your own logo, headless mode... (Pro plan+) - [learn more](https://simplepdf.com/help/how-to/customize-the-pdf-editor-and-add-branding)
82+
- Use your own S3/Azure Blob Storage for PDF documents (Pro plan+) - [learn more](https://simplepdf.com/help/how-to/use-your-own-s3-bucket-storage-for-pdf-form-submissions)
83+
84+
**Data Flow:**
85+
86+
```
87+
User fills PDF -> Clicks Submit -> Metadata sent to SimplePDF -> Webhook triggered -> Available in dashboard
88+
```
89+
90+
## Quick Reference
91+
92+
| Aspect | Default Mode | Company Mode |
93+
| --------------------- | ------------------------- | ------------------------------------------- |
94+
| `companyIdentifier` | Not set / reserved values | Your company ID |
95+
| Document storage | Browser only | Server (configurable) |
96+
| User notification | None needed | Shown before submit |
97+
| Submissions collected | No | Yes (Basic plan+) |
98+
| Branding | "Powered by SimplePDF" | Customizable (Pro plan+) |
99+
| Webhooks | Not available | Available (Basic plan+) |
100+
| BYOS (S3/Azure) | Not available | Available (Pro plan+) |
101+
| Price | Free | [Paid plans](https://simplepdf.com/pricing) |
102+
103+
# Branding Configuration
104+
105+
## Default Branding (Free Tier)
106+
107+
Without a SimplePDF account, the editor displays "Powered by SimplePDF" branding.
108+
109+
## Custom Branding (Pro Plan)
110+
111+
With a [Pro plan](https://simplepdf.com/pricing), you can:
112+
113+
- Remove "Powered by SimplePDF" entirely
114+
- Add your own company logo
115+
- Customize colors and appearance
116+
- Enable headless mode (no sidebar, programmatic controls only)
117+
118+
**To remove/customize branding:**
119+
120+
1. [Subscribe to a Pro plan](https://simplepdf.com/pricing)
121+
2. Go to your Dashboard
122+
3. Upload your logo or remove the sidebar entirely
123+
4. Use your `companyIdentifier` in the embed code:
124+
125+
```jsx
126+
// React - branding configured in your dashboard settings
127+
<EmbedPDF companyIdentifier="yourcompany">
128+
<button>Edit PDF</button>
129+
</EmbedPDF>
130+
```
131+
132+
```html
133+
<!-- Script tag - branding configured in your dashboard settings -->
134+
<script
135+
src="https://unpkg.com/@simplepdf/web-embed-pdf"
136+
companyIdentifier="yourcompany"
137+
defer
138+
></script>
139+
```
140+
141+
**Note:** Branding is configured through your SimplePDF dashboard, not via code props. The `companyIdentifier` links your embed to your dashboard settings.
142+
143+
For detailed customization options, see: [Customize the PDF Editor and Add Branding](https://simplepdf.com/help/how-to/customize-the-pdf-editor-and-add-branding)
144+
145+
# Architecture
146+
147+
## Client-Side Processing
148+
149+
SimplePDF Embed uses a **fully client-side architecture** for PDF processing:
150+
151+
```
152+
+-----------------------------------------------------+
153+
| User's Browser |
154+
| +-----------------+ +-------------------+ |
155+
| | Your App |-------->| SimplePDF | |
156+
| | | | Iframe | |
157+
| +-----------------+ +-------------------+ |
158+
| | | |
159+
| v v |
160+
| postMessage PDF editing / filling |
161+
| Events |
162+
+-----------------------------------------------------+
163+
| (Only with companyIdentifier)
164+
v
165+
+-----------------------------------------------------+
166+
| SimplePDF Servers |
167+
| Submission storage, webhooks, etc. |
168+
+-----------------------------------------------------+
169+
| (BYOS - Pro plan, optional)
170+
v
171+
+-----------------------------------------------------+
172+
| Your Own Storage (S3/Azure Blob Storage) |
173+
| For HIPAA compliance, data residency, etc. |
174+
+-----------------------------------------------------+
175+
```
176+
177+
## Benefits
178+
179+
| Benefit | Description |
180+
| ------------------- | --------------------------------------------------------------- |
181+
| **Privacy** | Documents never leave the browser (without `companyIdentifier`) |
182+
| **Security** | No server-side attack surface for document processing |
183+
| **Performance** | No upload/download latency for editing |
184+
| **Offline capable** | Works without internet after initial load |
185+
| **Cost efficient** | No server resources for document processing |
186+
| **GDPR friendly** | Data minimization - no server storage by default |
187+
188+
## Limitations
189+
190+
| Limitation | Description | Workaround |
191+
| --------------------------------- | ----------------------------------------------- | ---------------------------------------------------------- |
192+
| **No server-side PDF generation** | Cannot generate PDFs from templates server-side | Use client-side field creation via `createField()` |
193+
| **No bulk processing** | Cannot process multiple PDFs in batch | Process sequentially or use dedicated server-side library |
194+
| **No programmatic PDF retrieval** | Cannot get modified PDF as Blob/Base64 in JS | Use webhooks + server storage for programmatic access |
195+
| **No persistent storage** | PDFs don't persist without user action | Use `companyIdentifier` for server-side submission storage |
196+
| **Browser memory limits** | Very large PDFs (100+ MB) may cause issues | Recommend splitting large documents |
197+
198+
## When to Use SimplePDF Embed
199+
200+
**Good fit:**
201+
202+
- End-user PDF form filling
203+
- Document signing workflows
204+
- PDF annotation and commenting
205+
- Privacy-sensitive document handling
206+
- Embedding PDF editing in web apps
207+
208+
**Consider alternatives for:**
209+
210+
- Server-side PDF generation from templates
211+
- Bulk PDF processing pipelines
212+
- Automated document workflows (without user interaction)
213+
- Extracting raw PDF bytes programmatically
214+
215+
# Retrieving PDF Data
216+
217+
## Text Content Extraction
218+
219+
Use `getDocumentContent()` to extract text from the PDF. See the [React](./react/README.md#programmatic-control) or [Iframe](./documentation/IFRAME.md#get_document_content) documentation for implementation details.
220+
221+
## Downloading the Modified PDF
222+
223+
Use `submit({ downloadCopyOnDevice: true })` to trigger a browser download of the modified PDF.
224+
225+
## Server-Side PDF Generation & Storage
226+
227+
SimplePDF handles PDF generation and storage so you don't have to. When users submit, the filled PDF is automatically generated and stored - either on SimplePDF's servers or your own storage.
228+
229+
| Method | How It Works | Use Case |
230+
| ------------------------------------------- | ----------------------------- | ------------------------------------ |
231+
| `submit` with `downloadCopyOnDevice: true` | Browser downloads the PDF | End-user saves their work |
232+
| `submit` with `downloadCopyOnDevice: false` | PDF sent to SimplePDF servers | Server-side collection via webhooks |
233+
| S3/Azure Integration | PDF stored in your bucket | Programmatic access via your storage |
234+
235+
**Available integrations:**
236+
237+
- **Webhooks**: Get notified when submissions are received - [Configure webhooks](https://simplepdf.com/help/how-to/configure-webhooks-pdf-form-submissions)
238+
- **Bring Your Own Storage (BYOS)**: Store submissions directly in your storage - [S3 setup](https://simplepdf.com/help/how-to/use-your-own-s3-bucket-storage-for-pdf-form-submissions) / [Azure setup](https://simplepdf.com/help/how-to/use-your-own-azure-blob-storage-for-pdf-documents)
239+
240+
# Page Manipulation
241+
242+
SimplePDF includes built-in page manipulation capabilities:
243+
244+
| Feature | How to Access |
245+
| -------------------- | ------------------------------------------------------------ |
246+
| **Re-arrange pages** | Drag and drop pages in the thumbnail sidebar |
247+
| **Add pages** | Click "+" button in thumbnail sidebar or use "Add Page" menu |
248+
| **Remove pages** | Right-click page thumbnail -> "Delete page" |
249+
| **Rotate pages** | Right-click page thumbnail -> "Rotate" options |
250+
251+
## Enabling Page Manipulation
252+
253+
Page manipulation is **enabled by default** - no configuration required. Users access these features through the page thumbnail sidebar on the left side of the editor.
254+
255+
## Disabling Page Manipulation
256+
257+
**Using viewer mode (free):**
258+
259+
```jsx
260+
// React
261+
<EmbedPDF companyIdentifier="react-viewer" ... />
262+
```
263+
264+
```html
265+
<!-- Script tag -->
266+
<script ... companyIdentifier="viewer"></script>
267+
```
268+
269+
**Using Pro plan customization:**
270+
271+
With a [Pro plan](https://simplepdf.com/pricing), you can selectively disable page manipulation while keeping editing features enabled. In your dashboard:
272+
273+
- Toggle "Allow moving, rotating, deleting pages" to disable re-arrange/rotate/delete
274+
- Toggle "Allow adding new pages" to disable page insertion
275+
276+
See: [Customize the PDF Editor and Add Branding](https://simplepdf.com/help/how-to/customize-the-pdf-editor-and-add-branding)
277+
278+
## Programmatic Page Control
279+
280+
Currently, page manipulation (add/remove/re-arrange/rotate) is only available through the UI. There are no programmatic APIs for these operations. If you need this feature, [file an issue on the repository](https://github.com/SimplePDF/simplepdf-embed/issues).
281+
282+
**Available programmatic navigation:**
283+
284+
```jsx
285+
// Navigate to a specific page
286+
await actions.goTo({ page: 3 });
287+
```
288+
49289
# Get started
50290

51291
[⚛️ Using the `EmbedPDF` React component](./react/README.md)
@@ -58,13 +298,13 @@ https://github.com/SimplePDF/simplepdf-embed/assets/10613140/8924f018-6076-4e44-
58298

59299
- Fully-fledged PDF viewer & PDF form editor with a simple wrapper
60300
- Completely free to use
61-
- Insanely small footprint ([1.5KB gzipped](https://bundlephobia.com/package/@simplepdf/react-embed-pdf))
301+
- Tiny footprint (~5KB gzipped)
62302

63303
# FAQ
64304

65-
### This seems too good to be true, is it free?
305+
### Is SimplePDF Embed free?
66306

67-
Yes! The embed editor is and will remain free, it comes with a branding ("Powered by SimplePDF") that can be replaced (or removed) with your own logo under the [Premium Plan](https://www.simplepdf.com/pricing)
307+
Yes. The embed editor is free with no usage limits. It includes "Powered by SimplePDF" branding, which can be customized or removed with a [Pro plan](https://www.simplepdf.com/pricing).
68308

69309
### What happens to the document my users load and the data they fill in?
70310

@@ -78,7 +318,47 @@ The users are notified that the document and the data they submit is sent to the
78318

79319
The library is a simple wrapper around an Iframe that loads SimplePDF on-demand (whenever the user clicks the wrapped link), as such the footprint for this "opening an Iframe" mechanism is very tiny, the SimplePDF editor is of course bigger, but your users won't download anything until they have clicked the link. Think "lazy-loading".
80320

81-
82321
### I'm looking for a PDF viewer only, can I disable the editing features?
83322

84-
You can use SimplePDF as a PDF viewer by specifying `viewer` as a `companyIdentifier`.
323+
Yes! Use viewer mode to display PDFs without any editing capabilities.
324+
325+
**React:**
326+
327+
```jsx
328+
<EmbedPDF
329+
companyIdentifier="react-viewer"
330+
mode="inline"
331+
documentURL="https://example.com/document.pdf"
332+
style={{ width: 900, height: 800 }}
333+
/>
334+
```
335+
336+
**Script tag:**
337+
338+
```html
339+
<script
340+
src="https://unpkg.com/@simplepdf/web-embed-pdf"
341+
companyIdentifier="viewer"
342+
defer
343+
></script>
344+
```
345+
346+
**Iframe:**
347+
348+
```html
349+
<iframe src="https://viewer.simplepdf.com/editor?open=PDF_URL"></iframe>
350+
```
351+
352+
**What's disabled in viewer mode:**
353+
354+
- All annotation tools (text, checkbox, signature, picture)
355+
- Form field editing
356+
- Page manipulation (add, remove, rotate, re-arrange)
357+
- Submit functionality
358+
359+
**What remains available:**
360+
361+
- PDF viewing and navigation
362+
- Zoom controls
363+
- Page thumbnails
364+
- Download original PDF

‎bubble/README.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
1-
</br>
2-
</br>
1+
<br/>
2+
<br/>
33
<div align="center">
44
<a href="https://simplepdf.com" target="_blank">
55
<picture>
@@ -12,8 +12,8 @@
1212
<div align="center">
1313
Add a powerful PDF editor directly into your Bubble app.
1414
</div>
15-
</br>
16-
</br>
15+
<br/>
16+
<br/>
1717
<p align="center">
1818
<br/>
1919
<a href="https://bubble.io/plugin/pdf-editor-and-filler-1673591701449x899138091362287600" rel="dofollow"><strong>Read more about SimplePDF for Bubble.io »</strong></a>

0 commit comments

Comments
 (0)