Articles in this section

Image pixel tracking

Claudio Kerekes
  • Updated
Follow

Epica Pixel Tracking allows you to capture user events by using emails or messaging services that allow you to embed images with HTML.

Thanks to this we can recognize which users opened a mail, on what date, which campaign it belongs to and more valuable information of each user.

We have some API URLs to collect different types of events as follows: 

Endpoint

/api/v1/pixel/page for getting Page events

/api/v1/pixel/identify for getting Identify events

/api/v1/pixel/track for getting Track events
Method GET

Response example

 Status 200 + 1x1 image/gif
Description

Pixel API endpoint signature:

https://cat.poder.io/api/v1/pixel/<METHOD ENDPOINT>?data=<base64-ENCODED-JSON>

Example of the data:

{
  "writeKey": "YOUR_WRITE_KEY",
  "anonymousId": "8d5e0e0c-555f-11e9-8647-d663bd873d93",
  "event": "Email Opened",
  "properties": {
    "subject": "The Electric Daily",
    "email": "peekAtMe@email.poke"
  }
}

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.

Important! These endpoints are exposed to https://cat.poder.io/ domain. 

 

The pixel endpoint supports two approaches for params handling:

  • Params can be passed as JSON object converted into a string and encoded with base64,
  • query params in dot notation like 'context.page.url'. This approach becomes handy in case of tracking AMP and email opens.

When properties are sent as query params in dot notation like 'context.page.url', EPICA converts them into an event JSON object. For example, the following page request would be converted into a JSON object like this:

https://cat.poder.io/api/v1/pixel/page?writeKey=aaf9sdadkfas9dfa9sdfa \
&name=About%20us \
&anonymousId=507f191e810c19729de860ea \
&context.library.name=amp \
&context.locale=nl-NL \
&context.page.path=%2Fabout%2F \
&context.page.url=https%3A%2F%2Fepica.ai%2Fabout%2F \
&context.page.referrer=https%3A%2F%2Fepica.ai%2F \
&context.page.title=About%20us \
&context.screen.width=320
Result: 
{
  "writeKey": "aaf9sdadkfas9dfa9sdfa",
  "type": "page",
  "name": "About us",
  "anonymousId": "507f191e810c19729de860ea",
  "context": {
    "library": {
      "name": "amp"
    },
    "locale": "nl-NL",
    "page": {
      "path": "/about/",
      "referrer": "https://epica.com/",
      "title": "About us",
      "url": "https://epica.com/about/"
    },
    "screen": {
      "width": "320",
      "height": "568"
    }
  }
}
 

Examples

  • Track event pixel
https://cat.poder.io/api/v1/pixel/track?writeKey=TEST_WRITE_KEY&anonymousId=8d5e0e0c-555f-11e9-8647-d663bd873d93&event=Email%20Opened
 
  •  Track event pixel with properties
https://cat.poder.io/api/v1/pixel/track?writeKey=TEST_WRITE_KEY&anonymousId=8d5e0e0c-555f-11e9-8647-d663bd873d93&event=Category%20viewed&properties.name=Diapers

 

  • Identify Event
https://cat.poder.io/api/v1/pixel/identify?writeKey=TEST_WRITE_KEY&anonymousId=8d5e0e0c-555f-11e9-8647-d663bd873d93&userId=user_example@gmail.com&traits.email=user_example@gmail.com
 
 

Encode your URL

You can script this data from the user's eyes. For that, you can use base 64 encode to encrypt the data of your URL
1. First of all, you need to create a JSON code with the data like this:
 
{
 "writeKey": "YOUR_WRITE_KEY",
 "userId": "025pikachu025",
 "event": "Email Opened",
 "properties": {
 "subject": "The Electric Daily",
 "email": "peekAtMe@email.poke"
 }
}
 
2. Next, you need to encode this JSON using base 64 encode. The result if a string that you must include it in the URL like this: 
 
ewogICJ3cml0ZUtleSI6ICJURVNUX1dSSVRFX0tFWSIsCiAgInVzZXJJZCI6ICIwMjVwaWthY2h1MDI1IiwKICAiZXZlbnQiOiAiRW1haWwgT3BlbmVkIiwKICAicHJvcGVydGllcyI6IHsKICAgICJzdWJqZWN0IjogIlRoZSBFbGVjdHJpYyBEYWlseSIsCiAgICAiZW1haWwiOiAidXNlcl9leGFtcGxlQGdtYWlsLmNvbSIKICB9Cn0=
 
3. After that, you need to compose the URL with this string like this: 
 
https://cat.poder.io/api/v1/pixel/track?writeKey=TEST_WRITE_KEY&data=ewogICJ3cml0ZUtleSI6ICJURVNUX1dSSVRFX0tFWSIsCiAgInVzZXJJZCI6ICIwMjVwaWthY2h1MDI1IiwKICAiZXZlbnQiOiAiRW1haWwgT3BlbmVkIiwKICAicHJvcGVydGllcyI6IHsKICAgICJzdWJqZWN0IjogIlRoZSBFbGVjdHJpYyBEYWlseSIsCiAgICAiZW1haWwiOiAidXNlcl9leGFtcGxlQGdtYWlsLmNvbSIKICB9Cn0=
 
4. Now you can use this URL as an image and put it in your email: 
<img src="https://cat.poder.io/api/v1/pixel/identify?writeKey=TEST_WRITE_KEY&data=RewogICJ3cml0ZUtleSI6ICJURVNUX1dSSVRFX0tFWSIsCiAgInVzZXJJZCI6ICJjaW5keV9jYXN0aWxsb0BnbWFpbC5jb20iLAogICJldmVudCI6ICJFbWFpbCBPcGVuZWQiLAogICJ0cmFpdHMiOiB7CiAgICAiZmlyc3ROYW1lIjogIkNpbmR5IiwKICAgICJlbWFpbCI6ICJwZWVrQXRNZUBlbWFpbC5wb2tlIgogIH0KfQ=="/>
 

UUID

Allways you need the "anonymousId" for each API URL. You must generate the universal unique identifier for each URL you use in each user. Otherwise, it won't work.
 
 

Related articles

Comments

0 comments

Please sign in to leave a comment.