Pixel Tracker

Pixel tracking allows you to capture when a user views a web page or HTML content, which can be helpful for HTML in email campaigns, advertisements, and other features. Pixel tracking is a simple solution for capturing front-end log data and metrics, by embedding a 1x1 pixel transparent image and appending log data to the URL of the image.

Use pixel tracking if you cannot or do not want to use JavaScript for capturing front end metrics.

To start using this feature with the pixel tracker API, you will need to:

Generate a Token

Before you start, you must obtain a log token. Token-based input is a single TCP connection where each log line contains a token which uniquely identifies the destination log.

To obtain a log token:

  1. Log in to your InsightOps account.
  2. Follow the instructions to obtain a TCP log token.

Or, you can use an existing token.

Encode Your Log Message

You should encode the log message to prevent the logs from transforming when appended to the URL. You can quickly achieve this with your browser’s developer console. To encode the log messages:

  1. Open the JavaScript console in your browser. Read about using the Developer console for Chrome here: https://developers.google.com/web/tools/chrome-devtools/console/
  2. Enter the following command: encodeURIComponent(btoa("Your log message goes here")); The command returns your encoded log message. For example: W91ciBsb2cgbWVzc2FnZXMgZ29lcyBoZXJl
  3. To generate the URLs on the server side, you can use another coding language or framework to generate the encoded log message. Here’s an example using Ruby:
 
1
require 'base64'
2
encoded = Base64.urlsafe_encode64("Your log message goes here")
  1. Paste the final code block into the HTML that the user will see.

Send Data to InsightOps

After you successfully encode the message, you can send it to the InsightOps endpoint using an API call. To send the message with the API:

  1. Build an API call using the following example: https://REGION.js.logs.insight.rapid7.com/v1/logs/TOKEN/?e=LOGMESSAGE
  2. Replace parts of the URL with the appropriate information:
    • REGION is the data center of your InsightOps account (for example, US or AU).
    • TOKEN is the log token.
    • LOGMESSAGE is the base64 encoded string assigned to the ‘?e=’ query parameter

If you do not include this, you will receive an error response for HTTP bad request 3. Embed the URL in an HTML page within an <img> tag.

Functional Example

A functional API call will look similar to the following: https://us.js.logs.insight.rapid7.com/v1/logs/12345-12345-12345-12345?e=W91ciBsb2cgbWVzc2FnZXMgZ29lcyBoZXJl

With the URL in the <img> tag, the entire code will look like the following:

 
1
<html lang="en">
2
  <head>
3
    <title>Pixel tracker example</title>
4
  </head>
5
  <body>
6
    <img src=https://us.js.logs.insight.rapid7.com/v1/logs/12345-12345-12345-12345?e=W91ciBsb2cgbWVzc2FnZXMgZ29lcyBoZXJl/>
7
 </body>
8
</html>

Verify the Configuration

When a user accesses the URL that contains the embedded API call in the image, it will immediately send a log message to InsightOps.

Log in to InsightOps and navigate to the Log Search page to verify that this new log appears.