Use the Bridge API to process button clicks and form submissions in in-app messages — track events, update profiles, and capture data in real time.
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.
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.
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.
Close
Track Event
Update Profile
Open Link
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.
// Dashboard configuration:// Action type: "close"// No additional configuration needed
The track_event action fires a custom event and sends it to the Bridge API. Configure the event name and any event properties in the dashboard message editor.
The update_profile action writes one or more attributes to the customer’s profile when the button is clicked. Define the profileAttributes object in the dashboard message editor.
The link action opens a URL when the button is clicked. This is handled entirely in the browser — the SDK navigates to the configured URL without making any Bridge API call.
// Dashboard configuration:// Action type: "link"// Link: "https://example.com/promo"// Link behavior: "browser" (new tab) or "same_window"
Because the link action is client-side only, no event is tracked automatically. To also record the click, add a separate track_event button action, or use the form button combination pattern described below.
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.
Track Event
Creates an event in Tappd and maps form field values to event properties.
// Dashboard configuration:// Submit action type: "track_event"// Event name: "newsletter_signup"// Event properties mapping:// "email_address" ← form field "email"// "user_name" ← form field "name"
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.
The Bridge API identifies customers using one or more of the following fields, all of which the SDK includes automatically in every request:
Field
Source
userId
SDK currentUserId or anonymousId
external_id
Set via identify() call
email
Set via identify() call
phone
Set via identify() call
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:
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.
Example 2: Form captures newsletter signups
A modal form collects email addresses and first names for a newsletter opt-in.Dashboard configuration:
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.
Example 3: Button updates a user's segment
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.
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.
.png?fit=max&auto=format&n=_oxDKcVQxojISfsr&q=85&s=ef4e6f5671de21a6630bdf17f7ea7abc){kind=icon}
