SDK Integration Guide

How to embed the audio player on your website.

Basic Integration

The SDK is served from a dedicated server. You can find your personalized integration code on the "Player Settings" page in the dashboard.

Integration Code

<!-- Player container -->
<div class="pub-voice-player-container"></div>

<!-- Loader script -->
<script
  src="https://sdk.pub-voice.com/sdk-assets/[CONTENT-SOURCE-ID]/loader.js"
  data-pub-voice-config='{"playerSelector": ".pub-voice-player-container"}'
></script>

ℹ️

[CONTENT-SOURCE-ID]should be replaced with the actual value from the "Player Settings" page in the dashboard. Changes are reflected automatically within approximately one hour.

Player Placement

Place the container element where you want the player to appear. If no container is specified, the SDK automatically inserts the player above the article element.

CMS-Specific Examples

WordPress

Edit your theme's template file (typically single.php). We recommend placing the player just below the article title.

<!-- single.php example -->
<article>
  <h1><?php the_title(); ?></h1>
  
  <!-- Player container (below title) -->
  <div class="pub-voice-player-container"></div>
  
  <div class="content">
    <?php the_content(); ?>
  </div>
</article>

<!-- Place near footer -->
<script
  src="https://sdk.pub-voice.com/sdk-assets/[CONTENT-SOURCE-ID]/loader.js"
  data-pub-voice-config='{"playerSelector": ".pub-voice-player-container"}'
></script>

Some themes make the footer harder to find. In that case, place the loader in any section that loads on every page (e.g. footer.php or a site-wide custom HTML block).

Next.js (App Router)

In Next.js, we recommend loading the loader once in the Root Layout using next/script. The SDK handles SPA page transitions automatically — no manual cleanup is needed.

Step 1: Load the loader in layout.tsx

// src/app/layout.tsx
import Script from "next/script"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          id="pub-voice-loader"
          src="https://sdk.pub-voice.com/sdk-assets/[CONTENT-SOURCE-ID]/loader.js"
          strategy="afterInteractive"
          data-pub-voice-config={JSON.stringify({
            playerSelector: ".pub-voice-player-container",
          })}
        />
      </body>
    </html>
  )
}

Step 2: Create a PubVoicePlayer component

// src/components/PubVoicePlayer.tsx
"use client"

export default function PubVoicePlayer() {
  // Just place the container — the SDK handles init/destroy automatically
  return <div className="pub-voice-player-container" />
}

Tips

Use strategy="afterInteractive" to avoid blocking page interactivity
The id attribute prevents Next.js from loading the script twice
The SDK uses MutationObserver to watch for container additions/removals and manages the lifecycle automatically
Place the PubVoicePlayer component in your article page template

Troubleshooting

Player not showing

Article not detected — check that the article appears in the dashboard article list
Verify the URL is correct

Audio not generating

Article not registered — check that the RSS feed is configured correctly
Verify the article appears in the dashboard article list

Player not working correctly in SPA

The SDK uses MutationObserver to detect container additions/removals and manages the lifecycle automatically
Make sure the container element (.pub-voice-player-container) is placed correctly
When the container is removed during page transitions, the SDK automatically destroys the player

Browser Support

Chrome (latest)
Firefox (latest)
Safari (latest)
Edge (latest)

Limitations

Article body is limited to 10,000 characters
Only MP3 format is supported for audio files
Only one article can be converted to audio at a time

Ready to try it for free?

PUBVOICE is available as a free beta. Add a "play button" to your articles and start building a new relationship with your readers.

Get Started Free