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, so 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, so 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.