Outbrain Install / Embed Tag | OpsBlu Docs

Outbrain Install / Embed Tag

Deployment approaches for installing Outbrain Pixel via direct embed, Google Tag Manager, or server-side integration.

Delivery Options

Outbrain offers multiple methods for deploying tracking pixels, each suited to different technical environments and organizational needs:

Option 1: Direct JavaScript Embed

When to Use

  • Simple websites with limited tracking requirements
  • Teams with direct access to site templates or header/footer files
  • Quick implementation needed without tag management overhead
  • Static sites or CMS platforms with custom code injection

Implementation Steps

Step 1: Obtain Pixel Code from Amplify

  1. Log in to Outbrain Amplify dashboard
  2. Navigate to Tracking & Conversions or Pixel Setup
  3. Copy the base pixel JavaScript snippet
  4. Note your unique Outbrain Pixel ID (typically in format: OB-XXXXX-X)

Step 2: Install Base Pixel on All Pages

The base pixel should fire on every page to enable audience building and retargeting.

<!-- Outbrain Base Pixel - Place in <head> or before </body> -->
<script type="text/javascript">
  !function(_window, _document) {
    var OB_ADV_ID = 'YOUR_PIXEL_ID_HERE';
    if (_window.obApi) {
      var toArray = function(object) {
        return Object.prototype.toString.call(object) === '[object Array]' ? object : [object];
      };
      _window.obApi.marketerId = toArray(_window.obApi.marketerId).concat(toArray(OB_ADV_ID));
      return;
    }
    var api = _window.obApi = function() {
      api.dispatch ? api.dispatch.apply(api, arguments) : api.queue.push(arguments);
    };
    api.version = '1.1';
    api.loaded = true;
    api.marketerId = OB_ADV_ID;
    api.queue = [];
    var tag = _document.createElement('script');
    tag.async = true;
    tag.src = '//amplify.outbrain.com/cp/obtp.js';
    tag.type = 'text/javascript';
    var script = _document.getElementsByTagName('script')[0];
    script.parentNode.insertBefore(tag, script);
  }(window, document);

  obApi('track', 'PAGE_VIEW');
</script>

Key Configuration:

  • Replace YOUR_PIXEL_ID_HERE with your actual Outbrain Pixel ID
  • Place in site template so it loads on all pages
  • Ensure it fires before the closing </body> tag or in the <head> section

Step 3: Add Conversion Pixel to Post-Conversion Pages

On pages where conversions happen (thank-you pages, order confirmations, lead form success pages), add the conversion tracking pixel.

<!-- Outbrain Conversion Pixel - Place on conversion pages only -->
<script type="text/javascript">
  obApi('track', 'Conversion', {
    orderValue: 99.99,          // Total purchase value or lead value
    orderId: 'ORDER-12345',     // Unique transaction ID
    currency: 'USD'             // Currency code
  });
</script>

Dynamic Values: Replace static values with server-side variables:

<!-- Example with server-side template variables -->
<script type="text/javascript">
  obApi('track', 'Conversion', {
    orderValue: {{ order.total }},
    orderId: '{{ order.id }}',
    currency: '{{ order.currency }}'
  });
</script>

Validation

  1. Load a page with the base pixel installed
  2. Open browser developer tools (F12) > Network tab
  3. Look for requests to amplify.outbrain.com or outbrain.com
  4. Verify request includes your Pixel ID and PAGE_VIEW event
  5. Trigger a test conversion and verify Conversion event fires with correct parameters

Option 2: Google Tag Manager Deployment

When to Use

  • Marketing teams need to update tracking without developer involvement
  • Multiple tracking pixels and tags are already managed in GTM
  • Need flexibility to test and modify tracking logic quickly
  • Want to use GTM's built-in debugging and preview tools

Implementation Steps

Step 1: Create Outbrain Base Pixel Tag

  1. Log in to Google Tag Manager
  2. Navigate to Tags > New
  3. Click Tag Configuration > Custom HTML
  4. Name the tag: Outbrain - Base Pixel
  5. Paste the Outbrain base pixel code (same as direct embed option)
  6. Set trigger to All Pages (or Initialization - All Pages for immediate firing)
  7. Save the tag

Step 2: Create Conversion Tracking Tag

  1. Create a new Custom HTML tag in GTM
  2. Name it: Outbrain - Conversion Tracking
  3. Paste the conversion pixel code
  4. Use GTM variables to dynamically populate conversion parameters:
<script type="text/javascript">
  obApi('track', 'Conversion', {
    orderValue: {{DLV - Order Value}},     // GTM Data Layer Variable
    orderId: '{{DLV - Order ID}}',         // GTM Data Layer Variable
    currency: '{{DLV - Currency}}'         // GTM Data Layer Variable
  });
</script>
  1. Set trigger based on conversion event (e.g., Custom Event with event name purchase or Page View on /thank-you URL)
  2. Save the tag

Step 3: Configure Data Layer Variables

If using dynamic values, create GTM Data Layer Variables:

  1. Go to Variables > New > Data Layer Variable
  2. Create variables for:
    • DLV - Order Value → Data Layer Variable Name: ecommerce.purchase.actionField.revenue
    • DLV - Order ID → Data Layer Variable Name: ecommerce.purchase.actionField.transaction_id
    • DLV - Currency → Data Layer Variable Name: ecommerce.currencyCode
  3. Adjust variable paths to match your site's data layer structure

Step 4: Test in Preview Mode

  1. Click Preview in GTM to enter debug mode
  2. Navigate to your site in the opened browser window
  3. Verify Outbrain - Base Pixel tag fires on all pages
  4. Navigate to conversion page or trigger conversion event
  5. Verify Outbrain - Conversion Tracking tag fires with correct parameters
  6. Check the Variables tab to ensure dynamic values are populated

Step 5: Publish GTM Container

  1. Exit preview mode
  2. Click Submit in GTM
  3. Add version name and description (e.g., "Add Outbrain conversion tracking")
  4. Click Publish
  5. Monitor live site to confirm tags fire correctly in production

Advanced GTM Configuration

Trigger Exceptions: Prevent pixel from firing if user has opted out of tracking:

  1. Create a custom JavaScript variable to check consent status
  2. Add exception trigger to Outbrain tags: Fire tag except when consent variable is false

Custom Event Tracking: Track engagement actions beyond conversions:

<script type="text/javascript">
  obApi('track', 'CustomEvent', {
    eventName: '{{DLV - Event Name}}',
    eventValue: {{DLV - Event Value}}
  });
</script>

Option 3: Server-Side Conversion API

When to Use

  • Privacy regulations require minimizing client-side tracking
  • Ad blockers or browser restrictions are blocking pixel fires
  • Need more reliable conversion tracking independent of cookies
  • Want to send offline or CRM conversions to Outbrain

Prerequisites

  • Backend server with ability to make HTTPS POST requests
  • Outbrain API credentials (contact Outbrain support to obtain)
  • User identifier to match conversions to clicks (email, phone, or Outbrain click ID)

Implementation Steps

Step 1: Obtain API Credentials

  1. Contact Outbrain support or account manager
  2. Request access to Conversion API
  3. Receive API endpoint URL and authentication token
  4. Store credentials securely (environment variables, secret manager)

Step 2: Capture Click ID from Outbrain Campaigns

Outbrain appends a click ID parameter (obOrigUrl or custom parameter) to landing page URLs. Capture and store this on the user's session or cookie.

// Client-side: Capture Outbrain click ID from URL
const urlParams = new URLSearchParams(window.location.search);
const obClickId = urlParams.get('ob_click_id');
if (obClickId) {
  sessionStorage.setItem('ob_click_id', obClickId);
}

Step 3: Send Conversion Data from Backend

When a conversion occurs on your server (e.g., order placed, lead form submitted), make a POST request to Outbrain's Conversion API.

Example: Node.js

const axios = require('axios');

async function sendOutbrainConversion(orderData) {
  const obClickId = orderData.obClickId; // Retrieved from session

  const conversionPayload = {
    click_id: obClickId,
    conversion_timestamp: new Date().toISOString(),
    conversion_value: orderData.revenue,
    transaction_id: orderData.orderId,
    currency: orderData.currency,
    hashed_email: hashEmail(orderData.customerEmail) // Optional: for enhanced matching
  };

  try {
    const response = await axios.post(
      'https://api.outbrain.com/amplify/v1/conversions',
      conversionPayload,
      {
        headers: {
          'Authorization': `Bearer ${process.env.OUTBRAIN_API_TOKEN}`,
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Outbrain conversion sent:', response.data);
  } catch (error) {
    console.error('Outbrain conversion error:', error.response.data);
  }
}

function hashEmail(email) {
  const crypto = require('crypto');
  return crypto.createHash('sha256').update(email.toLowerCase().trim()).digest('hex');
}

Example: Python

import requests
import hashlib
import os
from datetime import datetime

def send_outbrain_conversion(order_data):
    ob_click_id = order_data.get('ob_click_id')

    payload = {
        'click_id': ob_click_id,
        'conversion_timestamp': datetime.utcnow().isoformat(),
        'conversion_value': order_data['revenue'],
        'transaction_id': order_data['order_id'],
        'currency': order_data['currency'],
        'hashed_email': hash_email(order_data['customer_email'])
    }

    headers = {
        'Authorization': f"Bearer {os.environ['OUTBRAIN_API_TOKEN']}",
        'Content-Type': 'application/json'
    }

    response = requests.post(
        'https://api.outbrain.com/amplify/v1/conversions',
        json=payload,
        headers=headers
    )

    if response.status_code == 200:
        print('Outbrain conversion sent successfully')
    else:
        print(f'Error: {response.status_code} - {response.text}')

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

Step 4: Validate API Integration

  1. Send a test conversion using a known Outbrain click ID
  2. Check API response for success confirmation (HTTP 200)
  3. Verify conversion appears in Amplify dashboard within 1-2 hours
  4. Monitor server logs for any API errors or rate limiting

Enhanced Matching with Hashed PII

For improved attribution accuracy, send hashed personally identifiable information:

  • Hashed email: SHA-256 hash of lowercase, trimmed email
  • Hashed phone: SHA-256 hash of phone number (E.164 format)
  • User IP address: For geo-matching and fraud prevention

Privacy Considerations:

  • Hash PII before sending (never send plaintext emails or phone numbers)
  • Ensure compliance with GDPR, CCPA, and other privacy regulations
  • Include hashed PII only with explicit user consent

Hybrid Approach: Browser Pixel + Server-Side API

Benefits of Redundancy

  • Browser pixel tracks most conversions in real-time
  • Server-side API catches conversions blocked by ad blockers or privacy tools
  • Enhanced matching improves attribution accuracy
  • Offline conversions (phone orders, in-store sales) can be uploaded via API

Implementation Strategy

  1. Deploy browser-based pixel (direct embed or GTM) for immediate tracking
  2. Implement server-side Conversion API for critical conversions
  3. Use unique transaction IDs to deduplicate conversions in reporting
  4. Monitor both channels to identify discrepancies and coverage gaps

Validation Checklist

  • Base pixel fires on all site pages
  • Pixel ID is correct and matches Amplify account
  • Conversion pixel fires on post-conversion pages only
  • Conversion parameters (value, order ID, currency) are dynamic and accurate
  • No JavaScript errors in browser console blocking pixel execution
  • GTM container published (if using Tag Manager)
  • Server-side API authenticated and returning HTTP 200 responses
  • Test conversions appear in Amplify dashboard within 1-2 hours
  • Cross-domain tracking enabled if campaigns drive to multiple domains
  • Consent management integration respects user opt-outs

Troubleshooting

Pixel Not Firing

  • Check browser developer tools Network tab for requests to outbrain.com or amplify.outbrain.com
  • Verify JavaScript is enabled and no ad blockers are interfering
  • Ensure pixel code is in <head> or before </body> closing tag
  • Test in incognito/private browsing mode to rule out browser extensions

Conversions Not Tracking

  • Confirm conversion pixel is on the post-conversion page (not just landing page)
  • Verify conversion parameters are populated (not null or undefined)
  • Check that Outbrain click ID is preserved through conversion funnel
  • Review attribution window in Amplify (conversions outside window won't attribute)

GTM Tag Not Firing

  • Enter GTM Preview mode and verify tag appears in Tags Fired section
  • Check trigger conditions match expected page or event
  • Ensure data layer variables are available when tag fires
  • Publish GTM container (tags in preview mode don't fire in production)

API Integration Errors

  • Verify API token is valid and has not expired
  • Check request payload matches required schema
  • Monitor for rate limiting (HTTP 429 errors)
  • Ensure HTTPS is used (HTTP requests will fail)
Back to top