Documentation

Button

Suggest Edits

📘

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.

What are the benefits of integrating MetaRouter with Button?

  • Server-side event delivery ensures secure purchase tracking without relying on client-side tags.
  • Flexible data mapping to structure order details, product attributes, and transaction values in Button's required format.

Capabilities and Considerations

  • 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 accurate transaction reporting.
  • Identifies whether the transaction happened in an app or webview.
  • Maps product details (SKU, category, price, etc.) into Button's required format.

Limitations

  • This integration currently supports mobile web events. It does not support mobile app events.

Getting Started - From Your Button Account

Getting Started - From Your MetaRouter Account

Adding a Button integration.

From the integration library, add a Button integration. Then, fill out the Connection Parameters:

Connection ParameterDescription
API_KEYButton uses your API key for API endpoint access.

Adding a Button Sync

To gather the btn_ref value you must add a Button sync.

  1. From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select “Build AJS File.”
  2. In the Identity Syncs section, select the Button sync.
  3. Fill out the following fields:
    1. Consent Type
    2. Source Token Lifetime - Defines how long the synced identifier will remain in the first-party ID graph. Once the lifetime is reached, or whenever MetaRouter no longer detects the identifier, another sync will be performed to pull a new value.
  4. Scroll down and click the Save and Build File button.
  5. Deploy your AJS file to propagate changes to your web property.

Event Mappings

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.

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 KeyDescriptionExpected 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 traits.email or context.traits.email using SHA-256.
customer.device_id
Recommended		String: Device ID (IDFA/AAID) used for tracking the user’s device.Expression: Uses context.device.advertisingId if ad tracking is enabled.
purchase_date
Required		ISO 8601 date string: The time when the purchase was made.Expression: Uses timestamp, originalTimestamp, or sentAt.
partner_order_channelString: Indicates whether the transaction occurred via an app or webview.Expression: Returns "app" if context.app.name exists, otherwise "webview".
total
Required		Integer: Total value of the order in cents (excluding taxes and fees).Expression: Multiplies each product’s price by quantity, then converts to cents.
currency
Required		String: Three-letter ISO currency code (e.g., USD).properties.currency
order_id
Required		String: Unique order identifier assigned by the merchant.properties.order_id
customer_order_idString: Customer-facing order ID.properties.order_id
line_items
Required		Array: List of purchased items with attributes like SKU, price, and quantity.Expression: Maps products array into required Button format.

Event Specific

Order Completed

Output KeyDescriptionExpected Input
total
Required		Integer: Total value of the order in cents (excluding taxes and fees).Expression: Multiplies each product’s price by quantity, then converts to cents.
currency
Required		String: Three-letter ISO currency code (e.g., USD).properties.currency
order_id
Required		String: Unique order identifier assigned by the merchant.properties.order_id
customer_order_idString: Customer-facing order ID.properties.order_id
line_items
Required		Array: List of purchased items with attributes like SKU, price, and quantity.Expression: Maps products array into required Button format, extracting product_id, price, quantity, sku, category, name, and other attributes.

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.

AttributeExampleSync Injector Required?
btn_refRequiredsrctok-abcdef0123456789Yes
customer.id Required130161d0-8fee-4167-aa4d-d151eed27c6bNo
customer.email_sha256 Recommended9561c3516f02f51fa0ac38e9c81df0157ebab90d59ebde6fcf0f128f06a66423No
customer.device_id RecommendedAEBE52E7-03EE-455A-B3C4-E57283966239No

Additional Button Documentation

Report an Order API

Authentication

Integration Change Log

Updated 23 days ago