Nudgeflare documentation
Nudgeflare sends web push notifications to your visitors' browsers using the open Web Push standard (RFC 8030 delivery, RFC 8291 encryption, RFC 8292 VAPID). Each site has its own VAPID key pair, so you pay no per-message fee to us or to a push vendor.
- Add a site in the dashboard.
- Add the script tag and host the service worker.
- Design the prompt, then send campaigns or switch on automations.
Install
The site page shows your exact snippet. It has the form:
<script src="https://push.example.com/sdk/<siteId>/sdk.js" data-key="<site public key>" async></script>data-key is the site's SDK key (nfpk_…). It is not a secret, but the server only accepts a subscription that carries it and comes from a registered origin. Rotate it from the site page if you ever need to; update the script tag at the same time.
Platform guides
Plain HTML
Paste the script tag before </head> of every page and upload nudgeflare-sw.js to the web root.
WordPress
Add the script tag with a header-scripts plugin (or wp_head in your child theme). Upload nudgeflare-sw.js to the folder that contains wp-config.php so it is served from /nudgeflare-sw.js.
Next.js / React
Put nudgeflare-sw.js in public/ and load the SDK once, for example with next/script:
import Script from 'next/script';
<Script src="https://push.example.com/sdk/<siteId>/sdk.js" data-key="nfpk_…" strategy="afterInteractive" />Shopify-style themes
Add the script tag to the theme's layout file head. If your platform cannot serve a file from the root, use a proxy or redirect rule that serves /nudgeflare-sw.js from the same origin; a service worker must be served from the origin it controls.
Hosting the service worker
Download nudgeflare-sw.js from the site page (it is one line that imports the core from your Nudgeflare install) and host it at /nudgeflare-sw.js. It registers under its own scope (/nudgeflare-push/), never replaces an existing worker and never calls clients.claim(). Press Check my site: Nudgeflare fetches the file with a DNS-pinned request and marks the site active.
SDK reference
The SDK initialises itself from the script tag; there is no init call. It exposes window.Nudgeflare:
Nudgeflare.showPrompt(): show the opt-in prompt now (ignoring delay and scroll rules).Nudgeflare.setTags(['boots'])/removeTags([…]): tags are letters, numbers and_ : . - /(up to 64 characters).Nudgeflare.setAttributes({ plan: "pro", orders: 3 }): only attributes declared on the site are accepted (string, number, boolean, date).Nudgeflare.setExternalId('learner-4821'): lets your backend target this person through the API.Nudgeflare.unsubscribe(): removes the browser subscription and tells the server.
Prompts
A prompt is the soft ask shown before the browser's own dialog: slide-in card, bell button or native only. Rules: delay in seconds, scroll depth, minimum page views, URL include/exclude patterns (* wildcard) and device. After a dismissal it is not shown again for the re-ask period. The prompt text is yours and is not translated by the page translator.
Segments
Build audiences from allow-listed fields: tag, country, timezone, browser, OS, language, subscribed / last seen / last clicked dates, external id, site, clicked campaign and your declared attributes. Groups nest up to three levels with all / any. The estimate is live. A natural-language request to Gemini becomes the same rules and is shown for editing first.
Campaigns
Title up to 65 characters, body up to 240, up to two buttons, a click target with UTM merged. Send now, at a moment, or at a local time in every timezone: one wave per zone, unknown zones use the site default, DST handled per zone. A/B tests send variants to a test share and the winner by click-through rate (after a number of hours, with a minimum click count) to the rest. A campaign that reaches your monthly send quota pauses with the remaining count and can be resumed; nobody receives it twice.
Automations
- Welcome series: step 1 right after opt-in, later steps after their delay, optional tag conditions.
- RSS to push: polls an RSS or Atom feed (minimum 5 minutes), pushes new items once each (deduplicated by guid), skips old items.
- API trigger:
POST /api/v1/automations/<key>/triggerwithexternalIdsand anidempotencyKey.
REST API
Authenticate with Authorization: Bearer nf_sk_…. Scopes: subscribers:read|write, campaigns:read|write|send, automations:trigger, analytics:read. Keys can be limited to some sites. See the API reference and openapi.json. Error codes include origin_not_allowed, endpoint_not_allowed, quota_exceeded, subscriber_cap, idempotency_conflict, scope_missing, org_scope.
curl https://push.example.com/api/v1/campaigns?status=sent \
-H "Authorization: Bearer nf_sk_…"Webhooks
Events: subscription.created, subscription.expired, campaign.sent, automation.triggered. Each POST carries x-dev3-signature: t=…,v1=HMAC-SHA256(secret, body). Deliveries are made by the worker with retries; the log is in Developers.
Browser support
| Browser | Desktop | Mobile |
|---|---|---|
| Chrome | Yes | Yes (Android) |
| Edge | Yes | Yes (Android) |
| Firefox | Yes | Yes (Android) |
| Safari | Yes (macOS 13+) | iOS 16.4+, only from the Home Screen |
| Samsung Internet | — | Yes |
iOS Home Screen requirement: on iPhone and iPad (iOS 16.4+), web push only works for sites added to the Home Screen. Ask visitors to add the site, then show the prompt from inside the installed app.
Security
- VAPID private keys and every subscription (endpoint and keys) are encrypted at rest with your vault key. Back up
NUDGEFLARE_VAULT_KEY: losing it orphans every subscriber. - Subscriptions are accepted only from registered origins, with the site's SDK key, and only for known push-service hosts.
- Click links are signed per delivery; a tampered link is refused.
Troubleshooting
- Verify fails: the file must answer 200 at
/nudgeflare-sw.json the registered origin and point at this install. - Prompt never shows: check the URL rules, the delay and that the site is not paused.
- Subscribers stay unconfirmed: they count toward your cap after the first successful push or service-worker beacon.
- After rotating VAPID keys: existing subscribers must re-subscribe.