Skip to main content

Reader Embedding

Overview​

The Publica.la reader supports an embedded mode that allows content to be seamlessly integrated within partner applications, websites, and learning platforms through iframes. This feature enables publishers and organizations to provide reading experiences directly within their existing digital ecosystems, increasing engagement and reducing friction for end users.

Business Value​

Embedded readers help our customers:

  • Increase content accessibility by meeting readers where they already are
  • Improve user retention by eliminating the need to navigate away from familiar platforms
  • Enhance partner integrations with seamless content delivery
  • Support educational workflows by embedding materials directly in learning management systems
  • Boost engagement metrics through reduced barriers to content access

How to Enable Embedded Mode​

To enable embedded mode, add the embedded query parameter to the reader URL:

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

The embedded mode feature is available to all stores by default. No feature flag or special configuration is required to enable this functionality.

Query Parameter Behavior​

The embedded parameter accepts boolean values:

  • ?embedded=true or ?embedded=1 → Enables embedded mode
  • ?embedded=false or ?embedded=0 → Disables embedded mode (default behavior)
  • ?embedded (without value) → Treated as false (embedded mode OFF)
  • No parameter → Normal reader mode

What Changes in Embedded Mode​

When embedded mode is active, the reader modifies its behavior and UI to better fit within an iframe context:

  • Navigation elements that would navigate away from the reader are hidden
  • Exit button behavior is modified or removed
  • UI adjustments are made to optimize the reading experience within the embedded container
  • Certain features that don't work well in embedded contexts may be disabled

Example Usage​

Basic Iframe Implementation​

<!-- Embedding the reader in an iframe -->
<iframe 
  src="https://{store_final_domain}/reader/my-book?embedded=true"
  width="100%"
  height="600px"
  frameborder="0">
</iframe>

Responsive Iframe​

<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>
  </iframe>
</div>

Common Use Cases​

  1. Partner Integrations: When partners need to display Publica.la content within their own platforms
  2. Custom Dashboards: Embedding the reader in administrative or educational dashboards
  3. Marketing Sites: Previewing content on landing pages or product showcases
  4. Learning Management Systems: Integrating reading materials directly into educational platforms
  5. Library Systems: Displaying digital content within library catalog interfaces
  6. Corporate Training Platforms: Embedding training materials and documentation

Combining with Other Parameters​

The embedded mode can be combined with other reader parameters:

Embedded Preview Mode​

?embedded=true&preview=true

Shows the reader in embedded mode with preview restrictions (limited pages).

Embedded with Specific Location​

?embedded=true&location=5

Opens the reader at a specific page while in embedded mode.

Embedded with Custom Exit URL​

?embedded=true&reader_exit_url=https://{your_website}/return

Defines where users should be redirected when exiting the embedded reader (if exit functionality is available).

Embedded with Authentication Token​

?embedded=true&token=[auth_token]

Passes authentication for secure content access in embedded contexts.

Security Considerations​

When implementing embedded readers:

  1. Content Security Policy (CSP): Ensure your CSP headers allow iframe embedding from authorized domains
  2. X-Frame-Options: Configure appropriately to prevent clickjacking while allowing legitimate embedding
  3. Authentication: Use secure token-based authentication for protected content
  4. CORS Configuration: Set up proper CORS headers for cross-origin resource sharing

Best Practices​

  1. Responsive Design: Always implement responsive iframe containers for mobile compatibility
  2. Loading States: Show loading indicators while the reader initializes
  3. Error Handling: Implement fallback content if the iframe fails to load
  4. Performance: Consider lazy loading for pages with multiple embedded readers
  5. Accessibility: Ensure keyboard navigation and screen reader compatibility are maintained

Troubleshooting​

Common Issues​

Reader not displaying in embedded mode:

  • Verify the embedded=true parameter is correctly formatted
  • Check browser console for JavaScript errors
  • Ensure the parent page allows iframe embedding

Exit button still visible:

  • Confirm you're using embedded=true (not just embedded)
  • Check if custom CSS or JavaScript is overriding the embedded mode styles

Authentication issues:

  • Verify token-based authentication is properly configured
  • Check CORS settings for cross-domain embedding
  • Ensure cookies are being handled correctly in third-party contexts

Frequently Asked Questions​

Can embedded readers track reading analytics?​

Yes, embedded readers maintain full analytics capabilities, tracking reading sessions, page views, and engagement metrics just like the standard reader.

Are there limitations on which content can be embedded?​

Content availability in embedded mode depends on your licensing agreements and content settings. Free content and preview-enabled content work seamlessly, while premium content requires proper authentication.

How does embedded mode affect mobile users?​

The embedded reader is fully responsive and adapts to mobile devices. We recommend using responsive iframe containers to ensure optimal viewing on all screen sizes.

Can multiple readers be embedded on the same page?​

Yes, you can embed multiple readers on a single page. Consider performance implications and use lazy loading for optimal user experience.

X

Graph View