Yumpu Embed – Documentation

Yumpu Embed is an ExpressionEngine 7 add-on for managing Yumpu PDF flipbooks without leaving the control panel: a channel field that browses your Yumpu account or uploads a PDF from the publish page, a customizable JavaScript player with a live preview, site-wide upload and player defaults, a document editor, and a set of MCP tools for AI assistants through MCP Server For EE.

Requirements

• ExpressionEngine 7.2 or later.
• PHP 8.1 or later with the curl extension (standard on typical EE hosts).
• A Yumpu account and API token (Yumpu → Account → API). Some document settings are gated by the Yumpu plan; the add-on drops settings your plan does not accept rather than failing the upload.
• Optional: MCP Server For EE 1.0.0 or later for the MCP tools (it needs PHP 8.2 or later itself).
• The Control Panel and the site must be served from the same origin (scheme and host): the field's picker, upload and editor calls are front-end actions sent with the editor's session cookie.

Installation, upgrades & uninstall

1. Unzip the release and copy the yumpu_embed/ folder to system/user/addons/yumpu_embed/.
2. In the Control Panel go to Developer → Add-ons and install Yumpu Embed.
3. Open the add-on's Settings page and enter your Yumpu API token. The token is stored encrypted and shown masked afterwards.
4. Add a Yumpu Embed field to a channel (it is also available as a Grid column and inside Fluid).
5. Using the MCP tools? In MCP Server For EE → Tools → External tools, enable the Yumpu Embed tools you want exposed. Every external tool starts disabled, including tools added by a later release.

Upgrading: replace the folder and run the add-on's Update from the Add-ons page. New front-end endpoints and database migrations are registered there, so the publish page may misbehave until the update has run.

Uninstalling removes the add-on's settings, cache, player templates, and the registry of embed objects it created. Field data in your channels stays in place, and the documents and embed objects on Yumpu are untouched. After a reinstall the orphaned-embed sweep can no longer tell objects made before the uninstall from dashboard-made ones, so it leaves them alone.

Control Panel pages

The add-on's pages live under Developer → Add-ons → Yumpu Embed, with their own sidebar. Only members with Add-ons Manager access reach them; the field itself works for any member who can create or edit entries. Creating, updating, deleting and importing player templates needs the same access as these pages (the Can access add-ons permission with Yumpu Embed assigned to one of the member's roles under Role → Add-on access), from the field's editor as much as from here; applying a template to an entry does not.

Settings

• Yumpu API token — leave the box blank on later saves to keep the stored token. Clear cache drops the cached account listings after you change documents on yumpu.com.
• Auto-load publications on entry load — whether an empty field loads the first page of your account when the publish page opens.
• Documents per page — how many publications the picker and the Documents page load at a time (multiples of 12, so every card layout fills its rows).

Upload Defaults

Site-wide settings applied to every PDF uploaded through the add-on, from the publish page or through MCP. Per-upload overrides win per key.

• ExpressionEngine Files — the PDF upload destination. Yumpu only sends the PDF straight to Yumpu and stores nothing in EE. Choosing an upload directory saves every PDF to that directory first (it appears in the File Manager and is available to templates as {field:pdf_url}), then sends it to Yumpu.
• Basic Information, Visibility, Player Permissions, Analytics, PROKiosk & Advanced — the document settings Yumpu accepts at creation (language, category, tags, visibility, download/print/share permissions, Google Analytics, PROKiosk ids, and so on).
• Applied After Upload — the handful of settings Yumpu refuses at creation time (for example the recommended-documents sidebar). The add-on applies them to the new document the moment conversion finishes.
• Backup & Restore — export the page as a versioned JSON file and import it on another site. The import validates the file and reports any setting it had to drop (for example an upload directory that does not exist on the target site).

Embed Settings

• Default Player Settings — the site-wide player configuration, edited with a live preview of any document from your account. Entries that never applied their own settings render with these defaults, and changes here reach them immediately.
• Player Templates — named, reusable player configurations. Save the editor as a template, load one back, update or delete it, and export or import the whole set as JSON. See Player settings for how templates stay linked to entries.
• Default Embed Dimensions — the width and height used on the front end when neither the field settings nor the template tag supply them.
• Embed Objects — a collapsed maintenance section for Advanced Styling. Check embed objects inventories the account (objects in use by entries, open previews, objects the add-on did not create); Delete orphaned embed objects (Super Admins only) removes objects the add-on created that no entry references any more, up to 40 per run. Objects made on yumpu.com are never touched.

Documents

Browse the connected account with the same card picker the field uses, and open any document in the Edit Document modal to change its title and settings, see which entries use it, or delete it. Nothing here selects a document for an entry; it is a management view.

The Yumpu Embed field

On the publish page an empty field shows a document URL/ID box with Load, plus Browse and Upload.

• Load accepts a numeric document ID or any Yumpu URL that carries one (view, read, or account edit URLs) and selects that document with its title and cover.
• Browse pages through your account as cards (cover, title, ID). Click a card or its Select button to choose it; Edit opens the document editor.
• Upload sends a PDF to Yumpu and selects the new document when conversion finishes, with upload and conversion progress shown in the field. With an EE upload directory configured, the panel is ExpressionEngine's native file widget (drop zone, Choose Existing, Upload New) pointed at that directory and the PDF lands in the File Manager first; without one it is a simple drop zone. Uploading requires the member's role to have access to that directory, the same rule as EE's own file fields. A PDF chosen from the File Manager but not yet sent to Yumpu survives an entry save as a pending upload, so the editor can come back and finish it.

Once a document is selected the field shows its cover, title, and ID with these controls:

• Edit Document — title and Yumpu document settings, the entries that use the document, the document's embed code, and (for Super Admins) delete. See Editing and deleting documents.
• Embed Settings — the player editor for this entry, with a live preview. See Player settings.
• Change reopens the picker on a fresh first page; Clear empties the field.
• Link PDF / Change PDF / Unlink — shown when Upload Defaults names an EE upload directory. A document that never went through the field's upload panel (picked from Browse, loaded by ID, or uploaded on the Yumpu dashboard) has no File Manager PDF behind it, so {field:pdf_url} is empty for it. Link PDF opens EE's file picker on that directory and attaches an existing PDF to the stored document; nothing is uploaded and Yumpu is not called. Documents uploaded through the field are linked automatically.

Field settings let a field use the site-wide default dimensions (the default) or, with that toggle set to No, its own width and height. The field declares itself compatible with Grid and Fluid, and every control above works in those placements too.

Required fields: clearing a required field flags it immediately and disables Save until a document is selected again.

Player settings, templates & Advanced Styling

Every entry renders through Yumpu's JavaScript player. The settings the player honors are the ones the editor offers: start page, single-page view, autoflip, language, canvas and fullscreen background colors, page numbers, logo, search, and the fullscreen share, download, and print buttons. Anything else the Yumpu documentation lists is silently ignored by the current player, so the add-on does not offer it.

Settings resolve in three tiers, and the contract between them is worth knowing:

1. Site defaults (Embed Settings page) apply live to every entry whose editor was never applied.
2. Templates are live-linked. An entry stays linked to a template only while its settings exactly match it, so editing the template on the Embed Settings page updates every linked entry. Change anything in the entry's own editor and it becomes a frozen snapshot; a deleted template leaves its entries with their snapshot.
3. Per-render overrides from the template tag (player_settings, width, height) win over both for that render only.

Advanced Styling is a collapsed section of the editor: a header title with its own font family, size, weight, style and color, the headline and username toggles, and the menubar auto-hide, table of contents, and page overview toggles. These render through a Yumpu embed object that the add-on creates on your account and keeps in step with the entry's effective settings at every entry save; template and site-default edits push their linked entries' objects out immediately (up to 40 embed writes per save, the rest catching up on those entries' next save). Tag-parameter overrides cannot reach an embed object. The editor previews Advanced Styling through a scratch object that is released when the editor closes.

Player Permissions vs. player settings. The download, print, and share buttons of the embedded view are the document's permissions (Player Permissions in Upload Defaults or the Edit Document modal), while the editor's share, download, and print toggles govern the fullscreen view only. Yumpu serves the embedded view from a cached copy of the document that an API save does not refresh; see Yumpu platform notes.

Template tags & modifiers

{my_yumpu_field}

renders the player. Optional parameters:

{my_yumpu_field width="100%" height="600px"}
{my_yumpu_field player_settings='{"autoflip":"1","pageview":"single"}'}

• width / height override the field's and the site's default dimensions.
• player_settings is a JSON object merged over the entry's settings for that render.

Modifiers expose the stored document without rendering a player:

pdf_url and file_id are set when the PDF went to Yumpu through the field, or when an existing File Manager PDF was attached with Link PDF. Documents picked from Browse or uploaded on the Yumpu dashboard have no PDF linked until then. The URL is built from the EE file record at render time, so moving the upload directory needs no re-save.

A field whose PDF is waiting to be sent to Yumpu holds a small pending value, so {if my_yumpu_field} is true for it while every tag and modifier renders nothing. Test for a real document with {if my_yumpu_field:id}.

The field also works as a Grid column and inside Fluid; the same parameters and modifiers apply through EE's usual {grid_field:column} and Fluid syntax.

Sizing

Dimensions resolve tag → field settings → Embed Settings defaults → 100%×100% of the wrapping element. If the wrapper has no height the player falls back to 70vh and logs a console note explaining why; the intended setup is a sized container:

<div style="aspect-ratio:4/3">{book_flipbook}</div>

All embeds on a page share a single Yumpu player instance, as Yumpu's JavaScript FAQ recommends. If Yumpu's player script cannot load, the field falls back to a plain iframe of the document's embed URL, which is the only place the embed code's own dimensions are used.

Editing and deleting documents

Edit Document (from the field's selected state, a Browse card, or the Documents page) reads the document's current settings from Yumpu and saves the ones you change: title, description, language, category, tags, visibility, download and sharing permissions, player permissions, Google Analytics, and PROKiosk ids. The change applies everywhere the document is embedded. A few dashboard-only toggles the API cannot change are shown read-only.

The modal also shows Used in N entries: every entry that holds the document in a Yumpu Embed field, including Grid columns, Fluid blocks, and Grids inside Fluid, with links to edit them.

Embed Code at the bottom of the modal offers the same copy-and-paste snippets as the Yumpu dashboard's Embed Code panel — Responsive iFrame (full width, fixed height, page dimensions stamped on the wrapper), iFrame, and a JavaScript player snippet — each with a Copy button. Every snippet embeds a Yumpu embed object. Until the document has been styled, that object is the bare preset Yumpu returns with the document, which renders with Yumpu's defaults (a dark background); the panel says so. The first time the modal opens from an entry whose document has no share object, it styles the document from that entry automatically, so the snippets are ready to copy; it never restyles automatically after that, because outside sites may embed the object. Style with this entry's player settings (or the automatic first styling) creates one durable share object for the document that mirrors the entry's effective player look — background and fullscreen colours, page view, start page, autoflip, the player-element toggles, and Advanced Styling — and rebuilds the snippets on it, so what a client embeds looks like the site. Refresh styling from this entry updates that same object in place, so snippets already handed out pick up the new look without being replaced. On the Documents page, where there is no entry, a chooser next to the button styles from the site default player settings or any saved player template. Share objects survive entry saves and the orphan sweep and are deleted only with the document. Player Permissions (download, print, share) always come from the document. The same snippets are available through the yumpu_embed_get_embed_code MCP tool, styled when a share object exists, and yumpu_embed_style_embed_code styles a document from the site defaults or a template the way the modal does.

Delete on Yumpu… is available to Super Admins only. It deletes the document on Yumpu, then clears every listed placement (re-checking each one first), deletes the embed objects those entries owned, and refreshes the caches. Type the document ID to confirm; the usage list is the blast radius. The delete is refused if the usage scan fails, so nothing is removed blind. Documents are never deleted from Yumpu when an entry is deleted or a field is cleared.

MCP tools

With MCP Server For EE 1.0.0 or later installed, Yumpu Embed registers nineteen tools on the authenticated MCP endpoint. Each starts disabled until a Super Admin enables it under Tools → External tools, and every call is scope-checked and audit-logged by the host. The scope column is the OAuth scope a client's token must hold. Every tool also carries MCP tool annotations, so clients know which are read-only and which are destructive before calling them. The host's get_channel also reports every Yumpu Embed field with build_with: yumpu_embed_build_field_value and a value format that tells the assistant to obtain the value from the tools rather than hand-write it.

The publish pipeline, end to end: put the PDF in the File Manager with the host's upload_file (into the directory the Upload Defaults name; the upload tool's description states it, and a PDF from any other directory is refused), send it to Yumpu with upload_document_from_file, poll get_upload_progress with the same fileId until it returns a field_value, and pass that as the field's value in the host's create_entry or update_entry together with the cover file, categories, and status. For an entry that already holds a value, build the new one with build_field_value and pass the current stored value as currentValue so its PDF link, player settings and embed object survive. The failure mode to know: a build without currentValue replaces the whole value, so on an entry that already links a PDF, building without fileId and without currentValue and saving the result drops the link — no error, {field:pdf_url} just stops resolving. The tool's usage text says so whenever neither was given; treat it as a stop sign when the entry is not new.

Bulk linking of existing documents and PDFs is one loop: page documents with list_documents and files with the host's list_files, then one build_field_value (with fileId and currentValue) + update_entry per entry. Pace it on numbers: each build reads one document from Yumpu (150 such reads per 15 minutes), and every build_field_value and get_upload_progress result carries a quota block for the family it consumed — calls used, budget, remaining, and when the window resets — while yumpu_embed_quota reports every family. The cost model, measured: assume every entry save re-reads its document. It does for every document Yumpu has never HTML-rendered, which is the common case on an account with pre-2026 dashboard uploads (often most of an account that predates 2026), because those get two-hour thumbnail URLs whatever expiry is asked for and the fieldtype refreshes a stored value whose thumbnail expires within thirty days; it also does for upload results and for values about eleven months old. Only a stored value of an HTML-rendered document skips the read. The read goes through the same fifteen-minute cache a build fills, so a build-then-save pair on one document costs one call, not two, and a bulk-link pass costs one document read per distinct document per fifteen minutes; only repeat touches of the same document within that window are free. The save reports that itself: every create_entry, update_entry or update_entries result whose call touched a Yumpu Embed field carries field_reports.<field>.quota, the same block, read after the save (get_channel marks the field after_write: true). Keep a margin only for what the ledger cannot see: calls made by other clients of the same Yumpu token (the dashboard, another site).

Yumpu platform notes

• Rendering. Uploads are created with HTML5 rendering so the player version is built during conversion; Yumpu's own default can leave a document without a playable version for hours or longer. This is a creation-time setting that cannot be changed afterwards.
• Cached embedded view. Yumpu serves the embedded player from a cached copy of the document. Saving settings through the API (this add-on, or the MCP tools) does not refresh that copy, while saving in the Yumpu dashboard does. If a permission change does not show in an embed, open the document in the Yumpu dashboard and save it once.
• Rate limits and daily caps. Yumpu limits uploads to 50 per 15 minutes and progress checks to 150 per 15 minutes, and plans carry a daily upload cap that counts rejected uploads too. The add-on polls conversion every three seconds and caches account listings to stay well inside these.
• Embed colours through the API. The embed API accepts a bare six-digit hex or transparent for the background colour and renders both; toolbar, icon and arrow colours are accepted but never rendered (only dashboard-made objects, which store a # form the API refuses, show them), which is why the editor does not offer them.
• Embed objects. Advanced Styling stores one embed object per entry on your Yumpu account. The dashboard mints a new object on every save; the add-on updates its one object per entry in place and records what it created so the sweep can distinguish its objects from yours.

Support & logging

Enable ExpressionEngine's Developer Log (Developer → Logs), reproduce the issue, and send the relevant entries to [email protected]. Every failed Yumpu call is logged with the request it made, the keys it sent, what Yumpu rejected, and the assumption about Yumpu's API that the code encodes, so a change on Yumpu's side is diagnosable from the log alone. Values and the API token are never logged.

Security notes

• The Yumpu API token is stored encrypted, displayed masked, and never sent to the browser; every Yumpu request is made server-side.
• The field's endpoints are front-end actions gated by the member's entry-create or entry-edit permissions, with CSRF tokens on every mutating request; a refused call answers with the matching HTTP status and a JSON message. Player-template management (create, update, delete, import) needs access to this add-on's control panel pages (the Can access add-ons permission with Yumpu Embed assigned to the role) at both the field and MCP layers, the same test ExpressionEngine applies to the pages themselves. Document delete is limited to Super Admins at both layers, and the MCP delete tool additionally requires the mcp:admin scope.
• A stored value is validated on save and on output: only the keys the field itself writes are kept, every stored URL must be an https:// URL, and an embed object id is honoured only when the add-on created it.
• Player settings rendered into a page are JSON-encoded with script-closing sequences escaped, and the iframe fallback only embeds www.yumpu.com embed-view URLs.
• Uploads through an EE directory follow EE's own upload-directory permissions and file validation; only PDFs are accepted.

License

Yumpu Embed is commercial software. One license covers a single production site plus one related staging or development site; each additional production site needs its own license. The full terms are on the license page.