Outbrain Conversion API Integration

Create an Event-Based Conversion in Outbrain

First, log in to your Outbrain Amplify dashboard. Navigate to Conversions and add a new event-based conversion. Provide a unique name that accurately describes the action, for example, 'purchase' or 'lead'. Ensure you save this name exactly as it is case-sensitive and will be used in your API calls.

1. Go to "Conversions" -> "Add Conversion".
2. Select "Event-Based Conversion".
3. Enter a unique "Name" (e.g., "purchase", "lead").
4. Configure conversion window and value.
5. Click "Save".

Configure Click Tracking in Outbrain Campaigns

To capture the Outbrain click ID, you must instruct Outbrain to pass this parameter to your landing page. In your campaign settings, locate the tracking section and add the specific parameter to your tracking code or URL suffix. Outbrain will dynamically replace `{{ob_click_id}}` with a unique identifier for each click.

# Add this parameter to your campaign tracking URL suffix
OutbrainClickId={{ob_click_id}}

Capture the Outbrain Click ID (ob_click_id)

On your landing page or server, implement logic to extract the `ob_click_id` from the URL query parameters. This ID is critical for attributing conversions back to Outbrain. It should be stored securely, for example, in a cookie, local storage, or your database, until a conversion event occurs.

// Example in JavaScript (client-side, for demonstration)
function getOutbrainClickId() {
  const params = new URLSearchParams(window.location.search);
  return params.get("OutbrainClickId");
}

const obClickId = getOutbrainClickId();
if (obClickId) {
  // Store obClickId, e.g., in localStorage or send to your server
  console.log("Captured Outbrain Click ID:", obClickId);
}

Prepare Your Server-Side Event Data

When a conversion event, such as a purchase or signup, takes place on your website, you need to collect relevant data. This includes the captured `ob_click_id`, the exact name of the Outbrain conversion event, and optionally, the conversion value and currency. This data will form the basis of your postback request.

// Example of event data collected on your server
const conversionData = {
  ob_click_id: "v1-your-captured-click-id", // e.g., from database or cookie
  event_name: "purchase", // Exact name from Outbrain setup
  order_value: 99.99, // Optional: numeric value
  currency: "USD", // Optional: 3-letter ISO code
};

Send the Conversion Postback to Outbrain

Finally, send a server-to-server GET request to Outbrain's unified pixel endpoint. This request must include the `ob_click_id` and the `name` of the conversion event as query parameters. Include `orderValue` and `currency` if available.

// Example of sending the postback from your server (Node.js)
const obClickId = "v1-your-captured-click-id";
const eventName = "purchase";
const orderValue = 99.99;
const currency = "USD";

let postbackUrl = `https://tr.outbrain.com/unifiedPixel?ob_click_id=${obClickId}&name=${eventName}`;

if (orderValue && currency) {
  postbackUrl += `&orderValue=${orderValue}&currency=${currency}`;
}

fetch(postbackUrl)
  .then(response => {
    if (response.ok) {
      console.log("Outbrain postback successful.");
    } else {
      console.error("Outbrain postback failed:", response.statusText);
    }
  })
  .catch(error => {
    console.error("Error sending Outbrain postback:", error);
  });

Verify Conversions in Outbrain and TrackLayer

After implementing the postback, monitor your Outbrain Amplify dashboard to ensure conversions are being attributed correctly. Simultaneously, observe your TrackLayer dashboard to confirm that events are flowing through and being matched. Use test purchases to validate the entire conversion flow.

// No code for this step, just verification in dashboards.

Issue: Conversions are not appearing in Outbrain

Fix: Double-check that the 'OutbrainClickId' parameter is correctly configured in your campaign settings and that your server is successfully capturing it. Verify the 'name' parameter in your postback exactly matches the conversion event name in Outbrain. Ensure no firewalls are blocking the postback URL.

Issue: Conversion values are incorrect or missing

Fix: Confirm that 'orderValue' and 'currency' parameters are included in your postback URL and that their values are correctly formatted (e.g., numeric for value, 3-letter ISO code for currency).

Issue: Duplicate conversions reported

Fix: Implement a deduplication mechanism on your server-side. Store 'ob_click_id' and the event name, and only send a postback for a unique combination that has not been sent before for the same conversion action.

Issue: ob_click_id is not present in landing page URL

Fix: Ensure your Outbrain campaign is properly configured to append the 'OutbrainClickId={{ob_click_id}}' macro to your destination URLs. Check campaign settings and ad creative links.