Documentation

API Reference

The SDK options, message shape, and event shape.

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: "pk_...",
  host: window.location.host,
  apiBaseUrl: "https://spryui.com/api/sdk/v1",
  debug: false,
  onReady: (messages) => {
    console.log("eligible messages:", messages.length);
  },
  onError: (error) => {
    console.error("spryui error", error);
  },
});

Options

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

Snippetts

type SpryUiSdkOptions = {
  publicKey: string; // required
  env?: "DEVELOPMENT" | "STAGING" | "PRODUCTION";
  host?: string;
  mountId?: string;
  defer?: boolean; // default true
  apiBaseUrl?: string;
  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;
  };
  bannerPlacement?: "fixed" | "relative"; // default "fixed"
  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>;
};