Add audio to any website

Overview

The everlitAutoAudio.js script enables automatic audio conversion and playback for your web content. Simply add two HTML elements to your page and the script handles everything else.

How It Works

Basic Implementation

Add these two elements to your article pages:

Copy<!-- 1. The widget container -->
<div
  id="everlit-auto-audio-widget"
  data-publication-id="YOUR-PUBLICATION-ID"
  style="height: 136px; width: 100%;"
  hidden
><a href="https://everlit.audio/" rel="nofollow">Listen to this article &mdash; audio by Everlit</a></div>

<!-- 2. The script -->
<script
  defer
  src="https://cdn.everlit.audio/libs/everlitAutoAudio.js"
  type="text/javascript"
></script>

Where to Place It

Place the widget container where you want the audio player to appear—typically at the top of the article, below the headline, or in a sidebar. The script tag can go anywhere (we recommend before </body>).

Required Attributes

CMS Support

The Everlit script works with any CMS or custom website. It automatically detects article content from popular platforms and falls back to standard HTML patterns for others.

Customizable CMS Support

The Everlit Auto Audio JS can be customized to support any CMS or custom website. Here are a few platforms that are automatically detected with optimized content extraction:

Other CMS Platforms

For all platforms (Navigator, Drupal, Ghost, custom sites, etc.), the script uses standard and customizable content detection patterns:

• Looks for class's containing likely article data
• Extracts text from <p>, <div>, and various other tags within the article
• Identifies the article by the canonical URL and leverages any Open Graph or other meta tags to enrich the article

Configuration Options

The widget reads the attributes below. The article URL, title, and content are detected automatically from the page (see CMS Support).

Paywall Access Signal

If your publication has the audio paywall enabled, set data-everlit-access to the current visitor's access status (for example, from the subscription check you run when rendering the page). When the visitor is blocked, the widget shows a blurred player with a subscribe call-to-action instead of generating or playing audio.

These values are treated as blocked (case-insensitive): blocked, false, 0, no, gated, locked. Any other value—or omitting the attribute—is treated as allowed. The attribute has no effect unless the paywall is enabled for your publication.

Copy<!-- Blocked visitor: widget shows the blurred paywall placeholder -->
<div
  id="everlit-auto-audio-widget"
  data-publication-id="YOUR-PUBLICATION-ID"
  data-everlit-access="blocked"
  style="height: 136px; width: 100%;"
  hidden
></div>

Styling

The widget container should have a minimum height of 136px. The player will appear inside this container when audio is ready. You can style the container to match your site design.

Copy<style>
  #everlit-auto-audio-widget {
    height: 136px;
    width: 100%;
    margin: 20px 0;
    border-radius: 8px;
    overflow: hidden;
  }

  #everlit-audio-embed-container iframe {
    width: 100%;
    border: none;
  }
</style>

JavaScript Events

The widget dispatches custom events on document (they bubble, so window listeners work too). Listen for these to respond to conversion and player state:

Example: Listening for Events

Copy<script>
  document.addEventListener('everlit:ready', function (e) {
    console.log('Audio player is ready', e.detail);
  });

  document.addEventListener('everlit:processing', function (e) {
    console.log('Conversion started for', e.detail.url);
  });

  document.addEventListener('everlit:error', function (e) {
    console.error('Everlit error:', e.detail.reason);
  });
</script>

Player Events

Once enabled, the Everlit player posts realtime playback events from its iframe to your page via window.postMessage. Use them for on-page activation—fire your own analytics events, enrich them with your visitor's identity or subscription data, or trigger a prompt when a listener finishes an episode. They work wherever the player is embedded: the auto audio widget, playlist embeds, or a direct iframe.

Message Format

Copy{
  "type": "everlit:event",
  "event": "play",          // "play" | "pause" | "complete"
  "articleId": "artl_...",  // the article being played
  "eut": "..."              // the end-user tag for this listener
}

Events describe content playback only—ad breaks never emit events. In playlist embeds, articleId always reflects the track currently playing.

Example: Listening for Player Events

Copy<script>
  window.addEventListener('message', function (e) {
    if (e.data?.type !== 'everlit:event') return;

    // Enrich with your own visitor data and forward to your analytics
    yourAnalytics.track('audio_' + e.data.event, {
      articleId: e.data.articleId,
      everlitListenerId: e.data.eut,
      userId: yourCurrentUser.id
    });
  });
</script>

Correlating with Everlit Analytics

The eut (end-user tag) is the same pseudonymous listener identifier that appears as client_user_tag in your Everlit metric exports and BigQuery data. Store it alongside your own user ID to join realtime on-page events with the full listening history in your exports. If you already pass your own identifier into the player via the eut parameter, events echo that value back.

Troubleshooting

Common Issues

Debug Mode

Check the browser console for debug information. The script logs key events during initialization.

Next Steps