@pushary/sdk

Web Push Notification SDK for Pushary - Add push notifications to your website in minutes.

Features

• Simple API for web push notifications
• TypeScript support with full type definitions
• Works with any framework (React, Vue, Angular, vanilla JS)
• Service worker included
• Click tracking and analytics
• Subscriber segmentation with tags
• iOS Safari support (PWA)

Installation

npm install @pushary/sdk
# or
yarn add @pushary/sdk
# or
pnpm add @pushary/sdk

Script Tag

<script src="https://pushary.com/sdk/pushary.js"></script>

Quick Start

1. Get your Site Key

Sign up at pushary.com and create a site to get your site key.

2. Add the Service Worker

Copy the service worker file to your public directory:

cp node_modules/@pushary/sdk/dist/browser/pushary-sw.global.js public/pushary-sw.js

3. Initialize the SDK

import { createPushary } from '@pushary/sdk'

const pushary = createPushary({
  siteKey: 'pk_your_site_key',
  autoPrompt: true,
  debug: true,
  onSubscribe: (subscription) => {
    console.log('Subscribed!', subscription)
  },
})

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteKey | string | required | Your Pushary site key (pk_xxx) | | apiUrl | string | 'https://pushary.com' | API endpoint URL | | autoPrompt | boolean | true | Auto-prompt for permission | | promptDelay | number | 3000 | Delay before auto-prompt (ms) | | debug | boolean | false | Enable debug logging | | onSubscribe | function | - | Called on successful subscription | | onPermissionDenied | function | - | Called when permission denied | | onNotSupported | function | - | Called when push not supported | | onNotificationClick | function | - | Called on notification click |

API

createPushary(config): PusharyInstance

Creates a Pushary instance with the given configuration.

const pushary = createPushary({
  siteKey: 'pk_your_site_key',
  debug: true,
})

Methods

promptForPermission(): Promise<PushSubscription | null>

Request notification permission from the user.

const subscription = await pushary.promptForPermission()

subscribe(): Promise<PushSubscription | null>

Subscribe to push notifications (permission must already be granted).

const subscription = await pushary.subscribe()

unsubscribe(): Promise<void>

Unsubscribe from push notifications.

await pushary.unsubscribe()

setExternalId(externalId: string): Promise<void>

Associate an external ID with the subscriber for targeting.

await pushary.setExternalId('user-123')

setTags(tags: Record<string, string>): Promise<void>

Set tags for subscriber segmentation.

await pushary.setTags({
  plan: 'premium',
  interests: 'sports,news',
})

isSupported(): boolean

Check if push notifications are supported.

if (pushary.isSupported()) {
  // Push is available
}

Authentication

Client SDK (Browser)

Uses Site Key (public prefix):

• Format: pk_xxxxxxxx
• Safe to expose in client-side code
• Protected by domain validation

const pushary = createPushary({
  siteKey: 'pk_abc123xyz',
})

Server API (Backend)

Uses Full API Key (prefix + secret):

• Format: pk_prefix.sk_secret
• NEVER expose in client-side code
• Use @pushary/server package for server-side operations

Framework Examples

React

import { useEffect } from 'react'
import { createPushary } from '@pushary/sdk'

function App() {
  useEffect(() => {
    const pushary = createPushary({
      siteKey: 'pk_your_site_key',
      autoPrompt: false,
    })

    window.pushary = pushary
  }, [])

  const handleSubscribe = async () => {
    await window.pushary?.promptForPermission()
  }

  return <button onClick={handleSubscribe}>Enable Notifications</button>
}

Next.js

'use client'

import { useEffect, useState } from 'react'
import { createPushary, type PusharyInstance } from '@pushary/sdk'

export default function PushNotifications() {
  const [pushary, setPushary] = useState<PusharyInstance | null>(null)

  useEffect(() => {
    const instance = createPushary({
      siteKey: process.env.NEXT_PUBLIC_PUSHARY_SITE_KEY!,
      autoPrompt: false,
    })
    setPushary(instance)
  }, [])

  return (
    <button onClick={() => pushary?.promptForPermission()}>
      Enable Notifications
    </button>
  )
}

Vue 3

<script setup>
import { onMounted, ref } from 'vue'
import { createPushary } from '@pushary/sdk'

const pushary = ref(null)

onMounted(() => {
  pushary.value = createPushary({
    siteKey: 'pk_your_site_key',
    autoPrompt: false,
  })
})
</script>

<template>
  <button @click="pushary?.promptForPermission()">
    Enable Notifications
  </button>
</template>

TypeScript

Full TypeScript definitions are included:

import { 
  createPushary, 
  type PusharyConfig, 
  type PusharyInstance,
  type NotificationData 
} from '@pushary/sdk'

const config: PusharyConfig = {
  siteKey: 'pk_your_site_key',
  onNotificationClick: (url: string, data: NotificationData) => {
    console.log('Clicked:', url, data)
    return true
  },
}

const pushary: PusharyInstance = createPushary(config)

Service Worker Exports

For custom service worker implementations:

import {
  handlePush,
  handleNotificationClick,
  handleNotificationClose,
  handleMessage,
} from '@pushary/sdk/service-worker'

Browser Support

• Chrome 50+
• Firefox 44+
• Safari 16+ (macOS & iOS)
• Edge 17+
• Opera 37+

Plan Limits

| Feature | Free | Starter | Growth | Enterprise | |---------|------|---------|--------|------------| | Subscribers | 100 | 5,000 | 25,000 | Unlimited | | Notifications/month | 500 | 25,000 | 100,000 | Unlimited | | Sites | 1 | 3 | 10 | Unlimited | | Data retention | 7 days | 30 days | 90 days | Custom | | A/B Testing | - | ✓ | ✓ | ✓ | | API Access | - | ✓ | ✓ | ✓ | | Priority Support | - | - | ✓ | ✓ |

License

MIT. See LICENSE.

Links

• Documentation
• Dashboard
• Support