Troubleshooting & FAQ

The SDK logs richly to the browser console under [SDK] / [SDK][PWA] / [SDK][trackView] prefixes. When something looks off, open DevTools and read those lines first — they usually name the exact reason.

#"No prompt appears at all"

Check, in order:

autoPrompt is true? With the default false, nothing shows automatically.
Permission already set? If the visitor previously allowed or blocked notifications, the opt-in won't show (permission must be default).
Supported browser? DuckDuckGo, old iOS (<16.4), and most in-app webviews can't do push — see Browser Support. Look for [SDK][push-support] logs.
Config error? A [Sharepush] Configuration missing: log means apiUrl/apiKey (or the injected VAPID key) is absent — init() aborts.
On mobile, is the install prompt eligible? The push prompt waits behind the PWA prompt on mobile. If you see Modal not eligible after evaluation, the fallback should release the push prompt — make sure you're on the current SDK build.

#"The install (PWA) prompt never shows"

Missing manifest. The install prompt requires a valid <link rel="manifest"> with name, start_url, and icons. Look for Eligibility false: missing required PWA assets.
Platform disabled. Check pwaPromptPlatforms — a typo'd key is silently ignored, and the array form is a strict allowlist.
Cooldown active. After a dismissal it's suppressed for pwaPromptDismissDays (default 7). Look for Eligibility false: cooldown active until ….
Already installed. If running standalone, it's intentionally skipped.

#"View counts (`viewed`) are much lower than clicks"

viewed only fires when the visitor lands on a page where the SDK runs and the attribution ticket is found. Common causes:

Landing pages without the SDK — if clicks go to pages that don't include the snippet, no viewed fires.
Host mismatch — the attribution ticket is stored per-origin. If subscribers are on www.example.com but campaign links point to example.com (or vice-versa), the ticket won't be found. Keep campaign destinations on the same host.
Look for the console trail: ticket found in IDB → sending viewed event means it worked; no ticket found in IDB for URL after retries means attribution missed.

#"Users don't get iOS push"

iOS requires both iOS 16.4+ and the site installed to the Home Screen. If a user is on Safari in a normal tab, push is unavailable by Apple's rules — they must install first. See Browser Support.

#"I deployed a new SDK/service worker but users still run the old one"

Service workers and the SDK bundle are cached. The SharePush endpoints are designed to auto-refresh on deploy (the served bundle key is derived from the built file, so a new build invalidates it automatically) and the service worker is registered to revalidate its imports. In practice:

A normal deploy is picked up on the visitor's next navigation — no manual cache flush needed.
Service workers update lazily; expect a short rollout window as visitors return.
For a config-only change (no code rebuild), an operator can force-refresh the served bundle via the platform's cache-flush command.

#Useful console checks (paste in DevTools on a page with the SDK)

 1// What did the SDK decide about this device?
 2console.table({
 3  ua: navigator.userAgent,
 4  mobileOs: Sharepush._getMobileOs(),                 // 'ios' | 'android' | 'other'
 5  classification: JSON.stringify(Sharepush._resolveDeviceClassification()),
 6  browser: Sharepush.getBrowser(),
 7  permission: Sharepush.getPermission()
 8});

#Nothing shows and no logs appear

If you see no [SDK] logs at all, the script likely didn't load or init() wasn't called. Verify:

The <script src=".../api/v1/sdk.js"> tag loads (200 in the Network tab).
Sharepush.init({...}) runs after it, with valid apiUrl and apiKey.
No Content-Security-Policy is blocking the script or the service worker.

Back to the index.