Tracking Pixel API
Tracking pixels (aka beacon, 1×1 gif, or clear gif) allow for tracking email opens, advertising impressions and checkout pages where JavaScript and POST requests are disallowed, but where you can embed an image.
Follow Segment’s HTTP Tracking API to use the /pixel API endpoint, which accepts base64 encoded url ?data and returns an 1x1 transparent gif.
Pixel API endpoint signature:
https://api.segment.io/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>
The base64 encoding is optional, however it prevents special character interpretation or muxing by browsers, or other tools that might interpret URLs. For example, the URL https://www.example.com/ might be altered to http%3A%2F%2Fwww.example.com when appended to another URL, but the base64 version, aHR0cHM6Ly93d3cuZXhhbXBsZS5jb20, remains unchanged.
Pixel Routes
/v1/pixel/identify
/v1/pixel/group
/v1/pixel/alias
/v1/pixel/page
/v1/pixel/screen
/v1/pixel/track
Each endpoint always responds with a 200 <empty-gif>, even if an error occurs.
Example Email Opened event:
Create the payload:
{
"writeKey": "YOUR_WRITE_KEY",
"userId": "user_123",
"event": "Email Opened",
"properties": {
"subject": "The Electric Daily",
"email": "jane.kim@example.com"
}
}
Note: you must include either a userId or anonymousId with every API call.
Encode it using base64 and make sure it’s URL safe:
Protip: You can accomplish this with WindowBase64 methods:
eyJ3cml0ZUtleSI6ICJZT1VSX1dSSVRFX0tFWSIsICJ1c2VySWQiOiAiMDI1cGlrYWNodTAyNSIsICJldmVudCI6ICJFbWFpbCBPcGVuZWQiLCAicHJvcGVydGllcyI6IHsgICAic3ViamVjdCI6ICJUaGUgRWxlY3RyaWMgRGFpbHkiLCAgICJlbWFpbCI6ICJwZWVrQXRNZUBlbWFpbC5wb2tlIiB9fQ
Add an image tag to your email newsletter with src pointing to a Pixel API route:
<img src="https://api.segment.io/v1/pixel/track?data=eyJ3cml0ZUtleSI6ICJZT1VSX1dSSVRFX0tFWSIsICJ1c2VySWQiOiAiMDI1cGlrYWNodTAyNSIsICJldmVudCI6ICJFbWFpbCBPcGVuZWQiLCAicHJvcGVydGllcyI6IHsgICAic3ViamVjdCI6ICJUaGUgRWxlY3RyaWMgRGFpbHkiLCAgICJlbWFpbCI6ICJwZWVrQXRNZUBlbWFpbC5wb2tlIiB9fQ">
This page was last modified: 08 Mar 2022
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!