Documentation

JavaScript SDK API Reference

Reference the SpryUI JavaScript SDK initialization options, website banner configuration, message payloads, callbacks, and analytics event shapes.

initSpryUi

Entry point for fetching messages, checking whether they should show, rendering them, and sending events.

Snippetts

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

const sdk = initSpryUi({
  publicKey: "YOUR_PROJECT_API_KEY",
  debug: false,
  onReady: (messages) => {
    console.log("eligible messages:", messages.length);
  },
  onError: (error) => {
    console.error("spryui error", error);
  },
});

Options

Required: publicKey. Commonly provided: env, debug, onReady, onError.

Snippetts

type SpryUiSdkOptions = {
  publicKey: string; // required
  env?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
  mountId?: string;
  defer?: boolean; // default true
  token?: string;
  userId?: string;
  sessionKey?: string;
  schemaVersion?: number; // default 1
  privacyMode?: "anonymous" | "persistent"; // default "anonymous"
  consentRequired?: boolean; // default false
  hasConsent?: boolean;
  optOut?: boolean;
  consentStorageKey?: string;
  optOutStorageKey?: string;
  visitorSeenStorageKey?: string;
  targetingContext?: {
    path?: string;
    device?: "mobile" | "tablet" | "desktop";
    referrer?: string | null;
    utmSource?: string | null;
    utmMedium?: string | null;
    utmCampaign?: string | null;
    country?: string | null;
    isFirstVisit?: boolean;
    isReturningVisitor?: boolean;
  };
  debug?: boolean; // default false
  onReady?: (messages) => void;
  onError?: (error) => void;
};

Instance Methods

Use refresh() after host-page state changes, and destroy() for teardown during SPA unmount/navigation.

Snippetts

type SpryUiSdkInstance = {
  refresh: () => Promise<void>;
  destroy: () => void;
  setConsent: (value: boolean, persist?: boolean) => void;
  setOptOut: (value: boolean, persist?: boolean) => void;
};

Message Payload Contract

Dashboard and SDK config endpoints provide message objects with content, targeting, schedule, and frequency fields.

Snippetts

type SpryUiSdkMessage = {
  messId?: string; // preferred id in SDK payloads
  id?: string;     // legacy fallback id
  type: "BANNER";
  position:
    | "TOP_FIXED" | "BOTTOM_FIXED"
    | "TOP_RELATIVE" | "BOTTOM_RELATIVE";
  priority: number;
  content: Record<string, unknown>;
  targeting?: {
    selector?: string;
    trigger?: {
      type?: "IMMEDIATE" | "DELAY" | "SCROLL" | "CLICK" | "EXIT_INTENT";
      delayMs?: number;
      scrollPercent?: number;
      clickSelector?: string;
    };
    paths?: string[];
  };
  frequency?: {
    perSession?: number;
    total?: number;
    cooldownMinutes?: number;
    cooldownHours?: number;
  };
};

Event Payload Contract

The SDK sends event payloads with message, session, and page context.

Snippetts

type SpryUiSdkEventPayload = {
  eventType: "IMPRESSION" | "CLICK" | "DISMISS" | "COMPLETE" | "DEBUG";
  messageId?: string;
  userKey?: string;
  sessionKey?: string;
  schemaVersion?: number;
  context?: Record<string, unknown>;
};