X Ads Install / Embed Tag | OpsBlu Docs

X Ads Install / Embed Tag

How to install and deploy the X (Twitter) Ads tracking tag or SDK. Covers GTM deployment, direct code installation, mobile SDK setup, server-side.

Delivery Options

X Pixel Base Code

Direct Implementation

Install the X Pixel base code in the <head> section of all pages:

<!-- 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','PIXEL_ID');
</script>
<!-- End X Pixel Base Code -->

Replace PIXEL_ID with your actual X Pixel ID from Ads Manager.

Event Tracking

PageView

Track page views (recommended for all pages):

<script>
twq('event', 'tw-PIXEL_ID-PageView');
</script>

Purchase

Track completed purchases:

<script>
twq('event', 'tw-PIXEL_ID-Purchase', {
  value: '99.99',
  currency: 'USD',
  transaction_id: 'ORDER_12345',
  num_items: '2'
});
</script>

AddToCart

Track cart additions:

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

CompleteRegistration

Track user signups:

<script>
twq('event', 'tw-PIXEL_ID-CompleteRegistration', {
  value: '25.00',
  currency: 'USD'
});
</script>

Google Tag Manager Implementation

Create X Pixel Base Tag

  1. Create new tag: Custom HTML
  2. Name: "X Pixel - Base Code"
  3. Paste 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','{{X Pixel ID}}');
</script>
  1. Trigger: All Pages
  2. Firing Priority: 1

Create GTM Variable

  1. Create new variable: Constant
  2. Name: "X Pixel ID"
  3. Value: Your Pixel ID (e.g., o1234)

Event Tags

Purchase Event:

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

Trigger: Custom Event - purchase

Lead Event:

<script>
twq('event', 'tw-{{X Pixel ID}}-SubmitForm', {
  value: '50.00',
  currency: 'USD'
});
</script>

Trigger: Form Submission - All Forms

Advanced Matching

Include hashed email for improved attribution:

// Hash email client-side
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 trackWithAdvancedMatching(email) {
  const hashedEmail = await hashEmail(email);

  twq('event', 'tw-PIXEL_ID-Purchase', {
    value: '99.99',
    currency: 'USD',
    transaction_id: 'ORDER_12345',
    email_address: hashedEmail
  });
}

// Usage on confirmation page
trackWithAdvancedMatching('user@example.com');

Load pixel only with user consent:

<script>
// Check for consent
if (window.cookieConsent && window.cookieConsent.advertising) {
  // Load X Pixel
  !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','PIXEL_ID');
} else {
  console.log('X Pixel blocked - no consent');
}
</script>

Mobile App Integration

X doesn't have native SDK. Use Mobile Measurement Partners:

AppsFlyer

import AppsFlyerLib

AppsFlyerLib.shared().logEvent("af_purchase", withValues: [
    AFEventParamRevenue: 99.99,
    AFEventParamCurrency: "USD",
    "af_channel": "twitter"
])

Adjust

val event = AdjustEvent("abc123")
event.setRevenue(99.99, "USD")
event.addCallbackParameter("network", "twitter")
Adjust.trackEvent(event)

Testing & Validation

X Pixel Helper

  1. Install X Pixel Helper Chrome extension
  2. Navigate to your website
  3. Click extension icon
  4. Verify pixel is active and events fire

Browser Console

// Check if X Pixel loaded
if (typeof twq !== 'undefined') {
  console.log('✓ X Pixel loaded');

  // Fire test event
  twq('event', 'tw-PIXEL_ID-TestEvent');
} else {
  console.error('✗ X Pixel not loaded');
}

Network Tab

  1. Open Developer Tools → Network tab
  2. Filter by "twitter" or "ads-twitter"
  3. Verify requests to static.ads-twitter.com
  4. Check event parameters

Validation Checklist

  • Base code loads on all pages
  • Pixel ID is correct
  • PageView events fire on all pages
  • Conversion events fire at correct moments
  • Event parameters pass correct data
  • Advanced matching implemented (optional)
  • Consent management integrated
  • Test with X Pixel Helper
  • Verify in Events Manager
  • Custom audiences populate (24-48 hours)
Back to top