@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

``bash
npm install @pushary/sdk


or

yarn add @pushary/sdk

or

pnpm add @pushary/sdk
`

$3

`html

`

Quick Start

$3

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

$3

Copy the service worker file to your public directory:

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

$3

`typescript
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

$3

Creates a Pushary instance with the given configuration.

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

$3

#### promptForPermission(): Promise

Request notification permission from the user.

`typescript
const subscription = await pushary.promptForPermission()
`

#### subscribe(): Promise

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

`typescript
const subscription = await pushary.subscribe()
`

#### unsubscribe(): Promise

Unsubscribe from push notifications.

`typescript
await pushary.unsubscribe()
`

#### setExternalId(externalId: string): Promise

Associate an external ID with the subscriber for targeting.

`typescript
await pushary.setExternalId('user-123')
`

#### setTags(tags: Record): Promise

Set tags for subscriber segmentation.

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

#### isSupported(): boolean

Check if push notifications are supported.

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

Authentication

$3

Uses Site Key (public prefix):
- Format: pk_xxxxxxxx
- Safe to expose in client-side code
- Protected by domain validation

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

$3

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

$3

`tsx
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 Enable Notifications
}
`

$3

`tsx
'use client'

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

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

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

return (
pushary?.promptForPermission()}>
Enable Notifications

)
}
`

$3

`vue



`

TypeScript

Full TypeScript definitions are included:

`typescript
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:

`typescript
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