Documentation

Troubleshooting

Fast fixes for SDK delivery, experiments, analytics, and selector issues.

1) Quick triage

Snippetts

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

const sdk = initSpryUi({
  publicKey: "pk_...",
  host: window.location.host,
  apiBaseUrl: "https://spryui.com/api/sdk/v1",
  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 experiment/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.

Experiment does not split traffic

Likely causes: experiment inactive, invalid total weight, variant message filtered out, or deterministic assignment pinned to same user/session key.

Fix: activate experiment, ensure both variants are eligible, 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.modal.suppressed_by_modal
- arbitration.rail.fixed_banner_suppresses_fixed_toast

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