Skip to main content
  • Send to AI

Embed the Reader in Your Application

Add ?embedded=true to any reader URL to render the Publica.la reader inside an iframe in your application. Embedded mode hides navigation controls that would break the parent page context and adapts the UI to fit within a container.

Use this guide when you need to display Publica.la content (PDF, EPUB, or Audiobook) directly inside your platform without redirecting your users to a standalone reader URL.

Prerequisites​

  • You have a store on Publica.la and know your {store_final_domain}.
  • The product you want to embed has a slug (visible in the store admin).
  • For protected content: you have configured Auth Token authentication.
  • Your server can set HTTP response headers (for CSP and X-Frame-Options configuration).

Enable Embedded Mode​

Append ?embedded=true to any reader URL:

https://{store_final_domain}/reader/{product-slug}?embedded=true

No feature flag or special configuration is required. Embedded mode is available on all stores by default.

Parameter Values​

ValueBehavior
?embedded=true or ?embedded=1Embedded mode on
?embedded=false or ?embedded=0Embedded mode off (default behavior)
?embedded (no value)Treated as false
Parameter absentNormal reader mode

Iframe Implementation​

Basic Embed​

<iframe
  src="https://{store_final_domain}/reader/my-book?embedded=true"
  width="100%"
  height="600px"
  frameborder="0"
  title="Publica.la Reader"
></iframe>

Responsive Embed​

Use the aspect-ratio wrapper pattern to keep the reader proportional on any screen size:

<div
  style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"
>
  <iframe
    src="https://{store_final_domain}/reader/my-book?embedded=true"
    style="position: absolute; top: 0; left: 0; width: 100%; height: 100%;"
    frameborder="0"
    allowfullscreen
    title="Publica.la Reader"
  ></iframe>
</div>

The 56.25% padding produces a 16:9 ratio. Adjust to match your layout.

Combining Query Parameters​

Combine embedded=true with other reader parameters in a single URL:

CombinationEffect
?embedded=true&preview=trueEmbedded mode with preview restrictions (limited pages)
?embedded=true&location=5Opens at page 5 in embedded mode
?embedded=true&reader_exit_url=https://yoursite.com/returnRedirects users to your URL when they exit the reader
?embedded=true&token={auth_token}Passes an auth token for protected content access

Authentication in Embedded Contexts​

For content that requires a logged-in user, pass the auth token directly in the URL:

https://{store_final_domain}/reader/my-book?embedded=true&token={auth_token}

Generate {auth_token} using the Auth Token integration. The token authenticates the user and grants access to the product in a single request, which avoids cookie-based flows that often fail inside iframes due to browser third-party cookie restrictions.

warning

Do not expose auth tokens in client-side JavaScript. Generate them server-side and inject them directly into the iframe src attribute on page render.

Security Configuration​

Content Security Policy (CSP)​

Your page must allow the Publica.la domain to load inside a frame. Add your store domain to the frame-src directive:

Content-Security-Policy: frame-src https://{store_final_domain};

If you serve multiple stores or use a custom domain, include each domain.

X-Frame-Options​

X-Frame-Options controls whether your own page can be framed. Set it on the parent page to prevent clickjacking while still allowing your iframe to contain the reader:

X-Frame-Options: SAMEORIGIN

Do not set X-Frame-Options: DENY on the parent page; it blocks all framing, including your own iframe.

CORS​

The reader loads assets from {store_final_domain}. Your server does not need to configure CORS for the iframe to load, but any JavaScript postMessage communication between the iframe and parent requires the origin to match what you specify.

Native Share in Embedded Mode​

The Web Share API (navigator.share) is restricted by some browsers inside cross-origin iframes. If your readers tap the Share button inside the embedded reader, the share sheet may not appear.

To allow native share, add allow="web-share" to the iframe:

<iframe
  src="https://{store_final_domain}/reader/my-book?embedded=true"
  allow="web-share"
  frameborder="0"
  title="Publica.la Reader"
></iframe>

Without this attribute, the share action silently fails on browsers that enforce the permissions policy.

Troubleshooting​

Reader does not display inside the iframe

  • Confirm the URL includes ?embedded=true with the correct boolean value.
  • Open your browser console and look for CSP or mixed-content errors.
  • Verify that the parent page does not set X-Frame-Options: DENY.

Exit button is still visible

  • Confirm the parameter value is embedded=true, not just embedded (without a value).
  • Check that no parent-page CSS or JavaScript overrides the reader's embedded styles.

Authentication fails inside the iframe

  • Use token-based auth (?token={auth_token}) instead of cookie-based flows.
  • Verify your CORS headers allow the origin of the parent page.
  • Check that the token is not expired before injecting it into the iframe src.

Share button does nothing

  • Add allow="web-share" to the iframe element (see Native Share above).

Frequently Asked Questions​

Does embedded mode affect reading analytics?

No. Embedded readers record reading sessions, page views, and engagement metrics the same as the standalone reader.

Can I embed multiple readers on the same page?

Yes. Each iframe loads independently. Use lazy loading (loading="lazy" on the iframe element) when placing more than two readers on a single page to avoid blocking the initial page render.

Can I embed protected (paid) content?

Yes, as long as you pass a valid auth token in the URL. Free content and preview-enabled content work without a token. See Authentication in Embedded Contexts.

Does embedded mode work on mobile?

Yes. The reader adapts to the iframe container width. Use the responsive wrapper pattern to ensure correct sizing on small screens.

X

Graph View