Documentation

Website Banner Troubleshooting

Fix website banners that do not appear or track by checking SDK installation, public keys, domains, environments, targeting, schedules, and CSP.

Nuxt SSR checks

Compare your setup with the live Nuxt SSR demo. Confirm the project public key and approved deployment domain, then inspect /api/_spryui/config and the server logs. An empty response can mean the config request failed; the module keeps the page usable without banners. Check the initial page source for banner markup, and disable shared page caching or prerendering.

1) Quick triage

Snippetts

import { initSpryUi } from "https://spryui.com/sdk/v1/index.mjs";

const sdk = initSpryUi({
  publicKey: "YOUR_PROJECT_API_KEY",
  debug: true,
});

Check debug overlay totals: total, matched, rendered.
Read suppressed and fallback reason lines.
Verify project key, domain, environment, and message status.
Retest in a fresh session for variant/frequency behavior.

2) Symptom matrix

No messages render

Likely causes: host/key mismatch, inactive message, schedule window, path mismatch, trigger not ready, dismissed/frequency-capped.

Fix: check debug suppressed reasons, then test one broad IMMEDIATE message with no frequency caps.

Variants do not split traffic

Likely causes: the message is inactive, all variants are disabled, invalid total weight, or deterministic assignment is pinned to the same user/session key.

Fix: activate the message, ensure at least two variants are enabled, and retest with a new session/user key.

CTR stays at 0%

Likely causes: no clickable CTA, users only dismiss, or clicks are outside actionable elements.

Fix: test with a valid anchor/button CTA and confirm CLICK events in analytics/event logs.

Message never reappears (frequency confusion)

Likely causes: perSession, total, cooldown, or persisted dismissal.

Fix: inspect suppression reasons, then clear local storage state and retest.

Snippetjs

localStorage.removeItem("spryui:display");
localStorage.removeItem("spryui:dismissed");

Click trigger or inline selector issues

Likely causes: missing/invalid CSS selector, selector typo, or anchor target missing in DOM at render time.

Fix: validate selector with document.querySelector(), trim spaces, and confirm the target exists before the message renders.

3) Suppression reason cheat sheet

Snippettext

Common suppression reasons:
- eligibility.trigger_not_ready
- eligibility.dismissed
- eligibility.frequency_capped
- arbitration.banner.lower_priority
- arbitration.banner.same_position

These reason keys appear in debug output and explain why messages were filtered or suppressed.