Advanced Usage

Manual initialization, event handling, and troubleshooting.

---

Manual Initialization

By default, the widget auto-initializes when the script loads. For more control, initialize manually via JavaScript:

<script src="https://api.earpocket.com/widget.js" async></script>
<script>
  window.addEventListener('load', function() {
    if (window.EarpocketWidget) {
      window.EarpocketWidget.createWidget({
        siteId: 'your-site-id',
        position: 'bottom-right',
        theme: 'auto',
        apiUrl: 'https://api.earpocket.com',
        playerUrl: 'https://play.earpocket.com',
        feedsUrl: 'https://feeds.earpocket.com'
      });
    }
  });
</script>

---

Single Page Applications

For SPAs (React, Vue, Angular, etc.) where content changes without page reloads, the widget automatically detects URL changes.

No extra config needed

The widget handles client-side navigation automatically.

---

Content Security Policy

If your site uses CSP headers, add these directives:

script-src 'self' https://api.earpocket.com;
connect-src 'self' https://api.earpocket.com https://feeds.earpocket.com;
frame-src 'self' https://play.earpocket.com;

---

Troubleshooting

Widget Not Appearing

1. Check the console — Open browser DevTools (F12) and look for errors
2. Verify site ID — Ensure data-site matches your registered site ID
3. Check script loading — Verify the script URL is accessible
4. CSP issues — Check if Content Security Policy is blocking the widget

Common Errors

"No script tag with data-site found"

The widget couldn't find its script tag. Ensure you have the data-site attribute:

<!-- ❌ Wrong -->
<script src="https://api.earpocket.com/widget.js" async></script>

<!-- ✅ Correct -->
<script
  src="https://api.earpocket.com/widget.js"
  data-site="your-site-id"
  async
></script>

"Missing data-site attribute"

The script tag was found but data-site is empty:

<!-- ❌ Wrong -->
<script src="..." data-site="" async></script>

<!-- ✅ Correct -->
<script src="..." data-site="your-site-id" async></script>

Ad Blockers

Some ad blockers may block the widget. Users can whitelist your domain or api.earpocket.com to resolve this.

---

Performance

Aspect	Details
Loading	Script loads with async — doesn't block page render
Audio generation	On-demand — no preloading
Bundle size	~15KB gzipped

---

Browser Support

Browser	Minimum Version
Chrome	80+
Firefox	75+
Safari	13+
Edge	80+

Not Supported

Internet Explorer is not supported.

---

Getting Help

If you're still having issues:

1. Check the browser console for error messages
2. Verify your site ID is correct
3. Contact support at support@earpocket.com