Mobile In-App Messages: Banners, Popups, and Modals

In-app messages let you deliver personalized content — promotional banners, onboarding prompts, important alerts — directly inside your React Native app without requiring a separate release. You create and configure messages in the Tappd dashboard, and the SDK automatically fetches, evaluates trigger conditions, and hands them off to your app to render using the built-in MessageRenderer component.

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,
  autoDisplayMessages: true,
  messagePollingInterval: 30,
});

enableInAppMessages

boolean

default:"true"

Enable or disable in-app message rendering in your app. Set to false if you want to fully suppress all in-app messages.

autoDisplayMessages

boolean

default:"true"

When true, the SDK automatically fetches pending messages for the identified user, evaluates trigger conditions, and calls your render callback when a message is ready to display.

messagePollingInterval

number

default:"30"

How often (in seconds) the SDK polls for new messages. Lower values give more timely delivery; higher values reduce network activity.

React Native Integration

To render messages, register a callback with the SDK so it can hand off a message object to your component tree whenever one is ready to display.

Basic Setup

import React, { useState, useEffect } from 'react';
import { View } from 'react-native';
import TappdSDK from '@tappd/mobile-sdk';
import { MessageRenderer } from '@tappd/mobile-sdk/src/renderers/MessageRenderer';

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: true,
});

function App() {
  const [currentMessage, setCurrentMessage] = useState(null); // InAppMessage | null

  useEffect(() => {
    // Register the callback the SDK calls when a message is ready
    tappd.setMessageRenderCallback((message) => {
      setCurrentMessage(message);
    });

    return () => {
      tappd.setMessageRenderCallback(() => {});
    };
  }, []);

  const handleDismiss = async (messageId) => {
    await tappd.dismissMessage(messageId);
    setCurrentMessage(null);
  };

  const handleButtonClick = async (messageId, link, text) => {
    console.log('Button clicked:', { messageId, link, text });
    await handleDismiss(messageId);
  };

  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}

      {currentMessage && (
        <MessageRenderer
          message={currentMessage}
          onDismiss={handleDismiss}
          onButtonClick={handleButtonClick}
        />
      )}
    </View>
  );
}

Automatic Display

When autoDisplayMessages is true, the SDK handles the full delivery pipeline for you:

Fetch pending messages

After identify() is called, the SDK automatically retrieves any pending messages for that user from the Tappd API.

Evaluate trigger conditions

Each message is evaluated against its configured trigger (immediate, timed delay, or event-based) and expiration date.

Invoke your render callback

When a message is ready to display, the SDK calls the function you registered with setMessageRenderCallback(), passing the message object.

Track interactions automatically

The SDK automatically tracks message.viewed, message.clicked, and message.dismissed events as the user interacts with the message.

Poll for new messages

The SDK continues polling at the interval defined by messagePollingInterval to pick up newly published messages.

const tappd = new TappdSDK({
  appId: 'YOUR_APP_ID',
  enableInAppMessages: true,
  autoDisplayMessages: true,
  messagePollingInterval: 30,
});

// Identify the user — automatic message fetching begins here
await tappd.identify({
  external_id: 'user_123',
  email: 'john@example.com',
  name: 'John Doe',
});

// Register the render callback
tappd.setMessageRenderCallback((message) => {
  setCurrentMessage(message);
});

Manual Control

If you prefer to control when messages are fetched and displayed, you can bypass automatic display and call these methods directly.

Fetch messages
Display a specific message
Display all pending messages
Dismiss a message

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

const messages = await tappd.getInAppMessages();

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

// Fetch and display all messages that are ready to show
await tappd.displayPendingMessages();

// Dismiss a message by ID — also tracks the dismissal event
await tappd.dismissMessage('message_id_123');

Message Types

Banner

Banners are fixed-position messages that slide in at the top or bottom of the screen using absolute positioning.

Position: Top or bottom of the screen
Animation: Slide
Dismissible: Optional dismiss button
Use cases: Announcements, promotions, time-sensitive notifications

Popup

Modal

Message Blocks

Messages are composed of one or more content blocks, each rendered as a native React Native component.

Image Block

Renders images using React Native’s Image component.

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

Text Block

Renders text content using React Native’s Text component.

Property	Description
`content`	Text content to display
`fontSize`	`sm`, `base`, `lg`, `xl`, `2xl`, or a custom size
`fontWeight`	`normal` or `bold`
`color`	Text color (hex, rgb, or named color)
`alignment`	`left`, `center`, `right`, or `justify`

Button Block

Renders a tappable button using React Native’s TouchableOpacity.

Property	Description
`text`	Button label
`link`	URL opened via `Linking.openURL()`
`textColor`	Button text color
`backgroundColor`	Button background color
`linkBehavior`	`browser` (open URL), `in_app`, or `deeplink`
`alignment`	`left`, `center`, or `right`

HTML Block

Renders arbitrary HTML content using react-native-render-html.

Property	Description
`content`	Full HTML string to render

react-native-render-html is bundled inside the Tappd Mobile SDK. You do not need to install it separately in your project.

Event Tracking

The SDK tracks all standard message interactions automatically:

Event	Triggered when
`message.viewed`	The message is displayed to the user
`message.clicked`	A button inside the message is tapped
`message.dismissed`	The user dismisses the message

For custom interactions, call trackMessageEvent() directly:

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

Place MessageRenderer at the root of your navigation tree so messages appear above all screens, regardless of which route is currently active:

import { NavigationContainer } from '@react-navigation/native';
import { MessageRenderer } from '@tappd/mobile-sdk/src/renderers/MessageRenderer';

function App() {
  const [currentMessage, setCurrentMessage] = useState(null);

  useEffect(() => {
    tappd.setMessageRenderCallback((message) => {
      setCurrentMessage(message);
    });
  }, []);

  return (
    <NavigationContainer>
      {/* Your navigation structure */}

      {currentMessage && (
        <MessageRenderer
          message={currentMessage}
          onDismiss={(id) => {
            tappd.dismissMessage(id);
            setCurrentMessage(null);
          }}
        />
      )}
    </NavigationContainer>
  );
}

Complete Example

import React, { useState, useEffect } from 'react';
import { View, StyleSheet, Linking } from 'react-native';
import TappdSDK from '@tappd/mobile-sdk';
import { MessageRenderer } from '@tappd/mobile-sdk/src/renderers/MessageRenderer';

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

export default function App() {
  const [currentMessage, setCurrentMessage] = useState(null); // InAppMessage | null

  useEffect(() => {
    tappd.setMessageRenderCallback((message) => {
      setCurrentMessage(message);
    });

    tappd.identify({
      external_id: 'user_123',
      email: 'john@example.com',
      name: 'John Doe',
    });

    return () => {
      // Clear the callback on unmount
      tappd.setMessageRenderCallback(() => {});
    };
  }, []);

  const handleDismiss = async (messageId) => {
    await tappd.dismissMessage(messageId);
    setCurrentMessage(null);
  };

  const handleButtonClick = async (messageId, link, text) => {
    if (link && link !== '#') {
      Linking.openURL(link);
    }
    await handleDismiss(messageId);
  };

  return (
    <View style={styles.container}>
      {/* Your app content */}

      {currentMessage && (
        <MessageRenderer
          message={currentMessage}
          onDismiss={handleDismiss}
          onButtonClick={handleButtonClick}
        />
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
});

API Reference

Method	Returns	Description
`setMessageRenderCallback(callback)`	`void`	Registers the function the SDK calls when a message is ready to display.
`getInAppMessages()`	`Promise<InAppMessage[]>`	Fetches all pending in-app messages for the current user.
`displayInAppMessage(message)`	`Promise<void>`	Displays a specific message by calling the registered render callback.
`displayPendingMessages()`	`Promise<void>`	Fetches and displays all messages that are ready to show.
`dismissMessage(messageId)`	`Promise<void>`	Dismisses a message and tracks the `message.dismissed` event.
`trackMessageEvent(messageId, eventType, metadata?)`	`Promise<void>`	Manually tracks a message interaction with optional metadata.

Troubleshooting

Messages not displaying

Work through this checklist if messages aren’t appearing in your app:

Confirm enableInAppMessages is set to true in your SDK config.
Verify you have called setMessageRenderCallback() in your root component.
Make sure identify() has been called — messages are user-specific.
Enable debug: true in the SDK config and check the console for errors.
Confirm the messages are published in your Tappd dashboard.
Check that any configured trigger conditions are met.

Messages displaying too frequently

If the same message keeps reappearing:

Increase messagePollingInterval to poll less aggressively.
Check the expiration settings on the message in the dashboard.
Ensure dismissMessage() is being called correctly when a message is dismissed so the SDK records the dismissal.

Styling issues

If message styles look wrong or conflict with your app:

Check for StyleSheet conflicts between your app styles and the MessageRenderer component.
Ensure MessageRenderer is rendered at the correct level in the component tree (ideally at the root, above your navigation structure).
Test on both iOS and Android — some styles, such as shadows and font rendering, differ between platforms.

​Configuration

​React Native Integration

​Basic Setup

​Automatic Display

​Manual Control

​Message Types

​Message Blocks

​Event Tracking

​Integration with React Navigation

​Complete Example

​API Reference

​Troubleshooting

Configuration

React Native Integration

Basic Setup

Automatic Display

Manual Control

Message Types

Message Blocks

Event Tracking

Integration with React Navigation

Complete Example

API Reference

Troubleshooting