Image Beacon

Sometimes you want to track events that happen in a place where you can’t really run your own code. One example of this is tracking email events. For example, how do you know when an email you’ve sent has been read? And how can you track an event when somebody clicks on a link in your email? Keen IO makes this possible by supporting a few common methods for tracking data online:

An image beacon is simply a 1 pixel by 1 pixel transparent image that you inject into the HTML being rendered by some client. The key is that the source of the image is the Keen IO API. When the client requests the correct API URL, the API will return the correct image data, and also track an event in Keen IO, just as POSTing an event through our normal REST API would do.

How Do I Use It?

Pretty easily, hopefully! There’s two important parts to creating an image beacon URL:

  1. The image URL needs to include a query string parameter called data. This parameter should contain the base 64 encoded JSON string of the event you want to track. Here’s what your event JSON might look like prior to encoding it. Use any property names and any number of properties you want!

    {
    "campaign": "Awesome analytics!",
    "subject": "Hi",
    "text": "Image beacons are fun."
    }
    
  2. The URL also needs to include the name of the collection where you would like to store the click events. You can name it anything you want. Here’s an example URL if you wanted to track an event in a collection called email_opened:

    https://api.keen.io/3.0/projects/PROJECT_ID/events/email_opened?api_key=WRITE_KEY&data=
    

So, in HTML, you’d do something like:

<html>
    <body>
        <img src="https://api.keen.io/3.0/projects/PROJECT_ID/events/email_opened?api_key=WRITE_KEY&data=<base64_data_here>"></img>
    </body>
</html>

This would result in an event being written to the email_opened collection!