Self-Hosted Web Push Integration Guide

Welcome to HyperPush X! This step-by-step guide helps you quickly integrate instant web push notifications into your website or web application. In just a few minutes, you will be ready to send real-time push alerts to re-engage your visitors and boost sales.

📐 How Web Push Works on Your Website

🌍 Supported Browsers & Devices

HyperPush X works seamlessly across all major modern desktop and mobile web browsers with zero browser extensions required:

[!NOTE] Web Push requires an HTTPS secure connection on your website (e.g. https://yourdomain.com).

⚡ Step 1: Add Your Website to HyperPush X

First, register your website in your HyperPush X console:

1. Go to Websites in your dashboard (/websites).
2. Click + Add Website.
3. Enter your Site Name (e.g. Acme Store) and your Site Domain (e.g. https://acme.com).
4. Click Register Website.

Once added, your website receives a unique Site Key (site_key) that connects your website to your HyperPush X account.

📥 Step 2: Download Your Integration Files

Next, download your pre-configured SDK files from your dashboard:

1. In your Websites list, click the three-dots menu (•••) next to your domain.
2. Click Download SDK.

3. Unzip the downloaded file. You will get two files:
   • sdk.js — Client JavaScript library for your pages.
   • sw.js — Service Worker file that handles background notifications.

[!IMPORTANT] Important Placement Rule:
Upload sw.js to the root folder of your website (e.g., https://yourdomain.com/sw.js). This allows HyperPush X to show notifications across every page on your site.

💻 Step 3: Add Code Snippet to Your Website

Standard Web Page Integration (HTML)

Paste this small code snippet into the <head> or before </body> on your site:

<!-- HyperPush X Web Push -->
<script>
  window.HyperPush = window.HyperPush || [];
  window.HyperPush.push(['init', {
    siteKey: 'YOUR_SITE_KEY_HERE',
    serviceWorkerPath: '/sw.js',
    autoPrompt: true,
    bellWidget: true
  }]);
</script>
<script src="/sdk.js" async></script>

React / Next.js Integration

If you use React or Next.js, add the setup inside a component lifecycle hook:

import { useEffect } from 'react';

export default function WebPushSetup() {
  useEffect(() => {
    window.HyperPush = window.HyperPush || [];
    window.HyperPush.push(['init', {
      siteKey: 'YOUR_SITE_KEY_HERE',
      serviceWorkerPath: '/sw.js',
      autoPrompt: true
    }]);

    const script = document.createElement('script');
    script.src = '/sdk.js';
    script.async = true;
    document.head.appendChild(script);
  }, []);

  return null;
}

Vue 3 / Nuxt Integration

If you use Vue 3 or Nuxt, add the setup inside onMounted:

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  window.HyperPush = window.HyperPush || [];
  window.HyperPush.push(['init', {
    siteKey: 'YOUR_SITE_KEY_HERE',
    serviceWorkerPath: '/sw.js',
    autoPrompt: true
  }]);

  const script = document.createElement('script');
  script.src = '/sdk.js';
  script.async = true;
  document.head.appendChild(script);
});
</script>

🔔 Step 4: Customize Your Opt-in Prompts

HyperPush X includes beautiful, high-converting subscription prompts and a floating notification bell widget:

You can easily customize prompt colors, headings, button text, and bell icons right inside your HyperPush X console:

[!TIP] Pro Tip: Triggering subscription prompts after a user interacts with your page leads to much higher subscription rates compared to prompting immediately on landing.

🏷️ Step 5: (Optional) Segment & Tag Your Subscribers

Personalize notifications by attaching custom tags (like user interest, plan, or location) to your subscribers:

Tag Subscriber Interests

window.HyperPush.push(['tag', {
  category: 'sports',
  user_type: 'premium'
}]);

Connect Logged-in User IDs

window.HyperPush.push(['setExternalUserId', 'user_12345']);

🧪 Step 6: Test & Verify Your Setup

1. Open your website in your browser.
2. Click Allow on your subscription prompt or notification bell.
3. Check Subscribers in your HyperPush X dashboard (/subscribers).
4. You will see your browser listed as an Active subscriber!

🚨 Need Help? Quick Troubleshooting

[!TIP] Why is the prompt not appearing?
Check if your site is loaded over https://. Also ensure you uploaded sw.js to your root directory.

[!NOTE] What if a user accidentally blocked notifications?
Browsers do not allow websites to automatically re-prompt blocked users. The visitor can re-enable notifications anytime by clicking the lock icon next to the URL in their browser address bar.