X Ads Web Conversions

Datafly Signal delivers web conversion events to X (formerly Twitter) server-to-server using the X Ads Conversions API. This enables accurate conversion tracking for X ad campaigns without depending on the X Pixel client-side script.

Prerequisites

Before configuring X Ads Web Conversions in Signal, you need an X Ads account, a web pixel, conversion events, and an API access token. Follow the steps below to set everything up.

Step 1: Create an X Ads Account

If you don’t already have one:

Go to ads.x.com and sign in with your X account.
Enter your country, time zone, and billing information.
Complete the account setup. Note your Ads Account ID from the account settings.

Step 2: Create a Web Tag (Pixel)

The X Pixel (Universal Website Tag) is required to associate server-side conversions with your ad account.

In X Ads Manager, go to Tools > Events Manager.
Click Add Event Source > Install with Pixel.
Name your pixel (e.g. “Datafly Signal”).
Click Create. Note the Pixel ID (also called Universal Website Tag ID).

You do not need to install the X Pixel JavaScript on your website. Signal delivers events server-side. However, the pixel must exist in your account as it serves as the event source for conversion tracking.

Step 3: Set Up Conversion Events

Conversion events define the actions you want to track and optimise for.

In Events Manager, click on your pixel.
Click Add Events or Create Custom Event.
For each conversion action (e.g. Purchase, Lead, Sign-up):
- Enter an event name.
- Select the event type (e.g. Purchase, Lead, Sign Up, Page View, Download, Custom).
- Configure attribution settings (default: 1-day post-view, 30-day post-click).
Note the Event ID for each conversion event you create.
Click Save.

⚠️

Each conversion action requires a separate event configured in Events Manager. You will map Datafly events to these X event IDs in the integration configuration.

Step 4: Apply for Developer Access

The X Ads Conversions API requires developer access with Ads API permissions.

Go to developer.x.com and sign in with the X account linked to your Ads account.
If you don’t have a developer account, click Sign up and complete the application.
Select a developer plan that includes Ads API access (Pro or Enterprise tier).
Describe your use case (server-side conversion tracking).
Wait for approval. This can take 1-5 business days.

Ads API access is not included in the Free tier. You need at least the Pro tier, or an approved Ads API application. Contact your X Ads account representative if you need expedited access.

Step 5: Generate an API Access Token

Once you have developer access with Ads API permissions:

In the X Developer Portal, go to your project/app settings.
Navigate to Keys and Tokens.
Generate or regenerate your API Key and Secret (also called Consumer Key and Secret).
Generate an Access Token and Secret with read and write permissions.
Note all four values:
- API Key (Consumer Key)
- API Secret (Consumer Secret)
- Access Token
- Access Token Secret

Alternatively, use the OAuth 2.0 flow for app-level authentication:

In your app settings, go to OAuth 2.0 settings.
Set the redirect URI and note the Client ID.

Initiate an OAuth 2.0 flow with the ads_management scope:

https://twitter.com/i/oauth2/authorize?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=ads_management%20offline.access&state=STATE&code_challenge=CHALLENGE&code_challenge_method=S256

Exchange the authorization code for an access token:

curl -X POST https://api.x.com/2/oauth2/token \
  -d "grant_type=authorization_code&code=AUTH_CODE&redirect_uri=YOUR_REDIRECT_URI&client_id=YOUR_CLIENT_ID&code_verifier=YOUR_VERIFIER"

Note the access_token and refresh_token from the response.

⚠️

Store all tokens securely. OAuth 2.0 access tokens expire after 2 hours. Configure a refresh token for automatic renewal. OAuth 1.0a tokens (Access Token and Secret) do not expire unless revoked.

Configure in Signal

Now that you have your Pixel ID, event IDs, and access token, configure the integration in Signal.

Configuration Fields

Field	Required	Description
`pixel_id`	Yes	Your X Pixel ID (Universal Website Tag ID). Found in X Ads Manager > Events Manager.
`access_token`	Yes	API access token with Ads API (ads_management) permissions.
`event_id`	No	Default conversion event ID. If set, all events are sent to this event. If not set, events are routed based on event type mapping.
`refresh_token`	No	OAuth 2.0 refresh token for automatic token renewal.

Management UI Setup

Go to Integrations > Add Integration > X Ads Web Conversions.
Enter your pixel_id and access_token.
Optionally enter a default event_id or configure per-event mapping.
Select consent categories (typically advertising).
Click Save.

Management API Setup

curl -X POST http://localhost:8084/v1/admin/integrations \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "src_abc123",
    "vendor": "x_ads",
    "name": "X Ads Web Conversions",
    "enabled": true,
    "config": {
      "pixel_id": "abcde",
      "access_token": "your_access_token",
      "event_id": "tw-xxxxx-yyyyy"
    },
    "consent_categories": ["advertising"]
  }'

API Endpoint

POST https://ads-api.x.com/12/measurement/conversions/{pixel_id}

Events are sent as JSON with authentication via the Authorization: Bearer header.

Identity Signals

X uses multiple identity signals to match server events to ad interactions and user profiles.

Automatic Signals

These are sent automatically by Signal — no configuration needed:

Signal	Field	Description
`twclid`	`click_id`	X click ID. Automatically captured from the `twclid` URL parameter when a user clicks an X ad. This is the primary attribution signal.
`ip_address`	Forwarded from original request	Visitor’s IP address.
`user_agent`	Forwarded from original request	Visitor’s User-Agent string.

When a user clicks an X ad, the twclid parameter is appended to the landing page URL:

https://example.com/landing?twclid=abc123def456ghi789

Datafly.js automatically captures the twclid from the URL and persists it as a first-party cookie for the duration of the attribution window.

⚠️

The twclid parameter is essential for click-through conversion attribution. Ensure your X ad campaigns have click tracking enabled. Without it, conversions can only be attributed via hashed email matching.

User-Provided Signals (Hashed)

When user data is available via _df.identify(), the following fields are SHA-256 hashed before sending to X:

Signal	Hashing	Description
`hashed_email`	SHA-256, lowercase, trimmed	User’s email address
`hashed_phone`	SHA-256, E.164 format	User’s phone number

All PII hashing is performed server-side by the Delivery Worker. Raw PII never leaves your infrastructure. X uses hashed email and phone as supplementary matching signals to improve conversion attribution.

Event Mapping

Datafly Event	X Ads Event	Notes
`page` (page view)	`PageView`	Sent for every page view
`Order Completed` / `Product Purchased`	`Purchase`	Requires `value`, `currency`
`Product Added`	`AddToCart`	Includes item details
`Checkout Started`	`Checkout`	Includes `value`, `currency`
`Product Viewed`	`ViewContent`	Includes item details
`Lead Generated`	`Lead`	Lead form submission
`Signed Up`	`SignUp`	User registration
`Product Added to Wishlist`	`AddToWishlist`	Includes item details
`app_install`	`Download`	App install event
Custom events	Mapped to custom event IDs	Configure via `event_id` mapping

Example: Purchase Event

Datafly.js call:

_df.track("Order Completed", {
  order_id: "ORD-001",
  total: 129.99,
  currency: "USD",
  products: [
    { product_id: "SKU-A", name: "Widget", price: 49.99, quantity: 2 },
    { product_id: "SKU-B", name: "Gadget", price: 30.01, quantity: 1 }
  ]
});

X Ads Conversions API payload sent by Signal:

{
  "conversions": [
    {
      "conversion_time": "2024-01-29T12:00:00Z",
      "event_id": "tw-xxxxx-yyyyy",
      "identifiers": [
        {
          "twclid": "abc123def456ghi789"
        },
        {
          "hashed_email": "836f82db99121b3481011f16b49dfa5fbc714a0d1b1b9f784a1ebbbf5b39577f"
        }
      ],
      "conversion_id": "evt_abc123def456",
      "description": "Order Completed",
      "number_items": 3,
      "price_currency": "USD",
      "value": "129.99",
      "contents": [
        {
          "content_id": "SKU-A",
          "content_name": "Widget",
          "content_price": "49.99",
          "num_items": "2"
        },
        {
          "content_id": "SKU-B",
          "content_name": "Gadget",
          "content_price": "30.01",
          "num_items": "1"
        }
      ]
    }
  ]
}

Testing Your Integration

Step 1: Send Test Events

Enable the integration in Signal and trigger events on your website.
Check the Signal event debugger to confirm events are being delivered.
Verify the delivery status shows successful responses from the X Ads API.

Step 2: Verify in Events Manager

In X Ads Manager, go to Tools > Events Manager.
Select your pixel. You should see events arriving under the Activity tab.
Click on individual events to inspect the payload.
Allow up to 1 hour for events to appear in the dashboard.

Step 3: Check Attribution

In X Ads Manager, go to your campaign reporting.
Add the Conversions column to verify events are being attributed to ad clicks.
Check that conversion values and event types match your expectations.

X may take up to 1 hour to reflect conversion events in the Ads Manager dashboard. If events are not appearing after 2 hours, check the troubleshooting section below.

Troubleshooting

Problem	Solution
Events not appearing in Events Manager	Verify the `pixel_id` is correct. Check the access token has Ads API (ads_management) permissions.
`401 Unauthorized` errors	The access token has expired (2-hour lifetime for OAuth 2.0). Configure a refresh token for automatic renewal, or use OAuth 1.0a tokens which do not expire.
`403 Forbidden` errors	Your developer account may not have Ads API access. Check your developer tier or contact your X Ads representative.
`twclid` not being captured	Ensure click tracking is enabled on your X ad campaigns. Verify Datafly.js is loaded on the landing page.
Conversions not attributed to campaigns	Ensure `twclid` is being captured and sent. Without it, attribution relies on hashed email matching which has lower match rates. Check the attribution window settings on your conversion events.
Duplicate conversions	Ensure unique `conversion_id` values are sent with each event. X deduplicates based on this field.
Revenue not appearing	Verify that `total` or `value` and `currency` are included in event properties. Check the conversion event in Events Manager is configured to accept revenue data.
Rate limit errors (`429`)	Reduce `rate_limit_rps`. The X Ads API has per-app rate limits. Check the `x-rate-limit-remaining` header in responses.

Rate Limits

Setting	Default
`rate_limit_rps`	50
`rate_limit_burst`	100

X Ads API rate limits vary by endpoint and developer tier. The defaults are set conservatively. Monitor 429 responses and adjust as needed.

For full API documentation, see X Ads Conversions API documentation.

VideoAmp Xandr