@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: false,
  banner: false,
  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 | | banner | boolean or config | true | Show the opt-in banner; set false for your own button | | 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,
      banner: 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,
      banner: 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 and Plans

Use HTTPS and feature detection (isSupported()) in current browsers. On iOS/iPadOS, Web Push requires 16.4 or later and a web app added to the Home Screen; request permission from a user interaction. See WebKit’s requirements.

See current plans and limits.

Initialization and worker updates

await pushary.ready observes initialization errors. Identity and tag updates wait for initialization and reject if there is no subscription or the server rejects the update. Subscribe first, then set identity/tags; handle rejected promises in your UI.

Set both autoPrompt: false and banner: false when your app supplies its own subscribe button. Neither setting removes the browser's permission requirement.

After an SDK upgrade, repeat the service-worker copy command above and deploy that file at the same URL. Updating the npm dependency alone does not update a previously copied worker. This release includes settlement handling already used by the hosted worker.

License

MIT. See LICENSE.

Links

• Documentation
• Dashboard
• Support

Contributing

This public repository is a source snapshot maintained from Pushary's source monorepo. Open issues and pull requests here; accepted changes are applied upstream and then mirrored back. Do not publish registry releases from this mirror.

Install Node.js 24 or newer for the source checks, then run:

npm ci
npm run typecheck
npm test
npm run build