Web SDK Integration

The NotiGrid Web SDK enables you to send push notifications to users' browsers.

Installation

Via CDN (Recommended)

Add the SDK script to your HTML:

<script src="https://cdn.notigrid.com/sdk/v1/notigrid-sdk.iife.js"></script>

Via NPM

npm install @notigrid/sdk

Quick Start

Initialize the SDK

<script>
  // Initialize NotiGrid
  const notigrid = window.Notigrid.init({
    projectId: 'YOUR_PROJECT_ID',
    apiKey: 'YOUR_PUBLIC_API_KEY'
  });

  // Request permission and subscribe
  notigrid.subscribe().then(subscription => {
    console.log('Subscribed successfully!', subscription);
  }).catch(error => {
    console.error('Subscription failed:', error);
  });
</script>

With NPM

import Notigrid from '@notigrid/sdk';

const notigrid = Notigrid.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_PUBLIC_API_KEY'
});

// Subscribe to push notifications
await notigrid.subscribe();

Configuration Options

const notigrid = Notigrid.init({
  // Required
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_PUBLIC_API_KEY',

  // Optional
  serviceWorkerPath: '/notigrid-sw.js', // Custom service worker path
  debug: true, // Enable console logging
  autoSubscribe: false, // Auto-subscribe on init
});

Service Worker Setup

The SDK requires a service worker to handle push notifications. Create a file notigrid-sw.js in your public directory:

Option 1: Use Our Hosted Service Worker

<!-- In your HTML -->
<script>
  navigator.serviceWorker.register('https://cdn.notigrid.com/sdk/v1/notigrid-sw.js');
</script>

Option 2: Self-hosted Service Worker

Download and host the service worker yourself:

curl -o public/notigrid-sw.js https://cdn.notigrid.com/sdk/v1/notigrid-sw.js

navigator.serviceWorker.register('/notigrid-sw.js');

SDK Methods

Request permission and subscribe the user:

notigrid.subscribe()
  .then(subscription => {
    console.log('Device token:', subscription.deviceToken);
  })
  .catch(error => {
    if (error.code === 'PERMISSION_DENIED') {
      console.log('User denied permission');
    }
  });

Unsubscribe

Unsubscribe the current user:

await notigrid.unsubscribe();

Check Subscription Status

const isSubscribed = await notigrid.isSubscribed();
console.log('Is subscribed:', isSubscribed);

Get Device Token

Get the current device's push token:

const token = await notigrid.getDeviceToken();
console.log('Device token:', token);

Send Custom User Data

Associate custom data with the subscription:

await notigrid.subscribe({
  userId: 'user_123',
  email: 'user@example.com',
  properties: {
    plan: 'pro',
    signupDate: '2025-01-15'
  }
});

Events

Listen to SDK events:

// Permission granted
notigrid.on('permission:granted', () => {
  console.log('Push permission granted');
});

// Permission denied
notigrid.on('permission:denied', () => {
  console.log('Push permission denied');
});

// Subscribed successfully
notigrid.on('subscribed', (subscription) => {
  console.log('Subscribed:', subscription);
});

// Unsubscribed
notigrid.on('unsubscribed', () => {
  console.log('Unsubscribed from push notifications');
});

// Notification received (when app is open)
notigrid.on('notification:received', (notification) => {
  console.log('Notification received:', notification);
});

// Notification clicked
notigrid.on('notification:clicked', (notification) => {
  console.log('Notification clicked:', notification);
  // Navigate to specific page, etc.
});

React Integration

With Hooks

import { useEffect, useState } from 'react';
import Notigrid from '@notigrid/sdk';

function App() {
  const [notigrid, setNotigrid] = useState(null);
  const [isSubscribed, setIsSubscribed] = useState(false);

  useEffect(() => {
    const ng = Notigrid.init({
      projectId: 'YOUR_PROJECT_ID',
      apiKey: 'YOUR_PUBLIC_API_KEY'
    });

    setNotigrid(ng);

    // Check subscription status
    ng.isSubscribed().then(setIsSubscribed);
  }, []);

  const handleSubscribe = async () => {
    try {
      await notigrid.subscribe();
      setIsSubscribed(true);
    } catch (error) {
      console.error('Failed to subscribe:', error);
    }
  };

  const handleUnsubscribe = async () => {
    try {
      await notigrid.unsubscribe();
      setIsSubscribed(false);
    } catch (error) {
      console.error('Failed to unsubscribe:', error);
    }
  };

  return (
    <div>
      <h1>Push Notifications</h1>
      {isSubscribed ? (
        <button onClick={handleUnsubscribe}>Unsubscribe</button>
      ) : (
        <button onClick={handleSubscribe}>Subscribe</button>
      )}
    </div>
  );
}

Next.js Integration

// app/providers.tsx
'use client';

import { useEffect } from 'react';
import Notigrid from '@notigrid/sdk';

export function NotiGridProvider({ children }: { children: React.ReactNode }) {
  useEffect(() => {
    if (typeof window !== 'undefined') {
      const notigrid = Notigrid.init({
        projectId: process.env.NEXT_PUBLIC_NOTIGRID_PROJECT_ID!,
        apiKey: process.env.NEXT_PUBLIC_NOTIGRID_API_KEY!,
      });

      // Auto-subscribe (optional)
      notigrid.subscribe().catch(console.error);
    }
  }, []);

  return <>{children}</>;
}

Testing

Test Push Notifications

Use the dashboard to send test notifications:

Go to Dashboard → Test Notifications
Select a device or enter device token
Compose and send test notification

Debug Mode

Enable debug mode to see detailed logs:

const notigrid = Notigrid.init({
  projectId: 'YOUR_PROJECT_ID',
  apiKey: 'YOUR_PUBLIC_API_KEY',
  debug: true // Enable debug logging
});

Browser Compatibility

The SDK supports all modern browsers with Push API support:

Browser	Version
Chrome	50+
Firefox	44+
Safari	16+
Edge	79+
Opera	37+

Troubleshooting

Permission Denied

If users deny permission, you'll need to guide them to manually enable it in browser settings.

Service Worker Not Registering

Ensure:

Service worker file is served over HTTPS (or localhost)
File path is correct
No conflicting service workers

Notifications Not Appearing

Check:

Browser notification settings
User is subscribed
Service worker is active
VAPID keys are configured correctly

Need help? Join our Discord community or email support@notigrid.com

SDK Integration

On this page