X Ads Event Tracking | OpsBlu Docs

X Ads Event Tracking

How to configure conversion tracking events for X (Twitter) Ads. Covers pixel event setup, custom parameters, conversion value assignment, audience.

Standard Events

X Pixel supports these standard conversion events:

PageView

twq('event', 'tw-PIXEL_ID-PageView');

Purchase

twq('event', 'tw-PIXEL_ID-Purchase', {
  value: '99.99',
  currency: 'USD',
  transaction_id: 'ORDER_12345',
  num_items: '2',
  content_ids: ['SKU_12345', 'SKU_67890']
});

AddToCart

twq('event', 'tw-PIXEL_ID-AddToCart', {
  value: '49.99',
  currency: 'USD',
  content_ids: ['SKU_12345'],
  content_name: 'Blue Widget',
  content_type: 'product'
});

InitiateCheckout

twq('event', 'tw-PIXEL_ID-InitiateCheckout', {
  value: '149.99',
  currency: 'USD',
  num_items: '3'
});

AddPaymentInfo

twq('event', 'tw-PIXEL_ID-AddPaymentInfo', {
  value: '149.99',
  currency: 'USD'
});

CompleteRegistration

twq('event', 'tw-PIXEL_ID-CompleteRegistration', {
  value: '25.00',
  currency: 'USD',
  status: 'completed'
});

SubmitForm

twq('event', 'tw-PIXEL_ID-SubmitForm', {
  value: '50.00',
  currency: 'USD'
});

twq('event', 'tw-PIXEL_ID-Search', {
  search_string: 'blue widgets',
  content_category: 'widgets'
});

ViewContent

twq('event', 'tw-PIXEL_ID-ViewContent', {
  content_ids: ['SKU_12345'],
  content_name: 'Blue Widget',
  content_type: 'product',
  value: '49.99',
  currency: 'USD'
});

E-commerce Event Sequence

// 1. View Product
twq('event', 'tw-PIXEL_ID-ViewContent', {
  content_ids: ['SKU_12345'],
  value: '49.99',
  currency: 'USD'
});

// 2. Add to Cart
twq('event', 'tw-PIXEL_ID-AddToCart', {
  content_ids: ['SKU_12345'],
  value: '49.99',
  currency: 'USD'
});

// 3. Initiate Checkout
twq('event', 'tw-PIXEL_ID-InitiateCheckout', {
  value: '54.99',
  num_items: '1',
  currency: 'USD'
});

// 4. Add Payment Info
twq('event', 'tw-PIXEL_ID-AddPaymentInfo', {
  value: '54.99',
  currency: 'USD'
});

// 5. Purchase
twq('event', 'tw-PIXEL_ID-Purchase', {
  value: '54.99',
  currency: 'USD',
  transaction_id: 'ORDER_12345',
  num_items: '1'
});

Dynamic Event Tracking

Product View

function trackXProductView(product) {
  twq('event', 'tw-PIXEL_ID-ViewContent', {
    content_ids: [product.id],
    content_name: product.name,
    content_type: 'product',
    value: product.price.toString(),
    currency: 'USD'
  });
}

// Usage
trackXProductView({
  id: 'SKU_12345',
  name: 'Blue Widget',
  price: 49.99
});

Add to Cart

document.querySelectorAll('.add-to-cart-btn').forEach(button => {
  button.addEventListener('click', function() {
    const productId = this.dataset.productId;
    const productPrice = this.dataset.productPrice;

    twq('event', 'tw-PIXEL_ID-AddToCart', {
      content_ids: [productId],
      value: productPrice,
      currency: 'USD'
    });
  });
});

Form Submission

document.getElementById('contact-form').addEventListener('submit', function(e) {
  twq('event', 'tw-PIXEL_ID-SubmitForm', {
    value: '50.00',
    currency: 'USD'
  });
});

Advanced Matching Parameters

Include user data for improved attribution:

// Hash email before sending
async function hashEmail(email) {
  const msgBuffer = new TextEncoder().encode(email.toLowerCase().trim());
  const hashBuffer = await crypto.subtle.digest('SHA-256', msgBuffer);
  const hashArray = Array.from(new Uint8Array(hashBuffer));
  return hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
}

// Track with advanced matching
async function trackPurchaseWithMatching(orderData) {
  const hashedEmail = await hashEmail(orderData.email);

  twq('event', 'tw-PIXEL_ID-Purchase', {
    value: orderData.value.toString(),
    currency: 'USD',
    transaction_id: orderData.orderId,
    email_address: hashedEmail,
    phone_number: orderData.phone // Will be hashed automatically by X
  });
}

// Usage
trackPurchaseWithMatching({
  value: 99.99,
  orderId: 'ORDER_12345',
  email: 'user@example.com',
  phone: '+15551234567'
});

GTM Implementation

Data Layer Push

dataLayer.push({
  'event': 'x_purchase',
  'ecommerce': {
    'purchase': {
      'actionField': {
        'id': 'ORDER_12345',
        'revenue': '99.99'
      },
      'products': [{
        'id': 'SKU_12345',
        'quantity': 2
      }]
    }
  }
});

GTM Custom HTML Tag

<script>
twq('event', 'tw-{{X Pixel ID}}-Purchase', {
  value: '{{DLV - Transaction Value}}',
  currency: 'USD',
  transaction_id: '{{DLV - Transaction ID}}',
  num_items: '{{DLV - Product Quantity}}'
});
</script>

Trigger: Custom Event - x_purchase

Custom Audience Events

High-Value Customer

twq('event', 'tw-PIXEL_ID-CustomEvent', {
  event_name: 'high_value_customer',
  value: '500.00',
  currency: 'USD',
  lifetime_value: '5000.00'
});

Content Category View

twq('event', 'tw-PIXEL_ID-ViewContent', {
  content_category: 'technology',
  content_type: 'blog_post',
  content_name: 'How to Use X Ads'
});

Best Practices

  • Always include value and currency for conversion events
  • Use unique transaction_id to prevent duplicates
  • Implement advanced matching for better attribution
  • Test events before launching campaigns
  • Monitor Events Manager for pixel health
  • Document event schema for team
  • Use GTM for centralized management
  • Implement deduplication for hybrid tracking
Back to top