Web Pixel Developer Guide

This guide is for developers adding the Bronco web pixel to a site by hand: installing the script, tracking conversions, leads, and custom events with broncoTrack(), and handling single-page apps.

If you're on Shopify and use the Bronco app or the Shopify custom pixel, page views, add-to-cart, checkout, and purchase events are tracked for you and you don't need this guide. For the no-code setup options, see Setting Up the Web Pixel.

Installation

Add the pixel script between the <head> tags on every page of your website.

1. In Bronco, go to Settings → Advertisers, click Configure in the Web Pixel column, and copy the script from the Pixel Configuration panel.
2. Paste it between the <head> tags on your website.
3. Visit your website to generate a test event.

<script src="https://p.1bronco.com/js/t.js" data-tid="YOUR_TRACKING_ID" async></script>

YOUR_TRACKING_ID is the tracking ID shown in your Pixel Configuration panel, a UUID like a3f8c2e1-7b4d-4e9a-b6f0-2d1c8e5a9f3b. The script you copy from the panel already has it filled in.

TIP

The script automatically tracks a pageview event on every page load, and on every page change in a single-page app. No additional code is required for page view tracking.

Google Tag Manager

If you manage your site's tags through Google Tag Manager, use a Custom HTML tag instead of the standard script tag. Don't use the standard data-tid script tag inside GTM: the script detection may not work reliably when a tag manager injects it.

1. In the Pixel Configuration panel, select the Google Tag Manager method and copy the code snippet.
2. In Google Tag Manager, create a new Custom HTML tag and paste the code.
3. Set the trigger to All Pages, then publish your container.
4. Visit your website to generate a test event.

<script>
window.__bt_config = {
  tid: "YOUR_TRACKING_ID",
  base: "https://p.1bronco.com"
};

var s = document.createElement("script");
s.src = window.__bt_config.base + "/js/t.js";
s.async = true;
document.head.appendChild(s);
</script>

This snippet passes configuration through window.__bt_config instead of data-tid. The tracker still fires a pageview event on load and uses first-party cookies for visitor and session tracking, just like the standard installation.

Tracking custom events via GTM

After the pixel has loaded, broncoTrack() is available globally. You can call it from additional Custom HTML tags or from your site's own JavaScript:

broncoTrack('purchase', {
  order_id: '100045',
  value: 99.99,
  currency: 'USD'
});

Page views

Page views are tracked automatically. The pixel sends a pageview event with the current URL and referrer when a page loads, and again each time a single-page app moves to a new page without reloading (see Single-page applications).

To fire a page view manually, call:

broncoTrack('pageview');

Conversions

Track a conversion when a user completes an action such as a purchase, sign-up, or download. Fire the event on the confirmation or thank-you page.

Purchase or sale

broncoTrack('purchase', {
  order_id: '100045',
  value: 99.99,
  currency: 'USD'
});

order_id is your order number or ID as your store or checkout creates it: digits ('100045' or 100045) or text ('ORD-100045'). Send a different ID for every order. Bronco matches purchases to your campaigns by it, and the Attribution dashboard counts purchases that share an ID as one order. A purchase sent without an ID is still recorded but isn't included in the Attribution dashboard. Send value as a number.

Sign-up

broncoTrack('sign_up', {
  method: 'email'
});

Download

broncoTrack('download', {
  file: 'pricing-guide.pdf'
});

Leads

Track a lead when a user submits a form, requests a demo, or provides contact information.

Form submission

broncoTrack('lead', {
  form: 'contact_us',
  source: 'homepage'
});

Demo request

broncoTrack('lead', {
  form: 'demo_request',
  plan: 'enterprise'
});

For best results, fire the event in your form's submit handler after validation passes:

document.getElementById('contact-form').addEventListener('submit', function (e) {
  broncoTrack('lead', { form: 'contact_us' });
});

Using your own lead ID

By default each lead is assigned a unique conversion ID automatically. If your system already generates its own lead, submission, or CRM record ID, pass it as lead_id so conversions are de-duplicated against your identifier instead of a generated one:

broncoTrack('lead', {
  form: 'contact_us',
  source: 'homepage',
  lead_id: 'YOUR_LEAD_ID' // e.g. '48213' or 'CRM-2026-00417'
});

TIP

lead_id should be unique per submission. The same key also works for sign_up, conversion, and download events (you may also use id or order_id).

Custom events

You can track any event by passing a custom event name. Use a short, descriptive snake_case name.

For shopping steps, use these names exactly: product_viewed, add_to_cart and checkout_started. The Sales Funnel on the Pixel Activity dashboard counts only these names, and only these names are passed on for campaign measurement. An event sent under another name, such as begin_checkout, is recorded but counted in neither.

// User views a specific product
broncoTrack('product_viewed', {
  product_id: 'SKU-1001',
  category: 'footwear'
});

// User adds item to cart
broncoTrack('add_to_cart', {
  product_id: 'SKU-1001',
  product_name: 'Running Shoes',
  value: 129.00
});

// User starts checkout
broncoTrack('checkout_started', {
  value: 287.00,
  currency: 'USD'
});

// User watches a video
broncoTrack('video_play', {
  video_id: 'promo-2026',
  duration: 120
});

Event properties

Every event can include an optional properties object: key-value pairs that give more context about the event.

Type	Example	Notes
String	{ category: 'shoes' }	Most common type, for labels and IDs.
Number	{ value: 49.99 }	Use for monetary values, quantities, or scores.
Boolean	{ is_member: true }	Use for flags and toggles.

Best practices

Use snake_case for property names. Keep values simple (strings, numbers, booleans). Don't send sensitive data such as emails, passwords, or personal information.

Single-page applications

The pixel tracks page changes in single-page apps automatically. When your app moves to a new page without a full reload, the pixel sends a pageview for the new address, with the previous page as the referrer. This works with any router that uses the browser's History API, including React Router, Next.js, Vue Router and Angular, and needs no extra code.

• A new page means a new path. Changes to only the query string (such as ?color=black) or the # fragment aren't counted as new page views.
• If your app already calls broncoTrack('pageview') after each route change, you can keep it: the pixel skips a second page view for the same address.
• If your app uses hash-based routing (addresses like /#/settings), the path doesn't change, so send the page view yourself after each route change:

window.addEventListener('hashchange', function () {
  broncoTrack('pageview');
});

API reference

broncoTrack(eventName, properties?)

Sends an event to the tracker.

Parameter	Type	Required	Description
eventName	string	Yes	Name of the event, such as 'purchase' or 'lead'.
properties	object	No	Key-value pairs of additional event data.

Common event names

Event	When to fire	Suggested properties
pageview	Page load or single-page app page change	Tracked automatically
purchase	Order confirmation	order_id, value, currency
lead	Form submission	form, source
sign_up	Account creation	method
product_viewed	Product detail page	product_id, category
add_to_cart	Item added to cart	product_id, value
checkout_started	Checkout initiated	value, currency

How it works

What the pixel does behind the scenes:

• Visitor ID — a unique ID stored in a first-party cookie (_bt_vid) for one year. It identifies the same browser across visits.
• Session ID — a unique ID stored in a cookie (_bt_sid) that expires after 30 minutes of inactivity. It groups events into sessions.
• Event delivery — events are sent with navigator.sendBeacon() when available, falling back to XMLHttpRequest, so they are delivered even while the page is unloading.
• Automatic data — every event includes the page URL, referrer, and timestamp without any configuration.

Troubleshooting

Events not appearing

• Check that the script tag is in the <head> section and the data-tid value matches your tracking ID.
• Open your browser's developer tools, go to the Network tab, and look for requests to /t. They should return a 204 status.
• Check that the src URL in the script tag is reachable and loads without errors.
• Click Test Configuration in the Pixel Configuration panel to confirm events are being received.

Duplicate page views

The pixel has a guard (window.__bt_loaded) that stops it loading twice. Make sure the script tag appears only once per page.

Ad blockers

Some ad blockers stop the tracker script from loading. Using a first-party subdomain (for example t.yourdomain.com) that proxies to the tracker reduces blocking.

Content Security Policy (CSP)

If your site uses a CSP, include the tracker domain in both the script-src and connect-src directives.

Still stuck? Check Pixel Activity for recent events, or reach out to support.