Convert

Server-side experiment data delivery to Convert for A/B testing, multivariate experiments, and personalisation goal tracking.

Why route Convert through Datafly Signal

Your numbers stop depending on what the browser allows. Client-side analytics loses every visit where the tag is blocked or the page unloads early. Signal delivers from the server, so Convert receives the complete event stream.
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 Convert needs to attribute the event to the right session.
Delivery is batched, rate-limited, and retried. Signal buffers to Kafka, respects the Convert rate limit, and retries on 429 or transient failure rather than dropping the event.
Token lifecycle is handled for you. Signal obtains and refreshes the OAuth credentials Convert requires, so nothing expires quietly in the middle of a campaign.
One consent decision governs every destination. Convert is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.

Prerequisites

Before configuring Convert in Datafly Signal, you need a Convert.com account, a project, and your API key.

Step 1: Create a Convert Account

Go to convert.com and click Start Free Trial or sign in.
Complete the registration process and verify your email.
Once signed in, you will land on the Convert dashboard.

Step 2: Create a Project

In the Convert dashboard, click New Project.
Enter your website URL and give the project a name (e.g. “My Website - Production”).
Click Create.
On the project settings page, note the Project ID displayed in the URL or in the project details.

Each Convert project is associated with a single website domain. If you have multiple domains, create a separate project for each.

Step 3: Find Your Account ID

Click your profile icon in the top-right corner and go to Account Settings.
Your Account ID is displayed on the account overview page.
Copy this value.

Step 4: Generate an API Key

In Account Settings, navigate to the API Keys section.
Click Generate New API Key.
Give the key a descriptive name (e.g. “Datafly Signal Integration”).
Copy the API key immediately — it will not be shown again.

⚠️

Store the API key securely. If you lose it, you will need to generate a new one. The API key provides full access to the Convert REST API for your account.

API Endpoint

POST https://api.convert.com/v1/projects/{project_id}/goals

Goal conversion events are sent as JSON payloads to the Convert REST API. Authentication is handled via the API key in the request headers.

Configuration

Field	Type	Required	Description
`account_id`	string	Yes	Your Convert account ID. Found in Account Settings.
`project_id`	string	Yes	The Convert project ID to receive experiment events. Found in the project settings or URL.
`api_key`	secret	Yes	Convert REST API key for server-side authentication. Generated in Account Settings > API Keys.

Management UI Setup

Go to Integrations in the sidebar.
Open the Integration Library tab.
Find Convert or filter by Analytics.
Click Install and fill in the required fields:
- Enter your Account ID from Step 3.
- Enter your Project ID from Step 2.
- Paste your API Key from Step 4.
Click Install Integration to create the integration with a ready-to-use default blueprint.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integration-catalog/convert/install \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Convert",
    "variant": "default",
    "config": {
      "account_id": "10001234",
      "project_id": "20005678",
      "api_key": "your_api_key"
    },
    "delivery_mode": "server_side"
  }'

Event Mapping

The Retail variant maps the following Datafly events to Convert event names:

Datafly Event	Convert Event	Notes
`page`	`page_view`	Triggers page-based goals matching the URL
`Product Viewed`	`product_viewed`	Product details as event properties
`Order Completed`	`purchase`	Revenue value and transaction data sent as goal conversion
Custom events	passed through	Events matched to Convert goals by name

Identity

The default blueprint forwards the following identifiers:

Source	Convert field
`user_id`	`user_id`
`anonymous_id`	`anonymous_id`
`context.ip`	`ip`
`context.user_agent`	`user_agent`
`context.locale`	`locale`

Default consent category: analytics.

Convert goals must be created in the Convert dashboard before they can receive conversions from Datafly Signal. The event name or properties are used to match incoming events to the correct goal.

Verify it’s working

In the Signal Management UI, open your Convert integration and watch the Live Events stream as you trigger events on your site.
Confirm 200 responses from the Convert REST API.
In Convert, open an active experiment and check the Results tab — conversions appear within minutes.

Testing

Once your integration is active and events are flowing, verify in Convert:

In the Convert dashboard, go to your project and open an active experiment.
Click the Results tab to see conversion data.
Use the Real-Time view (if available) to verify events are arriving.
Check the Goal details to see individual conversion counts and revenue.
In Datafly Signal, check the Delivery Logs for the Convert integration to verify successful API responses.

Convert may take a few minutes to process incoming goal conversions. If you do not see data immediately, wait 5-10 minutes and refresh the results page.

Troubleshooting

Symptom	Cause	Fix
`401` authentication error	Invalid API key	Generate a new API key in Account Settings > API Keys
`404` project not found	Incorrect project ID	Verify the project ID matches the value in your Convert dashboard URL
No conversions recorded	Goal not matched	Ensure the goal exists in Convert and the event name or properties match the goal trigger
Revenue not appearing	Revenue goal not configured	Create a revenue goal in Convert and map the `Order Completed` event to it
`400` bad request	Malformed request payload	Check Datafly Signal delivery logs for the full error message
Events sent but experiment shows no data	Visitor not bucketed	Visitors must be assigned to an experiment variation before conversions are counted

Delivery

Events are delivered server-side from your Datafly Signal infrastructure directly to the Convert REST API. No client-side Convert scripts are loaded for this integration.

Visit the Convert API documentation for full API reference and advanced configuration options.

Blueprint

The Convert blueprint version is 0.1.0. It ships with a Retail variant covering pages, product views, and purchase conversions.