# Client SDK installation

Source: https://pushary.com/docs/web-push/client-sdk/installation
Last updated: 2026-10-23

> Install and configure the Pushary client SDK for your website

Use `@pushary/sdk` in your website to register the service worker, request notification permission, and subscribe visitors. To send notifications from your backend, use the [server SDK](/docs/web-push/server-sdk/installation).

## Installation [#installation]

Install the SDK using your preferred package manager:

```bash
npm install @pushary/sdk
# or
yarn add @pushary/sdk
# or
pnpm add @pushary/sdk
# or
bun add @pushary/sdk
```

### CDN (Script Tag) [#cdn-script-tag]

For quick integration without a build step:

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

## Service Worker Setup [#service-worker-setup]

The SDK requires a service worker to handle push notifications. 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
```

Or download from:

```
https://pushary.com/pushary-sw.js
```

The service worker must be accessible at `/pushary-sw.js` from your domain root.

## Basic Usage [#basic-usage]

### ES Modules [#es-modules]

```typescript
import { createPushary } from '@pushary/sdk'

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

By default, a branded banner appears after 3 seconds. The banner pulls your site's logo, colors, and text from the dashboard. The user clicks the CTA and the native browser permission prompt fires - this works on all browsers including Safari (which requires a user gesture).

On iOS, the banner redirects to the Pushary subscribe app which handles the Add to Home Screen flow automatically.

### Script Tag [#script-tag]

```html
<script src="https://pushary.com/sdk/pushary.js"></script>
<script>
  var pushary = createPushary({
    siteKey: 'pk_your_site_key',
    debug: true
  });
</script>
```

## Configuration Options [#configuration-options]

| Option                | Type                | Default               | Description                                                         |
| --------------------- | ------------------- | --------------------- | ------------------------------------------------------------------- |
| `siteKey`             | `string`            | required              | Your Pushary site key                                               |
| `apiUrl`              | `string`            | `https://pushary.com` | API endpoint URL                                                    |
| `banner`              | `boolean \| object` | `true`                | Show branded opt-in banner (see below)                              |
| `autoPrompt`          | `boolean`           | `true`                | Legacy: auto-prompt without banner (only used when `banner: false`) |
| `promptDelay`         | `number`            | `3000`                | Delay before showing banner/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                                        |

### Banner Options [#banner-options]

Pass an object to `banner` for fine-grained control:

| Option            | Type                              | Default          | Description                                                                   |
| ----------------- | --------------------------------- | ---------------- | ----------------------------------------------------------------------------- |
| `style`           | `'popover' \| 'bar'`              | `'popover'`      | Corner card (popover) or full-width bar                                       |
| `theme`           | `'light' \| 'dark'`               | `'light'`        | Light or dark banner background                                               |
| `corner`          | `'bottom-right' \| 'bottom-left'` | `'bottom-right'` | Corner placement (popover only)                                               |
| `position`        | `'bottom' \| 'top'`               | `'bottom'`       | Edge placement (bar only). Setting this without `style` infers `style: 'bar'` |
| `delay`           | `number`                          | `3000`           | Milliseconds before showing the banner                                        |
| `dismissDuration` | `number`                          | `72`             | Hours to suppress banner after user dismisses                                 |

Set `banner: false` to disable and use manual control via `pushary.promptForPermission()`.

## Framework Examples [#framework-examples]

### React [#react]

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

function App() {
  useEffect(() => {
    const pushary = createPushary({
      siteKey: 'pk_your_site_key',
      banner: false,
    })
    
    window.pushary = pushary
  }, [])

  const handleSubscribe = () => window.pushary?.promptForPermission()

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

### Next.js [#nextjs]

```tsx
'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!,
      banner: false,
    })
    setPushary(instance)
  }, [])

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

### Vue 3 [#vue-3]

```vue
<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',
    banner: false,
  })
})
</script>

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

### WordPress [#wordpress]

Go to your site's **Settings → Integration** tab in the Pushary dashboard - it has a ready-to-use snippet with your site key pre-filled and a download button for the service worker. Paste the snippet into your theme header and you're done.

See the [full WordPress guide](/docs/web-push/client-sdk/wordpress) for step-by-step instructions, WPCode setup, caching plugin config, and WooCommerce tips.