Convertmax Documentation
Talk to us Get started
Guides

Pixel Tracking

Send Convertmax events from image beacons and first-party pixel hosts.

Copy page
Open in ChatGPT Open with page context Open in Claude Open with page context

Use the pixel endpoints when you need to send Convertmax events from environments where a simple GET request is easier than running JavaScript.

For the full event model and supported event names, see Event Tracking.

Supported endpoints

Convertmax supports both of these pixel-style routes:

  • GET /px/<event_type>
  • GET /pixel

Both return a transparent 1x1 GIF after the event is accepted.

Authentication

Requests sent to the shared Convertmax host support either of these query parameters:

  • key=<api_key>

For branded custom pixel hosts such as https://t.acme.com, Convertmax can infer the account from the host mapping, so no public key is required on the pixel request.

Common query fields

You can pass event data directly in the query string:

  • visitor or uid for the visitor ID
  • session_id or sid for the session ID
  • e for the event name on /pixel
  • data.page, data.title, or other nested data.* fields
  • properties.* for nested custom properties
  • gclid, fbclid, msclk, ttclid, and other click identifiers

Convertmax also accepts a base64-encoded data payload for cases where packing the event into one parameter is easier.

Event name normalization

Pixel requests normalize a few common aliases automatically:

  • page becomes page_view
  • pageview becomes page_view
  • purchase becomes convert
  • add_to_cart becomes add_cart
  • t becomes custom

Basic beacon example

<img
  src="https://event.convertmax.io/px/page_view?key=<api_key>&visitor=visitor_123&session_id=session_abc&data.page=https%3A%2F%2Fexample.com%2Flanding"
  alt=""
  height="1"
  width="1"
/>

Short /pixel example

<img
  src="https://event.convertmax.io/pixel?key=<api_key>&e=pageview&uid=visitor_123&sid=session_abc"
  alt=""
  height="1"
  width="1"
/>

Base64 payload example

<img
  src="https://event.convertmax.io/px/convert?key=<api_key>&data=eyJ2aXNpdG9yIjoidmlzaXRvcl8xMjMiLCJkYXRhIjp7InBhZ2UiOiJodHRwczovL2V4YW1wbGUuY29tL2NoZWNrb3V0In19"
  alt=""
  height="1"
  width="1"
/>

Referrer backfill

If the browser can send a referrer and you want Convertmax to use it as the page URL, add:

process_headers=true

When that flag is present, Convertmax can backfill data.page from the request referrer if you did not already provide page explicitly.

First-party branded pixel hosts

Convertmax can accept pixel requests on a branded host such as:

https://t.acme.com/pixel?e=pageview&uid=123

On these branded pixel requests, the worker can infer the account from the host itself, so you do not need to include key in the URL.

Custom branded pixel domains are configured by the Convertmax team so requests to your tracking host resolve to the correct account automatically.

  • legacy marketing platforms that only support beacon URLs
  • server-rendered pages where you want a no-JavaScript fallback
  • first-party collection on branded subdomains
  • lightweight page-view and conversion pings from constrained environments