Button

Send conversion and commerce event data to Button server-to-server for mobile commerce attribution, partnership optimisation, and revenue tracking.

Why route Button through Datafly Signal

Conversions survive ad blockers and tracking prevention. A browser tag served from an advertising domain is blocked outright for part of your traffic, and Safari’s ITP shortens the cookies it can set. Signal sends the event from your own server, so the conversions Button optimises against are not filtered by the browser.
Client IP and user agent are carried in the payload. Both are taken from the original visitor request rather than your server, which is what Button needs to attribute the event to the right session.
One consent decision governs every destination. Button is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
No vendor tag on the page. Removing it removes its page weight and its independent access to your visitors.

Prerequisites

Complete these steps in the Button dashboard before configuring Signal.

Create a Button account

Create an application

Navigate to Settings > Applications and click Create Application. Enter your app name and platform details. Each application represents a distinct property (website or app) that sends events to Button.

Find your Application ID

After creating the application, your Application ID is displayed on the application detail page. It typically follows the format app-xxxxxxxxxxxxxxxx.

Find your API key

Go to Settings > API Keys in the Button Dashboard. Copy your API Key. This key authenticates all server-to-server event delivery from Signal.

Configure your commerce events

In the Button Dashboard, define which commerce events (e.g. purchases, add-to-cart) you want to track. This ensures Button correctly processes the events Signal delivers.

Configuration

Field	Type	Required	Description
`application_id`	string	Yes	Your Button application ID from Settings > Applications.
`api_key`	secret	Yes	Your Button API key from Settings > API Keys.

Signal Setup

Quick Setup

Navigate to Integrations in the sidebar.
Open the Integration Library tab.
Find Button or filter by Attribution.
Click Install, select a variant if available, and fill in the required fields.
Click Install Integration to create the integration with a ready-to-use default blueprint.

API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/button/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Button",
    "variant": "default",
    "config": {
      "application_id": "app-abc123def456",
      "api_key": "your_api_key"
    },
    "delivery_mode": "server_side"
  }'

API endpoint

POST https://api.usebutton.com/v1/order

Allow egress to api.usebutton.com from the network your delivery workers run on.

Event Mapping

The Retail variant maps the following Datafly events to Button commerce events:

Datafly Event	Button Event	Notes
`Product Added`	`add_to_cart`	Cart-stage event
`Order Completed`	`purchase`	Requires `order_id`, `total`, `currency`, line items
Custom events	Passed through	Add the Button event type in the blueprint event map

Identity

The default blueprint forwards the following identifiers to Button:

Source	Button field
`user_id`	`customer_id`
`context.ip`	`ip_address`
`context.user_agent`	`user_agent`

Button’s btn_ref referral token is the primary attribution key. Capture it from inbound URLs on your landing page and pass it via Datafly.js so it reaches Button with each conversion.

Default consent category: advertising. Button commerce attribution is a paid-partnership destination — gate behind advertising consent in your CMP.

Button uses a btn_ref attribution token to link conversions to the originating partner. Ensure your site captures the Button referral token from inbound URLs and includes it in Signal events.

Verify it’s working

Generate a test referral through a Button partner link to obtain a valid btn_ref token.
Trigger a test conversion on your site that fires a Datafly event.
In the Signal Management UI, open your Button integration and watch the Live Events stream.
In the Button Dashboard, navigate to Reports > Orders and verify your test conversion appears.
Confirm 200 responses in Signal’s Live Events log.

Troubleshooting

Symptom	Cause	Resolution
`401 Unauthorized`	Invalid API key	Verify `api_key` in Button Settings > API Keys and update Signal.
`400 Bad Request`	Missing required fields	Ensure `order_id` and `total` are mapped in the blueprint.
Conversions not attributed	Missing `btn_ref` token	Capture the Button referral token from the landing page URL and include it in events.
Wrong application	Incorrect `application_id`	Verify the application ID matches the property you are tracking.

Visit Button documentation for full API reference and credential setup instructions.

Blueprint

The Button blueprint version is 0.1.0. It ships with a Retail variant covering add_to_cart and purchase commerce events.