# WordPress

Source: https://pushary.com/docs/web-push/client-sdk/wordpress
Last updated: 2026-05-11

> Add Pushary push notifications to your WordPress site in 2 minutes

## Prerequisites [#prerequisites]

* WordPress site served over **HTTPS**
* Admin access to your WordPress dashboard
* A Pushary account - [sign up free](https://pushary.com) if you haven't already

***

## Step 1: Get Your Code from the Dashboard [#step-1-get-your-code-from-the-dashboard]

Everything you need is in your site's **Settings → Integration** tab.

1. Open your [Pushary dashboard](https://pushary.com/dashboard) → **Sites** → click your site → **Settings**
2. Click **Download Service Worker** - save the `pushary-sw.js` file
3. Upload `pushary-sw.js` to your WordPress root directory (same folder as `wp-config.php` and `wp-login.php`) via FTP or your host's file manager
4. Back in the dashboard, copy the **SDK snippet** - it already has your site key filled in

If you don't have FTP access, add this to your theme's `functions.php` to serve the service worker from your domain:

```php
add_action('init', function () {
    $path = strtok($_SERVER['REQUEST_URI'] ?? '', '?');
    if ($path !== '/pushary-sw.js') return;

    header('Content-Type: application/javascript');
    header('Service-Worker-Allowed: /');
    header('Cache-Control: no-cache');

    $response = wp_remote_get('https://pushary.com/pushary-sw.js');
    if (!is_wp_error($response)) {
        echo wp_remote_retrieve_body($response);
    }
    exit;
});
```

***

## Step 2: Add to WordPress [#step-2-add-to-wordpress]

Paste the snippet you copied into your WordPress site's `<head>`. Pick whichever method you prefer:

**WPCode plugin (recommended):** Install [WPCode](https://wordpress.org/plugins/insert-headers-and-footers/), go to **Code Snippets → Header & Footer**, paste into **Header**.

**Theme editor:** Go to **Appearance → Theme File Editor → header.php**, paste before `</head>`. Note: theme updates will overwrite this.

**functions.php:** Wrap the same snippet in a `wp_head` hook:

```php
add_action('wp_head', function () {
    ?>
    <script src="https://pushary.com/sdk/pushary.js"></script>
    <script>
      var pushary = createPushary({
        siteKey: 'PASTE_YOUR_SITE_KEY_HERE',
        debug: true
      });
    </script>
    <?php
});
```

Replace `PASTE_YOUR_SITE_KEY_HERE` with the `pk_...` key from Step 1. Or better yet, just paste the full snippet from the dashboard into WPCode - no PHP needed.

A branded notification banner will appear at the bottom of the page after 3 seconds. It uses your site's logo, colors, and text from the dashboard's **Settings → Customize** tab. The user clicks "Enable Notifications" and the native browser prompt fires. On iOS, it redirects to the subscribe app which handles the Add to Home Screen flow.

***

## Verify [#verify]

1. Visit your site in any browser (Chrome, Firefox, Safari, Edge)
2. A branded banner should appear at the bottom of the page after 3 seconds
3. Click "Enable Notifications" → the native browser permission prompt appears
4. Click Allow
5. Check your Pushary dashboard → **Subscribers** - you should see the new subscriber

For deeper debugging, open DevTools (`F12`) → **Application → Service Workers** and confirm `pushary-sw.js` is registered. The console will show `[Pushary]` logs since `debug: true` is on by default in the dashboard snippet.

***

## Customize the Banner [#customize-the-banner]

The banner pulls its branding from your site settings. Go to **Sites → Settings → Customize** in the dashboard to change:

* **Primary color** - the CTA button color
* **Headline** - the main text (e.g., "Stay in the loop")
* **Description** - the subtitle text
* **Button text** - the CTA label (default: "Enable Notifications")
* **Logo** - shown in the banner

You can also control the banner behavior from the SDK:

```html
<script>
  var pushary = createPushary({
    siteKey: 'pk_...',
    banner: {
      delay: 5000,          // show after 5 seconds (default 3000)
      position: 'top',      // 'bottom' (default) or 'top'
      dismissDuration: 48   // hours to suppress after dismiss (default 72)
    }
  });
</script>
```

To disable the banner and use manual control:

```html
<script>
  var pushary = createPushary({
    siteKey: 'pk_...',
    banner: false,
    autoPrompt: false
  });

  document.getElementById('my-button').addEventListener('click', function () {
    pushary.promptForPermission();
  });
</script>
```

***

## WooCommerce [#woocommerce]

Tag subscribers for cart recovery and order notifications:

```html
<script>
  document.addEventListener('DOMContentLoaded', function () {
    if (typeof pushary !== 'undefined' && typeof wc_cart_params !== 'undefined') {
      pushary.setTags({ source: 'woocommerce', customer: 'true' });
    }
  });
</script>
```

For automated cart recovery and order confirmation notifications, use the [Server SDK](/docs/web-push/server-sdk/notifications) with WooCommerce webhooks.

***

## Troubleshooting [#troubleshooting]

### Banner not appearing [#banner-not-appearing]

**Check permission state:** Open DevTools (`F12`) → Console and type `Notification.permission`. If it returns `"denied"`, the banner won't show. Fix: click the lock/tune icon in the address bar → **Site Settings** → **Notifications** → set to &#x2A;*Ask (default)**, then reload the page.

**Previously dismissed:** The banner stays hidden for 72 hours after the user clicks "Not now." To reset during testing, open DevTools → Console and run `localStorage.removeItem('pushary_banner_dismissed')`, then reload.

**Check debug logs:** The dashboard snippet includes `debug: true` by default. Open DevTools → Console and look for `[Pushary]` logs. You'll see messages like `Initializing with site key`, `Fetching site config for banner`, `Banner dismissed, skipping`, or `Banner injected`.

**Domain mismatch:** Open DevTools → **Network** tab, reload the page, and look for a request to `/api/v1/site-config`. If it returns **401**, the site key is invalid. If the request to `/api/v1/vapid-key` returns **403**, the domain in the dashboard doesn't match the site's actual domain.

### Caching plugins blocking the service worker [#caching-plugins-blocking-the-service-worker]

Exclude `/pushary-sw.js` from caching:

* **WP Super Cache:** Settings → Advanced → Rejected Strings → add `pushary-sw.js`
* **W3 Total Cache:** Performance → Page Cache → Never Cache → add `/pushary-sw.js`
* **LiteSpeed Cache:** Settings → Excludes → Do Not Cache URIs → add `/pushary-sw.js`

### CDN stripping the service worker [#cdn-stripping-the-service-worker]

The service worker must be served from your origin domain. Add a page rule to bypass cache for `/pushary-sw.js`.

**Cloudflare:** Rules → Page Rules → `yoursite.com/pushary-sw.js` → Cache Level: Bypass

### Security plugins blocking scripts [#security-plugins-blocking-scripts]

If Wordfence or Sucuri blocks the SDK:

1. Whitelist `pushary.com` as an allowed external script domain
2. If using CSP headers, add `script-src 'self' https://pushary.com`

### iOS users [#ios-users]

iOS Safari doesn't support push notifications in the regular browser - the user must add the site to their Home Screen first. The SDK handles this automatically: when it detects iOS, the banner's CTA opens the Pushary subscribe app which guides the user through the Add to Home Screen flow. No extra configuration needed.

### Safari on macOS [#safari-on-macos]

The SDK shows the banner on Safari desktop which triggers the native prompt from a user click - this works correctly. If the permission was previously blocked, go to **Safari → Settings → Websites → Notifications** and remove the site from the denied list.