How to Setup a Proxy for Heap

This guide provides steps on how to set up a proxy in your own infrastructure that relays events to Heap. A proxy acts as an intermediary resource between your applications and Heap’s servers, allowing you to first send requests to an internal url, which then get forwarded to the target API endpoints at Heap.

There are various benefits to using a proxy to relay events, including enhanced logging, the ability to execute additional logic on payloads and manipulating the data that gets sent to Heap while it is still in-flight.

This guide will walk you through setting up a demo proxy using the open-sourced NGINX server.

Pre-requisites

This demo applies to the HeapJS 5 tag which can be installed by following the steps in the installation guide .

Proxy deployment steps

The steps involved in setting up a proxy are as follows:

1. Install the Heap tag and register your proxy’s url using the ingestServer property.
2. Set up your proxy, mapping an internal endpoint to Heap’s API.
3. Test your proxy

Tag Installation

Installing the Heap tag to work with a proxy involves two steps. First, install the tag using the standard approach, detailed in our documentation. Then, assuming for instance, you plan to proxy your requests through the local url http://acme.example.com update the heap.load function-call in the tag script, inserting the ingestServer property pointing to your proxy url like in the example below:

This change will handle redirecting the requests sent by the tag to the local url declared in the snippet. To load the heap tag from your own infrastructure, read our documentation on how to setup first-party data collection.

Setting up the Proxy

There are a variety of options available when it comes to setting up proxies within your infrastructure. Cloud providers offer various resources that allow you to relay requests to external servers. This guide will use the open-source NGINX server as an example of how you can set one up.

The code sample below shows what your NGINX configuration file might look like:

user nginx;  
worker_processes auto;  
events {  
    worker_connections 1024;  
}  
http {  
    server {  
        listen 80;  
        root /usr/share/nginx/html;  
        index index.html;  
        # Forward all other requests to the API endpoint  
        location /heap {  
            proxy_set_header X-Real-IP $http_x_forwarded_for;  
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  
            proxy_set_header X-Forwarded-Host $server_name;  
            # Remove the "/heap" prefix from the URL  
            rewrite ^/heap(/.\*)$ $1 break;  
            proxy_pass <https://c.us.heap-api.com>;  
        }  
        # Serve index.htm for base URLs"  
        location / {  
            try_files $uri $uri/ /index.html;  
        }  
    }  
}

In the example above, requests received at the base url for the proxy with the path /heap appended, will forward requests to Heap’s APIs.

Testing the Proxy

To test the proxy, send a cUrl request to the proxy url as shown in the following example:

curl -X POST 'http\://acme.example.com/api/capture/v2/identify'  
-H 'Content-Type: application/json'  
-d '{  
    "env_id": "<YOUR ENV_ID>",  
    "user_id": "0000000000000",  
    "identity": "00000000000000",  
    "time": "2024-12-03T16:04:26.979Z"  
}'

Code Sample

The code samples used in this guide are available in a Github repository linked here. The repository contains a Dockerfile which when built deploys a proxy and a test page that will send requests through your proxy to Heap’s APIs.