In-App Messages

The Tappd Web SDK supports displaying in-app messages (banners, popups, and modals) created in your Tappd dashboard. Messages are automatically fetched and displayed when enabled, or you can manually control their display.

Overview

In-app messages allow you to:

Display personalized messages to users based on their behavior
Show banners at the top or bottom of the screen
Display popups and modals with rich content
Track message views, clicks, and dismissals
Automatically evaluate trigger conditions and expiration dates

Configuration

Enable in-app messages when initializing the SDK:

javascript

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

Configuration Options

Option	Type	Default	Description
`enableInAppMessages`	`boolean`	`true`	Enable/disable in-app message rendering
`autoDisplayMessages`	`boolean`	`true`	Automatically fetch and display pending messages
`messagePollingInterval`	`number`	`30`	Interval in seconds for polling new messages
`messageContainerId`	`string`	`undefined`	Custom DOM container ID (if not provided, messages are appended to `document.body`)

Automatic Display

When autoDisplayMessages is enabled, the SDK will:

Automatically fetch pending messages for the identified user
Evaluate trigger conditions (immediate, delay, event-based, page visit)
Display messages that are ready to be shown
Track events (viewed, clicked, dismissed)
Poll periodically for new messages (based on messagePollingInterval)

javascript

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: true,
  messagePollingInterval: 30  // Check for new messages every 30 seconds
});

// Identify user - messages will be fetched automatically
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe'
});

// Messages are now being displayed automatically!

Manual Control

You can also manually control message fetching and display:

Fetch Messages

javascript

// Fetch all pending messages for the current user
const messages = await tappd.getInAppMessages();
console.log(`Found ${messages.length} pending messages`);

Display a Specific Message

javascript

const messages = await tappd.getInAppMessages();

// Display the first message
if (messages.length > 0) {
  await tappd.displayInAppMessage(messages[0]);
}

Display All Pending Messages

javascript

// Fetch and display all pending messages
await tappd.displayPendingMessages();

Dismiss a Message

javascript

// Dismiss a message by its ID
await tappd.dismissMessage('message_id_123');

Message Types

The SDK supports three message types, each with different display behaviors:

Banners are fixed-position messages that appear at the top, bottom, or center of the screen.

Position: Top, bottom, or center
Dismissible: Can include a dismiss button
Animation: Slide or fade animation
Use cases: Important announcements, notifications, promotions

javascript

// Banner messages are automatically rendered based on their configuration
// No additional code needed when using autoDisplayMessages

Popups are centered modal dialogs with an optional overlay.

Size: Smaller modal (typically max 500px wide)
Overlay: Optional semi-transparent background overlay
Close button: Optional close button
Animation: Fade or slide animation
Use cases: Important alerts, confirmations, CTAs

Modals are larger centered modal dialogs, similar to popups but with more space.

Size: Larger modal (typically max 600px wide)
Overlay: Optional semi-transparent background overlay
Close button: Optional close button
Animation: Fade or slide animation
Use cases: Detailed information, forms, multi-step flows

Message Blocks

Messages can contain multiple content blocks:

Image Block

Display images with alignment and sizing options.

Properties:

url - Image URL
alt - Alt text for accessibility
width - Image width
height - Image height
alignment - left, center, right, or full

Text Block

Display text content with styling options.

Properties:

content - Text content (supports basic HTML)
fontSize - sm, base, lg, xl, 2xl, or custom size
fontWeight - normal or bold
color - Text color (hex, rgb, or named color)
alignment - left, center, right, or justify

Button Block

Clickable buttons with links and custom styling.

Properties:

text - Button text
link - URL to navigate to
textColor - Button text color
backgroundColor - Button background color
linkBehavior - browser (open in new tab), in_app, or deeplink
alignment - left, center, or right

HTML Block

Raw HTML content (sanitized for security).

Properties:

content - Raw HTML content

Event Tracking

The SDK automatically tracks message interactions:

Message Viewed

Tracked when a message is displayed:

javascript

// Automatically tracked by SDK
// Event: message.viewed
// Properties: { messageId: '...' }

Message Clicked

Tracked when a button in a message is clicked:

javascript

// Automatically tracked by SDK
// Event: message.clicked
// Properties: { messageId: '...', buttonText: '...', buttonLink: '...' }

Message Dismissed

Tracked when a message is dismissed:

javascript

// Automatically tracked by SDK
// Event: message.dismissed
// Properties: { messageId: '...' }

Manual Event Tracking

You can also manually track message events:

javascript

await tappd.trackMessageEvent('message_id_123', 'clicked', {
  buttonText: 'Sign Up',
  buttonLink: 'https://example.com/signup'
});

API Reference

getInAppMessages()

Fetch pending in-app messages for the current user.

Returns: Promise<InAppMessage[]>

Example:

javascript

const messages = await tappd.getInAppMessages();
messages.forEach(message => {
  console.log('Message: ${message.config.messageType}');
  console.log('Status: ${message.status}');
});

displayInAppMessage(message)

Display a specific in-app message.

Parameters:

Parameter	Type	Required	Description
`message`	`InAppMessage`	Yes	The message object to display

Returns: Promise<void>

Example:

javascript

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

displayPendingMessages()

Fetch and display all pending messages that are ready to be shown.

Returns: Promise<void>

Example:

javascript

// Manually trigger message display
await tappd.displayPendingMessages();

dismissMessage(messageId)

Dismiss a message and track the dismissal event.

Parameters:

Parameter	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message to dismiss

Returns: Promise<void>

Example:

javascript

await tappd.dismissMessage('message_id_123');

trackMessageEvent(messageId, eventType, metadata)

Track a custom message interaction event.

Parameters:

Parameter	Type	Required	Description
`messageId`	`string`	Yes	The ID of the message
`eventType`	`string`	Yes	Event type (e.g., 'viewed', 'clicked', 'dismissed')
`metadata`	`object`	No	Additional event metadata

Returns: Promise<void>

Example:

javascript

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

Complete Example

javascript

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

// Initialize SDK with in-app messages enabled
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 user - messages will be fetched and displayed automatically
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe'
});

// Optional: Manually fetch messages
const messages = await tappd.getInAppMessages();
console.log(`Found ${messages.length} messages`);

// Optional: Manually display messages
await tappd.displayPendingMessages();

// Messages are now being displayed automatically!
// The SDK will:
// 1. Poll for new messages every 30 seconds
// 2. Display messages when trigger conditions are met
// 3. Track all message interactions
// 4. Handle message dismissal

Styling

The SDK injects CSS styles automatically. Messages are styled with:

Responsive design (mobile and desktop)
Smooth animations (slide, fade)
Customizable colors and fonts
Proper z-index layering
Touch-friendly interactions

Custom Styling

You can override default styles using CSS:

css

/* Customize banner styles */
.tappd-message-banner {
  background-color: #your-color !important;
  border-radius: 8px !important;
}

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

/* Customize button styles */
.tappd-button {
  border-radius: 6px !important;
}

Best Practices

Identify users early: Make sure to call identify() as soon as users log in so messages can be personalized
Monitor message performance: Use the tracked events to measure message effectiveness
Test trigger conditions: Ensure your trigger conditions are properly configured in the dashboard
Respect user preferences: Consider allowing users to opt-out of in-app messages
Mobile optimization: Test messages on mobile devices to ensure they display correctly

Troubleshooting

Messages not displaying

Check that enableInAppMessages is set to true
Verify the user is identified (identify() has been called)
Check browser console for errors (enable debug: true)
Verify messages exist in the dashboard and are published
Check trigger conditions are met

Messages displaying too frequently

Adjust messagePollingInterval to reduce polling frequency
Check message expiration settings in the dashboard
Ensure messages are being dismissed properly

Styling issues

Check for CSS conflicts with your site's styles
Use browser dev tools to inspect message elements
Override styles using CSS as needed

In-App Bridge - Braze-like bridge functionality for capturing data and triggering actions
API Reference - Complete API documentation
Configuration - All configuration options
Examples - Code examples

In-App Messages ​

Overview ​

Configuration ​

Configuration Options ​

Automatic Display ​

Manual Control ​

Fetch Messages ​

Display a Specific Message ​

Display All Pending Messages ​

Dismiss a Message ​

Message Types ​

1. Banner ​

2. Popup ​

3. Modal ​

Message Blocks ​

Image Block ​

Text Block ​

Button Block ​

HTML Block ​

Event Tracking ​

Message Viewed ​

Message Clicked ​

Message Dismissed ​

Manual Event Tracking ​

API Reference ​

getInAppMessages() ​

displayInAppMessage(message) ​

displayPendingMessages() ​

dismissMessage(messageId) ​

trackMessageEvent(messageId, eventType, metadata) ​

Complete Example ​

Styling ​

Custom Styling ​

Best Practices ​

Troubleshooting ​

Messages not displaying ​

Messages displaying too frequently ​

Styling issues ​

Related Documentation ​

In-App Messages

Overview

Configuration

Configuration Options

Automatic Display

Manual Control

Fetch Messages

Display a Specific Message

Display All Pending Messages

Dismiss a Message

Message Types

1. Banner

2. Popup

3. Modal

Message Blocks

Image Block

Text Block

Button Block

HTML Block

Event Tracking

Message Viewed

Message Clicked

Message Dismissed

Manual Event Tracking

API Reference

getInAppMessages()

displayInAppMessage(message)

displayPendingMessages()

dismissMessage(messageId)

trackMessageEvent(messageId, eventType, metadata)

Complete Example

Styling

Custom Styling

Best Practices

Troubleshooting

Messages not displaying

Messages displaying too frequently

Styling issues

Related Documentation