BETA
Docs
Hosted install

Install the Sarge pixel and prove every conversion path.

Add one hosted script, emit stable ecommerce events, keep existing media pixels in place, and verify the event stream from the matching Production, Staging, or Development environment.

Hosted pixel snippet

Use the exact snippet from the selected environment tab in the Sarge portal. The browser/API payload field is still called `siteId`, but the value is the selected environment ID. 

<script>
  window._sarge = { queue: [["track", "page.view"]] };
</script>
<script async src="https://track.sargetrack.app/pixel.js?env={siteEnvironmentId}"></script>

Place it in the document head or as early as possible in the page body. The queued `page.view` call is replayed after `pixel.js` loads.

Track ecommerce events

Call `window.sarge("track", eventName, properties)` near the action that actually changed state. Use stable, lowercase, dot-separated event names and JSON-serializable properties.

Event When Required
page.view Page load and SPA route changes. path, title
product.viewed Product detail, quick view, or product inspection. product_id
cart.added A product is successfully added to cart. product_id, price
checkout.started Checkout starts. value, currency
purchase.completed Payment succeeds and an order is created. order_id, value, currency 
window.sarge("track", "product.viewed", {
  product_id: "field-flask",
  product_name: "Field Flask",
  price: 42,
  currency: "USD"
});
window.sarge("track", "cart.added", {
  product_id: "field-flask",
  product_name: "Field Flask",
  price: 42,
  currency: "USD",
  cart_size: 1
});
window.sarge("track", "purchase.completed", {
  order_id: "order_123",
  value: 84,
  currency: "USD",
  item_count: 2
});

Watch other pixels

Sarge observes common browser pixel APIs after it loads, preserves the original function, records the call, then forwards the call to the existing provider.

fbq(...)
meta.pixel.fire

gtag(...)
google.tag.fire

dataLayer.push(...)
data_layer.push

SPA route changes

Client-side routed apps should emit another `page.view` whenever the route changes. 

window.sarge("track", "page.view", {
  path: window.location.pathname,
  title: document.title
});

Test impersonation

  1. Copy the user ID you want to test from the Sarge project page.
  2. Open the tracked site, then open the browser console on that page.
  3. Run impersonate(userId) before starting the checkout or account flow.
  4. Run clear_impersonation() when the test is finished.
impersonate('customer_123');
clear_impersonation();

While impersonation is active, browser events use the impersonated value as `userId` and are marked with Sarge test metadata. This is only debug labeling; it does not authenticate as that user in the tracked site.

Affiliate tracking and latents

The pixel reads `sarge_ref` and `sarge_aff` URL parameters, stores them in localStorage, and attaches them to later browser events during the environment attribution window. 

https://shop.example.com/?sarge_ref=summer-campaign&sarge_aff=partner-42

Use `sarge_ref` for the campaign, placement, click ID, or network click identifier. Use `sarge_aff` for the affiliate, creator, publisher, or partner ID.

Latent conversions

Sarge defaults to a 28-day attribution window. Later events such as `checkout.started`, `purchase.completed`, or a server-confirmed `affiliate.conversion` can still be tied back to the original affiliate visit until that window expires.

Server-side and postback events

Use browser events for page and interaction tracking. Use server-side events for trusted backend facts such as paid orders, refunds, fulfilled subscriptions, or webhook confirmations. 

curl -X POST "https://track.sargetrack.app/v2/server/events" \
  -H "authorization: Bearer {serverEventSecret}" \
  -H "content-type: application/json" \
  -d '{
    "siteId": "{siteEnvironmentId}",
    "name": "purchase.completed",
    "eventId": "order_123",
    "userId": "customer_123",
    "properties": {
      "order_id": "order_123",
      "value": 129.99,
      "currency": "USD"
    }
  }'

If the backend also calls Meta, Google, or another vendor API directly, report that upstream dispatch as a watchdog event with `transport: "server"` and the returned HTTP status in `properties.upstream`. Add `properties.implementation.note` when AI reviews need project-specific context. 

curl -X POST "https://track.sargetrack.app/v2/server/events" \
  -H "authorization: Bearer {serverEventSecret}" \
  -H "content-type: application/json" \
  -d '{
    "siteId": "{siteEnvironmentId}",
    "name": "meta.pixel.fire",
    "eventId": "order_123_meta_purchase",
    "sessionId": "sess_123",
    "userId": "customer_123",
    "properties": {
      "vendor": "meta",
      "transport": "server",
      "command": "track",
      "event_name": "Purchase",
      "payload": { "order_id": "order_123", "value": 129.99, "currency": "USD" },
      "upstream": {
        "endpoint": "https://graph.facebook.com/v20.0/{pixel_id}/events",
        "status": 200,
        "ok": true,
        "request_id": "fb_req_123"
      },
      "implementation": {
        "mode": "server_gtm",
        "note": "This project does not fire fbq directly. Meta Purchase is dispatched server-side through GTM."
      }
    }
  }'

URL-only partner postbacks are useful when an affiliate network can only call a tracking URL. Keep server event secrets out of browser code and rotate postback tokens if a URL is exposed. 

https://track.sargetrack.app/v2/postback/{siteEnvironmentId}/{postbackToken}?event=affiliate.conversion&click_id=click_123&order_id=order_123&value=42.50&currency=USD&aff=partner-42

Verify installation

  1. Open the target site in a browser.
  2. Open the Sarge portal and select the matching environment tab.
  3. Trigger the page, product, cart, checkout, and purchase actions you wired.
  4. Confirm the events appear in the event stream, user/session flow, and debug stream.

For coding-agent verification, create a temporary public stream URL:

https://sargetrack.app/verify/{siteEnvironmentId}?key={temporaryVerificationKey}