Skip to main content
In-app messages let you surface timely, personalized content to your users without requiring a page reload or a new deployment. You create and manage messages in the Tappd dashboard — the SDK handles fetching them, evaluating trigger conditions, rendering the UI, and tracking interactions automatically.

​
Configuration

Enable in-app messages when you initialize the SDK: 
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
  enableInAppMessages: true,       // Enable message rendering (default: true)
  autoDisplayMessages: true,       // Automatically display pending messages (default: true)
  messagePollingInterval: 30,      // Poll for new messages every N seconds (default: 30)
  messageContainerId: 'custom-id'  // Optional: custom DOM container ID
});

​
Configuration Options

​
enableInAppMessages
boolean
default:"true"
Enable or disable in-app message rendering entirely.
​
autoDisplayMessages
boolean
default:"true"
When true, the SDK automatically fetches and displays pending messages for the identified user.
​
messagePollingInterval
number
default:"30"
How often (in seconds) the SDK polls for new messages.
​
messageContainerId
string
A custom DOM element ID to use as the message container. When omitted, messages are appended to document.body.

​
Automatic Display

When autoDisplayMessages is true, the SDK runs the full message lifecycle without any additional code from you:
1

Fetch Pending Messages

After identify() is called, the SDK fetches all messages the current user is eligible to receive.
2

Evaluate Trigger Conditions

Each message is evaluated against its configured trigger — immediate display, a time delay, a specific event, or a page visit.
3

Display Ready Messages

Messages that pass their trigger conditions are rendered in the DOM using the configured message type and content blocks.
4

Track Interactions

message.viewed, message.clicked, and message.dismissed events are tracked automatically.
5

Poll for New Messages

The SDK continues polling every messagePollingInterval seconds to pick up newly published messages.
const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: true,
  messagePollingInterval: 30
});

// Identifying the user triggers automatic message fetching
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe'
});
// Messages are now fetched and will display automatically

​
Manual Control

If you need to manage message display yourself, set autoDisplayMessages: false and use the methods below.

​
Fetch Messages

const messages = await tappd.getInAppMessages();
console.log(`Found ${messages.length} pending messages`);

​
Display a Specific Message

const messages = await tappd.getInAppMessages();

if (messages.length > 0) {
  await tappd.displayInAppMessage(messages[0]);
}

​
Display All Pending Messages

await tappd.displayPendingMessages();

​
Dismiss a Message

await tappd.dismissMessage('message_id_123');

​
Track a Message Event Manually

await tappd.trackMessageEvent('message_id_123', 'clicked', {
  buttonText: 'Get Started',
  buttonLink: '/signup'
});

​
Message Types

The SDK renders three message types, each suited to different use cases:

​
Message Blocks

Each message is composed of one or more content blocks. You configure these in the Tappd dashboard.
Displays an image with alignment and sizing control.
PropertyDescription
urlImage URL
altAlt text for accessibility
widthImage width
heightImage height
alignmentleft, center, right, or full
Displays styled text content. The content property supports basic HTML.
PropertyDescription
contentText content (supports basic HTML)
fontSizesm, base, lg, xl, 2xl, or a custom size
fontWeightnormal or bold
colorHex, RGB, or named color
alignmentleft, center, right, or justify
A clickable button that navigates to a link or triggers an action.
PropertyDescription
textButton label
linkDestination URL
textColorButton text color
backgroundColorButton background color
linkBehaviorbrowser (new tab), in_app, or deeplink
Injects raw HTML content. All content is sanitized before rendering.
PropertyDescription
contentRaw HTML string

​
Event Tracking

The SDK automatically fires these events for every message interaction:
EventWhen It Fires
message.viewedWhen a message is rendered and visible
message.clickedWhen a user clicks a button inside the message
message.dismissedWhen a user dismisses the message
All three events include the messageId property. Click events also include buttonText and buttonLink.

​
CSS Customization

The SDK injects default styles automatically. Override them in your own stylesheet: 
/* Customize banner appearance */
.tappd-message-banner {
  background-color: #your-color !important;
  border-radius: 8px !important;
}

/* Customize popup and modal appearance */
.tappd-message-popup,
.tappd-message-modal {
  border-radius: 12px !important;
  box-shadow: 0 10px 40px rgba(0, 0, 0, 0.3) !important;
}

/* Customize button appearance */
.tappd-button {
  border-radius: 6px !important;
}
Use your browser’s DevTools to inspect the injected message elements and find the exact class names you need to target.

​
Complete Example

import { TappdSDK } from '@tappd/web-sdk';

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  apiUrl: 'https://sdk.gotappd.com/api/v1/sdk',
  enableInAppMessages: true,
  autoDisplayMessages: true,
  messagePollingInterval: 30,
  debug: true
});

// Identify the user — messages are fetched and displayed automatically
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe'
});

// Optionally inspect pending messages
const messages = await tappd.getInAppMessages();
console.log(`Found ${messages.length} messages`);