X Ads Integrations

Overview

X Ads (formerly Twitter Ads) integrates with analytics platforms, attribution partners, CRM systems, and marketing automation tools to provide comprehensive campaign measurement and audience activation. This guide covers native integrations, third-party connections, and API-based custom implementations.

Native X Ads Integrations

X Pixel

The X Pixel enables website conversion tracking and audience building:

<!-- X Pixel Base Code -->
<script>
!function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments);
},s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='https://static.ads-twitter.com/uwt.js',
a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script');
twq('config','YOUR_PIXEL_ID');
</script>

Standard Events:

// Page view (automatic with base code)
twq('track', 'PageView');

// Purchase event
twq('track', 'Purchase', {
  value: 99.99,
  currency: 'USD',
  num_items: 2,
  order_id: 'ORD-12345'
});

// Lead generation
twq('track', 'Lead', {
  email_address: 'hashed_email',
  phone_number: 'hashed_phone'
});

// Add to cart
twq('track', 'AddToCart', {
  value: 49.99,
  currency: 'USD',
  content_ids: ['SKU-123', 'SKU-456']
});

// Content view
twq('track', 'ViewContent', {
  content_id: 'product-123',
  content_type: 'product',
  content_name: 'Wireless Headphones'
});

Conversions API (CAPI)

Server-side conversion tracking for improved accuracy:

// Node.js implementation
const axios = require('axios');

async function sendConversion(eventData) {
  const response = await axios.post(
    'https://ads-api.twitter.com/12/measurement/conversions/YOUR_PIXEL_ID',
    {
      conversions: [{
        conversion_time: new Date().toISOString(),
        event_id: eventData.eventId,
        identifiers: [{
          hashed_email: hashEmail(eventData.email),
          hashed_phone_number: hashPhone(eventData.phone)
        }],
        conversion_id: eventData.orderId,
        contents: eventData.items.map(item => ({
          content_id: item.sku,
          content_price: item.price,
          num_items: item.quantity
        })),
        value: eventData.total,
        currency: 'USD'
      }]
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.X_ADS_ACCESS_TOKEN}`,
        'Content-Type': 'application/json'
      }
    }
  );

  return response.data;
}

// SHA-256 hashing for PII
function hashEmail(email) {
  const crypto = require('crypto');
  return crypto.createHash('sha256')
    .update(email.toLowerCase().trim())
    .digest('hex');
}

Python Implementation:

import requests
import hashlib
from datetime import datetime

def send_x_conversion(event_data, access_token, pixel_id):
    url = f'https://ads-api.twitter.com/12/measurement/conversions/{pixel_id}'

    payload = {
        'conversions': [{
            'conversion_time': datetime.utcnow().isoformat() + 'Z',
            'event_id': event_data['event_id'],
            'identifiers': [{
                'hashed_email': hash_email(event_data['email'])
            }],
            'conversion_id': event_data['order_id'],
            'value': event_data['total'],
            'currency': 'USD'
        }]
    }

    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(url, json=payload, headers=headers)
    return response.json()

def hash_email(email):
    return hashlib.sha256(email.lower().strip().encode()).hexdigest()

Analytics Platform Integrations

Google Analytics 4

Connect X Ads with GA4 using UTM parameters:

Campaign URL Builder:

https://example.com/landing?
  utm_source=twitter
  &utm_medium=paid_social
  &utm_campaign=spring_sale_2024
  &utm_content=video_ad_v1
  &utm_term=tech_audience

GA4 Integration Setup:

1. Enable auto-tagging in X Ads Manager
2. Configure UTM parameters in ad settings
3. Create GA4 audience based on X Ads traffic
4. Import GA4 conversions for bidding optimization

Cross-Platform Attribution:

// Track X Ads click with GA4
gtag('event', 'ad_click', {
  'source': 'twitter',
  'campaign': 'spring_sale_2024',
  'ad_id': getUrlParam('twclid')
});

Adobe Analytics

Integration Methods:

1. Classification Import: Import X Ads campaign data
2. Data Insertion API: Server-side event tracking
3. Analytics for Advertising: Native Adobe partnership

Processing Rules Setup:

Mixpanel

Track X Ads conversions in Mixpanel:

// Capture X click ID
const twclid = new URLSearchParams(window.location.search).get('twclid');

if (twclid) {
  mixpanel.register({
    'X Click ID': twclid,
    'Acquisition Source': 'X Ads'
  });
}

// Track conversion
mixpanel.track('Purchase', {
  'X Click ID': twclid,
  'Revenue': 99.99,
  'Campaign': 'spring_sale'
});

Amplitude

// Set X Ads user properties
amplitude.setUserProperties({
  'acquisition_source': 'x_ads',
  'x_click_id': twclid,
  'campaign': utm_campaign
});

// Track conversion event
amplitude.logEvent('purchase_completed', {
  revenue: 99.99,
  x_campaign: 'spring_sale_2024'
});

Attribution Partner Integrations

AppsFlyer

Mobile App Attribution Setup:

1. Connect X Ads in AppsFlyer dashboard
2. Configure X Ads API credentials
3. Enable click and impression attribution
4. Set attribution windows

Deep Linking Configuration:

// iOS - AppDelegate
func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    AppsFlyerLib.shared().continue(userActivity, restorationHandler: nil)
    return true
}

Adjust

Integration Steps:

1. Add X Ads as partner in Adjust
2. Configure conversion mapping
3. Enable click ID passback
4. Set up deep linking

Callback Configuration:

https://s2s.adjust.com/callback?
  twitter_click_id={twclid}
  &event_token=abc123
  &revenue=99.99
  &currency=USD

Branch

Universal Links Setup:

{
  "twitter_click_id": "{twclid}",
  "campaign": "{campaign_name}",
  "ad_group": "{ad_group_name}",
  "creative": "{creative_name}"
}

Kochava

1. Enable X Ads network in Kochava
2. Configure postback URLs
3. Map conversion events
4. Enable fraud prevention

Singular

Server-to-Server Configuration:

curl -X POST 'https://s2s.singular.net/api/v1/evt' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -d '{
    "a": "your_app_id",
    "i": "device_id",
    "p": "iOS",
    "n": "purchase",
    "amt": 99.99,
    "cur": "USD",
    "twitter_click_id": "twclid_value"
  }'

CRM Integrations

Salesforce

Offline Conversion Import:

1. Export conversion data from Salesforce
2. Format for X Ads Conversion Import
3. Upload via X Ads Manager or API
4. Match on hashed email/phone

Data Format:

email,phone,conversion_time,conversion_type,value,currency,order_id
sha256_hash,sha256_hash,2024-01-15T10:30:00Z,Purchase,99.99,USD,ORD-123

API Upload:

import requests

def upload_offline_conversions(conversions, access_token, ad_account_id):
    url = f'https://ads-api.twitter.com/12/accounts/{ad_account_id}/offline_conversions'

    headers = {
        'Authorization': f'Bearer {access_token}',
        'Content-Type': 'application/json'
    }

    response = requests.post(url, json={'conversions': conversions}, headers=headers)
    return response.json()

HubSpot

Contact Sync Integration:

1. Export HubSpot contacts matching X Ads audiences
2. Create Tailored Audiences from CRM lists
3. Sync conversion events back to HubSpot
4. Build lookalike audiences from converters

Workflow Automation:

// HubSpot to X Ads audience sync
async function syncToXAudience(contacts, audienceId) {
  const hashedEmails = contacts.map(c =>
    hashEmail(c.email)
  );

  await xAdsApi.updateAudience(audienceId, {
    operation: 'ADD',
    users: hashedEmails.map(email => ({
      hashed_email: email
    }))
  });
}

Marketo

Lead Sync Configuration:

1. Create smart list of qualified leads
2. Export with required fields
3. Hash PII for privacy compliance
4. Upload to X Ads Tailored Audiences

Klaviyo

E-commerce Integration:

// Sync Klaviyo segments to X Ads
const klaviyoSegment = await klaviyo.getSegmentMembers('segment_id');

const xAudienceData = klaviyoSegment.map(member => ({
  hashed_email: hashEmail(member.email),
  hashed_phone: hashPhone(member.phone)
}));

await xAds.updateAudience(audienceId, xAudienceData);

E-commerce Platform Integrations

Shopify

Native Integration:

1. Install X Sales Channel from Shopify App Store
2. Connect X Ads account
3. Enable automatic pixel installation
4. Configure product catalog sync

Manual Pixel Setup:

<!-- theme.liquid -->
{% if first_time_accessed %}
<script>
  twq('track', 'Purchase', {
    value: {{ total_price | money_without_currency }},
    currency: '{{ shop.currency }}',
    num_items: {{ line_items.size }},
    order_id: '{{ order.name }}'
  });
</script>
{% endif %}

WooCommerce

Plugin Installation:

1. Install X Ads for WooCommerce plugin
2. Enter Pixel ID in settings
3. Enable e-commerce tracking
4. Configure event mapping

Custom Implementation:

// functions.php
add_action('woocommerce_thankyou', 'track_x_purchase');
function track_x_purchase($order_id) {
    $order = wc_get_order($order_id);
    ?>
    <script>
    twq('track', 'Purchase', {
        value: <?php echo $order->get_total(); ?>,
        currency: '<?php echo $order->get_currency(); ?>',
        order_id: '<?php echo $order_id; ?>'
    });
    </script>
    <?php
}

Magento

Extension Setup:

1. Install X Ads extension from Magento Marketplace
2. Configure Pixel ID in admin
3. Enable conversion tracking
4. Map product catalog

BigCommerce

Script Manager Integration:

// Add to Script Manager - Order Confirmation
<script>
twq('track', 'Purchase', {
  value: {{checkout.grandTotal}},
  currency: '{{checkout.currency.code}}',
  order_id: '{{checkout.order.id}}'
});
</script>

Data Warehouse Integrations

Snowflake

X Ads Data Export:

-- Create stage for X Ads data
CREATE STAGE x_ads_stage
  URL = 's3://your-bucket/x-ads/'
  CREDENTIALS = (AWS_KEY_ID = '...' AWS_SECRET_KEY = '...');

-- Load campaign performance
COPY INTO x_ads_campaigns
FROM @x_ads_stage/campaigns/
FILE_FORMAT = (TYPE = 'JSON');

-- Join with conversion data
SELECT
  c.campaign_name,
  c.impressions,
  c.clicks,
  conv.conversions,
  conv.revenue
FROM x_ads_campaigns c
LEFT JOIN conversions conv ON c.campaign_id = conv.campaign_id;

Google BigQuery

-- Import X Ads data
LOAD DATA INTO x_ads.campaign_stats
FROM FILES (
  format = 'JSON',
  uris = ['gs://your-bucket/x-ads/*.json']
);

-- Attribution analysis
SELECT
  campaign_name,
  SUM(impressions) as total_impressions,
  SUM(clicks) as total_clicks,
  SUM(conversions) as total_conversions,
  SUM(revenue) as total_revenue,
  SAFE_DIVIDE(SUM(revenue), SUM(spend)) as roas
FROM x_ads.campaign_stats
GROUP BY campaign_name
ORDER BY total_revenue DESC;

API Integration Patterns

X Ads API Authentication

OAuth 2.0 Setup:

const { TwitterApi } = require('twitter-api-v2');

const client = new TwitterApi({
  appKey: process.env.X_API_KEY,
  appSecret: process.env.X_API_SECRET,
  accessToken: process.env.X_ACCESS_TOKEN,
  accessSecret: process.env.X_ACCESS_SECRET
});

// Access Ads API
const adsClient = client.v2;

Campaign Management API

import requests

class XAdsAPI:
    def __init__(self, access_token):
        self.base_url = 'https://ads-api.twitter.com/12'
        self.headers = {
            'Authorization': f'Bearer {access_token}',
            'Content-Type': 'application/json'
        }

    def get_campaigns(self, account_id):
        url = f'{self.base_url}/accounts/{account_id}/campaigns'
        response = requests.get(url, headers=self.headers)
        return response.json()

    def get_campaign_stats(self, account_id, campaign_ids, start_date, end_date):
        url = f'{self.base_url}/stats/accounts/{account_id}'
        params = {
            'entity': 'CAMPAIGN',
            'entity_ids': ','.join(campaign_ids),
            'start_time': start_date,
            'end_time': end_date,
            'granularity': 'DAY',
            'metric_groups': 'ENGAGEMENT,BILLING'
        }
        response = requests.get(url, headers=self.headers, params=params)
        return response.json()

Data Activation

Website Custom Audiences

Create audiences from pixel data:

1. Navigate to Audiences in X Ads Manager
2. Select Create Audience > Website Activity
3. Define audience rules:
   • All website visitors
   • Specific page visitors
   • Conversion event completers
4. Set lookback window (1-540 days)

Tailored Audiences

Upload CRM lists for targeting:

def create_tailored_audience(name, description, hashed_emails):
    url = f'{base_url}/accounts/{account_id}/tailored_audiences'

    payload = {
        'name': name,
        'description': description,
        'list_type': 'EMAIL'
    }

    # Create audience
    response = requests.post(url, json=payload, headers=headers)
    audience_id = response.json()['data']['id']

    # Upload users
    upload_url = f'{base_url}/accounts/{account_id}/tailored_audiences/{audience_id}/users'

    for batch in chunks(hashed_emails, 2500):
        requests.post(upload_url, json={'users': batch}, headers=headers)

    return audience_id

Lookalike Audiences

1. Select source audience (converters, high-value customers)
2. Choose similarity level (1-10%, higher = broader)
3. Target country/region
4. Audience generates within 24-48 hours

Compliance & Security

GDPR Compliance

Consent Management:

// Only fire pixel with consent
if (hasMarketingConsent()) {
  twq('config', 'YOUR_PIXEL_ID');
  twq('track', 'PageView');
}

// Opt-out mechanism
function optOutXTracking() {
  twq('config', 'YOUR_PIXEL_ID', { debug: true });
  // Disable tracking
  window.twq = function() {};
}

CCPA Compliance

1. Enable "Do Not Sell" handling in X Ads Manager
2. Respect DNT browser signals
3. Provide opt-out mechanisms
4. Honor data deletion requests

Data Retention

Troubleshooting Integration Issues

Common Problems

Validation Tools

1. X Pixel Helper: Chrome extension for debugging
2. Events Manager: Real-time event validation
3. API Test Endpoint: Validate CAPI calls before production

Support Resources

• X Ads API Documentation
• X Business Help Center
• X Ads Community