X Ads is a digital advertising platform that allows businesses and individuals to promote their tweets, accounts, and trends to a broad audience. Advertisers can target users based on various factors such as demographics, interests, keywords, and behaviors, ensuring their messages reach the most relevant audience. The platform offers different ad formats, including promoted tweets, promoted accounts, and promoted trends, each designed to engage users in unique ways. Additionally, X Ads provides analytics and insights to help advertisers measure the performance and effectiveness of their campaigns.
X Ads - Web Conversions is a server-side integration that allows advertisers to directly send web conversion events from their servers to X Ads. This integration allows for tracking and measuring the effectiveness of ad campaigns by capturing conversions, such as purchases, sign-ups, or other valuable actions, that occur in web environments. By using the X Ads Conversions API, advertisers can ensure more reliable data collection, better attribution, and enhanced optimization for their campaigns, particularly in environments where traditional tracking methods, like cookies, may be limited or less effective.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web
Event Scope: Full-Funnel Events
- Conversion tracking and optimization: Accurately track conversions like purchases and other key actions by sending conversion data directly from the server.
- Advanced targeting: Custom audiences are available, as user identifiers (e.g., click ID, hashed emails, and phone numbers) are sent to X Ads using the Conversions API. This ensures that audience segmentation and retargeting can be achieved without relying on client-side data collection methods.
- Real-time analytics and reporting: You can still access real-time analytics on conversion events sent via the integration, and these will be reflected in the X Ads Manager's conversion reports as well as Events Manager.
- Enriched Audience Insights: X Ads uses the data captured from conversions and ad interactions to compile audience insights such as demographics (age, gender, location) and behaviors (interests, activities). While this integration does not directly pass demographic data, it enables X to combine the server-side conversion events with the demographic and behavioral data already associated with the users in its ecosystem. This allows advertisers to continue optimizing campaigns based on audience insights when using server-side tracking.
- Flexible bid and budget control: Conversion events tracked through the API can still be used for optimizing bidding strategies, such as CPA (Cost Per Action) optimization, within the X Ads platform.
- Access Level Consideration: When planning your integration, determine your API Access Level based on the estimated number of event POST requests per month. The free version of the API supports up to 1,500 POST requests per month. For more details, refer to the X Ads API - API Access Levels documentation.
- Granularity of User Interactions: While server-side tracking captures key events such as page visits and conversions, capturing highly detailed metrics like scroll depth or time spent on page can be more complex. These metrics require a deeper level of real-time user interaction data that may not be fully addressed by server-side methods.
- Impression Tracking and CTR Calculation: The server-side integration may not capture impression data, which is necessary for calculating metrics like Click-Through Rate (CTR).
- Web Conversions Only: This server-side integration is designed to track and report web conversions exclusively. It does not support conversions from mobile apps, meaning app-based user interactions and conversions are not captured through this method. To track app conversions, a separate integration using app-specific tracking methods is required. Please reach out to your MetaRouter customer team for support if you need to track app events.
- Captures the
twclid (X Ads click ID) value used for conversion attribution.
- Required by X Ads to associate conversions with prior ad clicks.
- Without this sync, conversions may rely on other identifiers (such as hashed email) for matching.
- To collect the sync values (e.g.,
twclid), you must implement an X Ads ID sync. Refer to the following documentation to complete the setup: X Ads - ID Sync Guide.
- Create a developer account in the X Developer Portal and create an X Ads project and app. Determine your Access Level based on the number of event POST requests you expect per month (the free version supports up to 1,500 per month).
- From the app's Overview tab, copy the Consumer Key (API Key) and Consumer Secret (API Secret Key).
- In the Authentication Tokens section, generate and copy the Access Token and Token Secret.
- Obtain your Pixel ID from X Ads Manager > Tools > Events Manager.
- Set the API Version to the current version of the X Ads API you are using (e.g.,
12).
- Locate Event IDs: In X Ads Manager > Tools > Events Manager, the Event ID for each event is displayed below the event's title. You will assign an Event ID to each event in the playbook.
- From the integration library, add an X Ads - Web Conversions integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
API_VERSION | The version of the X Ads API you are using (e.g., 12). |
PIXEL_ID | The unique identifier for your X Ads pixel. |
CONSUMER_KEY | The API key from your X Ads developer account. |
CONSUMER_SECRET | The API secret key from your X Ads developer account. |
ACCESS_TOKEN | The OAuth token that grants access to X Ads APIs. |
TOKEN_SECRET | The OAuth token secret used in combination with the access token. |
- MetaRouter provides all of the event mappings that X Ads integrations typically require. You may add custom events, parameters, or mappings in accordance with X Ads' API documentation.
- In the Pipelines tab, add your X Ads integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
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 |
|---|
conversion_id Required | String: A unique identifier for each conversion event. | messageId |
conversion_time Required | Timestamp: The time the conversion event occurred. | timestamp |
identifiers Required | Array: Builds the list of available match identifiers — hashed email, hashed phone number, twclid, and the IP address and user agent. | Expression – builds identifiers from traits, provider context, and context |
number_items | Integer: The number of items involved in the conversion. | Expression – sums product quantities, or returns 1 for a single SKU |
price_currency Required | String: The currency of the conversion value (e.g., USD). | Expression – uppercases properties.currency |
value Required | String: The total value of the conversion, formatted to 2 decimal places. | Expression – sums price × quantity across products or a single SKU |
description | String: A description of the event type. | Expression – returns input.event for track events, otherwise input.type |
contents | Array: Builds a list of content objects per product with content_id (SKU), content_name, content_price, content_type (category), and num_items. | Expression – maps properties.products (or a single product) |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
search_string | String: The search string used for the event. | properties.query |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id Required | String: A unique event identifier. | Enrichment – 'ADD_EVENT_ID_HERE' |
| Output Key | Description | Expected Input |
|---|
event_id | String: A catch-all event identifier used when tracking broad categories of events where specific event types might not be predefined. | Enrichment – 'ADD_CATCH_ALL_EVENT_ID_HERE' |
These identifiers must be mapped to X Ads in order for successful user matching to occur. Without these IDs, any events sent to X Ads 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.
X Ads currently needs at least one identifier to be passed such as Click ID (twclid), email address, or phone number. If using IP address or user agent, a second identifier must be sent for proper conversion matching. Passing more identifiers will yield a higher conversion matching rate.
| Attribute | Example | Sync Injector Required? |
|---|
twclid Recommended | 12345abcde | Yes |
hashed_email Recommended | e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 | No |
hashed_phone_number Recommended | a3dcb4d229de6fde0db5686dee47145d | No |
ip_address Recommended | 192.168.1.1 | No |
user_agent Recommended | Mozilla/5.0 (Macintosh; Intel Mac OS X) | No |
Coordinate with your X Ads representative, or use the X Ads Manager (Events Manager) dashboard, to confirm that events are being received and processed correctly on their backend.
