Button
This integration is currently in beta. Contact your MetaRouter support team to get started.
What Is Button?
Button is a mobile commerce platform that enables seamless in-app purchasing experiences by connecting brands, publishers, and consumers. It provides a deep-linking and monetization infrastructure that facilitates transactions while ensuring a smooth user journey across apps and mobile web. Button's technology helps brands drive conversions, optimize performance marketing, and track user engagement with deterministic attribution. By integrating with Button, businesses can enhance their mobile commerce strategy, leveraging server-side data to improve targeting, personalization, and measurement.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Mobile Browser
Event Scope: Conversion Events Only
Capabilities
- Sends order completion data to Button's API to track purchases.
- Captures and hashes customer email for secure identification.
- Collects device and user identifiers (e.g.,
btn_ref, device ID) for attribution. - Converts purchase amounts into cents for transaction reporting.
- Identifies whether the transaction happened in an app or webview.
- Maps product details (SKU, category, price, etc.) into Button's required format.
Considerations
- Authentication uses a Basic auth token derived from your Button API key.
- The hashed email string cannot be empty.
- The
btn_refattribution token is collected via the sync and required on every event.
Limitations
- This integration currently supports mobile web events. It does not support mobile app events.
Identity Sync
- Sync Available: Yes
- Required for Starter Kit: Yes
- Prerequisites: Button API key
- Documentation: See Additional Button Sync Documentation
Sync Details
- Captures the
btn_refattribution token used for tracking and attribution. - Required by Button to associate conversions with prior activity.
- Without this sync, conversions may not be accurately attributed in reporting.
Starter Kit Setup Guide
1. Deploy the Button Sync
- To collect the sync values (e.g.,
btn_ref), you must implement a Button ID sync. Refer to the following documentation to complete the setup: Button - ID Sync Guide.
2. Gather Credentials
- Follow Button's authentication documentation to obtain an API Key.
3. Add a Button Integration
- From the integration library, add a Button integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|---|
API_KEY | Button uses your API key for API endpoint access. |
4. Configure Event Mapping
- MetaRouter provides all of the event mappings that Button integrations typically require. You may add custom events, parameters, or mappings in accordance with Button's API documentation.
5. Deploy to Pipeline
- In the Pipelines tab, add your Button integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
Event Mappings
Global
Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.
| Output Key | Description | Expected Input |
|---|---|---|
btn_ref Required | String: The Button attribution token used for tracking and attribution. | context.providers.button.btn_ref |
customer.id Required | String: Unique identifier for the customer in the merchant's system. | anonymousId |
customer.email_sha256 Recommended | String: SHA-256 hashed email used for customer identification. | Expression – hashes trimmed, lowercased traits.email when present |
customer.device_id Recommended | String: Device ID (IDFA/AAID) used for tracking the user's device. | Expression – returns context.device.advertisingId or device ID when ad tracking is enabled |
purchase_date Required | ISO 8601 date string: The time when the purchase was made. | Expression – returns timestamp, originalTimestamp, or sentAt |
partner_order_channel | String: Indicates whether the transaction occurred via an app or webview. | Expression – returns app when app/device/OS context exists, otherwise webview |
Event Specific
Order Completed
| Output Key | Description | Expected Input |
|---|---|---|
total Required | Integer: Total value of the order in cents (excluding taxes and fees). | Expression – sums each product's price × quantity, converted to cents |
currency Required | String: Three-letter ISO currency code (e.g., USD). | properties.currency (uppercased, default USD) |
order_id Required | String: Unique order identifier assigned by the merchant. | properties.order_id |
customer_order_id | String: Customer-facing order ID. | properties.order_id |
line_items Required | Array: Builds the Button line-item list from properties.products, mapping each product's identifier, total (in cents), quantity, SKU, category, and description, plus an attributes object carrying any of brand, name, variant, coupon, position, URL, and image URL that are present. | Expression – auto-generates the line-item array from properties.products |
Required & Recommended Identifiers
These identifiers must be mapped to Button in order for successful user matching to occur. Without these IDs, any events sent to Button may not be accurately reflected in reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.
| Attribute | Example | Sync Injector Required? |
|---|---|---|
btn_ref Required | srctok-abcdef0123456789 | Yes |
customer.id Required | 130161d0-8fee-4167-aa4d-d151eed27c6b | No |
customer.email_sha256 Recommended | 9561c3516f02f51fa0ac38e9c81df0157ebab90d59ebde6fcf0f128f06a66423 | No |
customer.device_id Recommended | AEBE52E7-03EE-455A-B3C4-E57283966239 | No |
Integration Validation
- Coordinate with your Button representative to confirm that order events are being received and processed correctly on their backend.
Additional Button Documentation
Updated 13 days ago