@kitbase/messaging

Kitbase In-App Messaging SDK for TypeScript and JavaScript. Fetches targeted messages and renders them directly in the page — modals, banners, cards, and full-screen images with automatic stacking.

Installation

npm install @kitbase/messaging
# or
pnpm add @kitbase/messaging
# or
yarn add @kitbase/messaging

Quick Start

import { init } from '@kitbase/messaging';

const messaging = init({
  sdkKey: 'your-sdk-key',
  userId: currentUser.id,
  metadata: { plan: 'pro' },
});

// Messages are fetched and rendered automatically!

That's it — messages matching your targeting criteria will appear as modals, banners, cards, or images with no extra code.

Script Tag (CDN)

No bundler required. Works with any page — PHP, WordPress, static HTML, etc.

<!-- unpkg -->
<script src="https://unpkg.com/@kitbase/messaging/dist/cdn.js"></script>

<!-- or jsdelivr -->
<script src="https://cdn.jsdelivr.net/npm/@kitbase/messaging/dist/cdn.js"></script>

<script>
  window.KITBASE_MESSAGING = {
    sdkKey: 'your-sdk-key',
    userId: 'user_123',
    metadata: { plan: 'free', country: 'US' },
  };
</script>
<script src="https://unpkg.com/@kitbase/messaging/dist/cdn.js"></script>
<!-- Messages appear automatically! -->

The script auto-initializes and exposes window.kitbaseMessaging for further control:

<script>
  // After user logs in
  window.kitbaseMessaging.identify('user_456');
</script>

Or initialize manually:

<script src="https://unpkg.com/@kitbase/messaging/dist/cdn.js"></script>
<script>
  var messaging = KitbaseMessaging.init({ sdkKey: 'your-sdk-key' });

  messaging.identify('user_123');
  messaging.close(); // clean up
</script>

Configuration

| Option | Type | Default | Description | |---|---|---|---| | sdkKey | string | (required) | Your Kitbase SDK key | | baseUrl | string | 'https://api.kitbase.dev' | API base URL (for self-hosted instances) | | userId | string | — | Current user ID. Filters out already-viewed show-once messages | | metadata | Record<string, string> | — | Key-value pairs for targeting evaluation | | pollInterval | number | 60000 | Polling interval in ms. Set to 0 to fetch once only | | autoShow | boolean | true | Automatically render messages in the page | | onShow | (message) => void | — | Called when a message is displayed | | onDismiss | (message) => void | — | Called when a message is dismissed | | onAction | (message, button) => void \| false | — | Called on button click. Return false to prevent navigation |

API

init(config): Messaging

Initialize the SDK. Creates a singleton instance.

import { init } from '@kitbase/messaging';

const messaging = init({ sdkKey: 'your-sdk-key' });

getInstance(): Messaging | null

Get the current singleton instance.

import { getInstance } from '@kitbase/messaging';

const messaging = getInstance();

messaging.identify(userId)

Set the current user. Triggers an immediate re-fetch to filter out already-viewed show-once messages.

messaging.identify('user_123');

messaging.reset()

Clear the user and dismissed state. Call on logout.

messaging.reset();

messaging.markViewed(messageId)

Record that the user has viewed a message. The message is removed from the UI immediately and the view is recorded on the server. Requires identify() to have been called first.

messaging.markViewed('msg_abc');

messaging.getMessages(options?)

Fetch messages without rendering (data-only). Useful with autoShow: false.

const messaging = init({ sdkKey: '...', autoShow: false });
const messages = await messaging.getMessages();

messaging.subscribe(callback, options?)

Subscribe to messages with polling. Returns an unsubscribe function.

const unsub = messaging.subscribe(
  (messages) => renderMyUI(messages),
  { pollInterval: 30_000 },
);

// Later
unsub();

messaging.close()

Stop polling, remove all rendered UI, and clean up.

Message Types

The SDK renders four message types, each with automatic stacking:

| Type | Behavior | |---|---| | modal | Centered overlay with backdrop | | banner | Fixed to top, stacks vertically | | card | Fixed to bottom-right, stacks vertically | | image | Full-screen image overlay |

All rendering uses shadow DOM for complete style isolation from your page.

Behavior

• Polling pauses when the browser tab is hidden and resumes immediately when the tab becomes visible again.
• Dismissed messages are tracked in-memory for the current session and filtered from subsequent polls.
• Show-once messages are filtered server-side when a userId is provided.

TypeScript Types

import type {
  MessagingConfig,
  InAppMessage,
  MessageType,
  MessageButton,
  GetMessagesOptions,
  SubscribeOptions,
} from '@kitbase/messaging';

Error Types

import {
  MessagingError,      // Base error
  AuthenticationError,  // Invalid SDK key (401)
  ApiError,             // API error (non-2xx)
  ValidationError,      // Invalid config or missing params
  TimeoutError,         // Request timed out
} from '@kitbase/messaging';

License

MIT