> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tappd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# In-App Messages: Display and Manage with Tappd SDK

> Render personalized banners, popups, and modals from the Tappd dashboard with automatic trigger evaluation, event tracking, and CSS customization.

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:

```javascript theme={null}
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

<ParamField body="enableInAppMessages" type="boolean" default="true">
  Enable or disable in-app message rendering entirely.
</ParamField>

<ParamField body="autoDisplayMessages" type="boolean" default="true">
  When `true`, the SDK automatically fetches and displays pending messages for the identified user.
</ParamField>

<ParamField body="messagePollingInterval" type="number" default="30">
  How often (in seconds) the SDK polls for new messages.
</ParamField>

<ParamField body="messageContainerId" type="string">
  A custom DOM element ID to use as the message container. When omitted, messages are appended to `document.body`.
</ParamField>

## Automatic Display

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

<Steps>
  <Step title="Fetch Pending Messages">
    After `identify()` is called, the SDK fetches all messages the current user is eligible to receive.
  </Step>

  <Step title="Evaluate Trigger Conditions">
    Each message is evaluated against its configured trigger — immediate display, a time delay, a specific event, or a page visit.
  </Step>

  <Step title="Display Ready Messages">
    Messages that pass their trigger conditions are rendered in the DOM using the configured message type and content blocks.
  </Step>

  <Step title="Track Interactions">
    `message.viewed`, `message.clicked`, and `message.dismissed` events are tracked automatically.
  </Step>

  <Step title="Poll for New Messages">
    The SDK continues polling every `messagePollingInterval` seconds to pick up newly published messages.
  </Step>
</Steps>

```javascript theme={null}
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

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

### Display a Specific Message

```javascript theme={null}
const messages = await tappd.getInAppMessages();

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

### Display All Pending Messages

```javascript theme={null}
await tappd.displayPendingMessages();
```

### Dismiss a Message

```javascript theme={null}
await tappd.dismissMessage('message_id_123');
```

### Track a Message Event Manually

```javascript theme={null}
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:

<Tabs>
  <Tab title="Banner">
    Banners are fixed-position messages anchored to the top, bottom, or center of the screen. They support slide and fade animations and are ideal for announcements, promotions, and notifications.

    ```javascript theme={null}
    // Banners render automatically based on dashboard configuration
    // No additional code is needed when autoDisplayMessages is true
    ```
  </Tab>

  <Tab title="Popup">
    Popups are centered modal dialogs (max \~500px wide) with an optional semi-transparent overlay and close button. Use them for important alerts, confirmations, and calls to action.
  </Tab>

  <Tab title="Modal">
    Modals are larger centered dialogs (max \~600px wide), also with optional overlay and close button. They work well for detailed information, forms, and multi-step flows.
  </Tab>
</Tabs>

## Message Blocks

Each message is composed of one or more content blocks. You configure these in the Tappd dashboard.

<Accordion title="Image Block">
  Displays an image with alignment and sizing control.

  | Property    | Description                          |
  | ----------- | ------------------------------------ |
  | `url`       | Image URL                            |
  | `alt`       | Alt text for accessibility           |
  | `width`     | Image width                          |
  | `height`    | Image height                         |
  | `alignment` | `left`, `center`, `right`, or `full` |
</Accordion>

<Accordion title="Text Block">
  Displays styled text content. The `content` property supports basic HTML.

  | Property     | Description                                       |
  | ------------ | ------------------------------------------------- |
  | `content`    | Text content (supports basic HTML)                |
  | `fontSize`   | `sm`, `base`, `lg`, `xl`, `2xl`, or a custom size |
  | `fontWeight` | `normal` or `bold`                                |
  | `color`      | Hex, RGB, or named color                          |
  | `alignment`  | `left`, `center`, `right`, or `justify`           |
</Accordion>

<Accordion title="Button Block">
  A clickable button that navigates to a link or triggers an action.

  | Property          | Description                                  |
  | ----------------- | -------------------------------------------- |
  | `text`            | Button label                                 |
  | `link`            | Destination URL                              |
  | `textColor`       | Button text color                            |
  | `backgroundColor` | Button background color                      |
  | `linkBehavior`    | `browser` (new tab), `in_app`, or `deeplink` |
</Accordion>

<Accordion title="HTML Block">
  Injects raw HTML content. All content is sanitized before rendering.

  | Property  | Description     |
  | --------- | --------------- |
  | `content` | Raw HTML string |
</Accordion>

## Event Tracking

The SDK automatically fires these events for every message interaction:

| Event               | When It Fires                                  |
| ------------------- | ---------------------------------------------- |
| `message.viewed`    | When a message is rendered and visible         |
| `message.clicked`   | When a user clicks a button inside the message |
| `message.dismissed` | When 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:

```css theme={null}
/* 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;
}
```

<Tip>
  Use your browser's DevTools to inspect the injected message elements and find the exact class names you need to target.
</Tip>

## Complete Example

```javascript theme={null}
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`);
```