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.
To start using this feature with the pixel tracker API, you will need to:
- Generate a log token
- Encode your log message
- Send your log message to InsightOps
- Verify the configuration
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:
- Log in to your InsightOps account.
- 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:
- Enter the following command:
encodeURIComponent(btoa("Your log message goes here"));The command returns your encoded log message. For example:
- 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:
1require 'base64'2encoded = Base64.urlsafe_encode64("Your log message goes here")
- 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:
- Build an API call using the following example:
- 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
A functional API call will look similar to the following:
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.