Skip to main content
The In-App Message Bridge gives your in-app messages a direct line to the Tappd backend. When a user clicks a button or submits a form inside a message, the SDK automatically fires a request to the Bridge API, which processes the action — tracking an event, updating a profile, or capturing form data — and links it to the identified customer. You configure all of this in the Tappd dashboard; no custom code is required.

​
How It Works

When a user interacts with an in-app message, the SDK follows this sequence:
1

Capture the interaction

The SDK detects a button click or form submission inside the rendered message.
2

Send to Bridge API

The SDK constructs a request payload — including the action type, any form data, and the customer’s identifiers — and sends it to the appropriate Bridge API endpoint.
3

Process the action

The Tappd backend processes the action: tracking an event, updating profile attributes, or saving form data.
4

Identify and link the customer

The customer is automatically identified from the included identifiers and linked to the action. If no matching customer exists, one is created automatically.

​
Button Actions

Buttons in in-app messages can trigger four types of actions. You configure the action type for each button in the message editor inside the Tappd dashboard.
The close action dismisses the message when the button is clicked. No additional configuration or API call is required — the SDK handles this entirely client-side.

​
Form Data Capture

Forms inside in-app messages capture user input and forward it to the Bridge API’s /capture endpoint on submission. You control what happens to that data by setting a submit action type in the dashboard message editor.
Creates an event in Tappd and maps form field values to event properties.
Combining Button Actions with Form DataCombining Button Actions with Form Data
When a submit button lives inside a form block, the SDK automatically attaches the collected formData to the button’s bridge action request. You don’t need any additional configuration.

​
Customer Identification

The Bridge API identifies customers using one or more of the following fields, all of which the SDK includes automatically in every request:
At least one identifier must be present in every bridge request. If no matching customer is found, Tappd automatically creates one using the provided identifiers.
Call identify() before your messages are displayed to ensure clean customer linking:

​
Examples

A promotional banner has a “Learn More” button. Clicking it fires a track_event action configured entirely in the dashboard.Dashboard configuration:
  • Action type: track_event
  • Event name: promo_banner_clicked
  • Event properties: { "campaign": "summer_sale", "position": "top" }
When the user clicks the button, the SDK calls /bridge/action with actionType: "track_event" and the configured event name and properties. The event is created in Tappd immediately and linked to the identified customer.
A modal form collects email addresses and first names for a newsletter opt-in.Dashboard configuration:
  • Form fields: email (required), name (optional)
  • Submit action type: both
  • Event name: newsletter_signup
  • Event properties mapping: { "email": "email" }
  • Profile attributes mapping: { "newsletter_subscribed": "true", "email": "email" }
On submission, the SDK calls /bridge/capture. Tappd creates a newsletter_signup event and updates the customer profile with newsletter_subscribed = true and their email address — in a single API call.
A banner button upgrades the user’s segment immediately when clicked, which can then gate them into a separate journey.Dashboard configuration:
  • Action type: update_profile
  • Profile attributes: { "user_segment": "premium", "upgrade_date": "{{ date }}" }
When the user clicks the button, the SDK calls /bridge/action with actionType: "update_profile". Tappd writes the user_segment and upgrade_date attributes to the customer’s profile. Other journeys listening for a user_segment = "premium" condition can then enroll the customer automatically.

​
Best Practices

Call identify() before any in-app message is shown. Without at least one identifier, the Bridge API cannot link the action to a customer record.
Use consistent, descriptive event names such as newsletter_signup or promo_banner_clicked. Clear naming makes analytics and journey conditions easier to manage as your workspace grows.
Use the property/attribute mapping feature to rename form fields to semantically meaningful keys. For example, map the form field name to the profile attribute full_name so your data model stays clean.
Use the both submit action type when you want to record an event for analytics and update the customer profile at the same time — this is more efficient than chaining two separate actions.
The SDK handles bridge errors internally, but errors are visible in the browser console. Always test button actions and form submissions in a development environment — check the Network tab in DevTools to verify that /bridge/action and /bridge/capture requests are firing with the expected payloads.