HTTP Events API

The Zaraz HTTP Events API allows you to send information to Zaraz from places that cannot run the Web API, such as your server or your mobile app. It is useful for tracking events that are happening outside the browser, like successful transactions, sign-ups and more. The API also allows sending multiple events in batches.

​​ Configure the API endpoint

The API is disabled unless you configure an endpoint for it. The endpoint determines under what URL the API will be accessible. For example, if you set the endpoint to be /zaraz/api, and your domain is example.com, requests to the API will go to https://example.com/zaraz/api.

To enable the API endpoint:

1. Log in to the Cloudflare dashboard Open external link , and select your account and domain.
2. Go to Zaraz > Settings.
3. Under Endpoints > HTTP Events API, set your desired path. Remember the path is relative to your domain, and it must start with a /.

​​ Send events

The endpoint you have configured for the API will receive POST requests with a JSON payload. Below, there is an example payload:

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      }
    }
  ]
}

The payload must contain an events array. Each Event Object in this array corresponds to one event you want Zaraz to process. The above example is similar to calling zaraz.track('transaction successful', { value: "200" }) using the Web API.

The Event Object holds the client object, in which you can pass information about the event itself. Every key you include in the Event Object will be available as a Track Property in the Zaraz dashboard.

There are two reserved keys:

• __zarazTrack: The value of this key will be available as Track Name. This is what you will usually build your triggers around. In the above example, setting this to transaction successful is the same as using the Web API and calling zaraz.track("transaction successful").
• __zarazEcommerce: This key needs to be set to true if you want Zaraz to process the event as an e-commerce event.

​​ The system key

In addition to the client key, you can use the system key to include information about the device from which the event originated. For example, you can submit the User-Agent string, the cookies and the screen resolution. Zaraz will use this information when connecting to different third-party tools. Since some tools depend on certain fields, it is often useful to include all the information you can.

The same payload from before will resemble the following example, when we add the system information:

{
  "events": [
    {
      "client": {
        "__zarazTrack": "transaction successful",
        "value": "200"
      },
      "system": {
        "page": {
          "url": "https://example.com",
          "title": "My website"
        },
        "device": {
          "language": "en-US",
          "ip": "192.168.0.1"
        }
      }
    }
  ]
}

For all available system keys, refer to the table below:

​​ Process API responses

For each Event Object in your payload, Zaraz will respond with a Result Object. The Result Objects order matches the order of your Event Objects.

Depending on what tools you are loading using Zaraz, the body of the response coming from the API might include information you will want to process. This is because some tools do not have a complete server-side implementation and still depend on cookies, client-side JavaScript or similar mechanisms. Each Result Object can include the following information:

You do not have to process the information above, but some tools might depend on this to work properly. You can start using the HTTP Events API without processing the information in the table above, and adjust accordingly later.