Form tracking: Server Side Analytics APIs

Updated by Patrick Madsen

Please only implement the scripts below IF you are currently using the legacy version 1.0 of Dreamdata's Web Tracking script. Otherwise, we recommend using the new Web Tracking script, version 2.0, which has built-in support for form tracking, intent sources and other integrations.

This article describes how to set up the server-side tracking APIs. This allows developers to send Dreamdata events from their backend code.

Authenticate with the Tracking API

  1. Obtaining Your API Key:
    1. Access the Data Platform: Navigate to Data Platform > Sources > Server Side Analytics to find your API Key.
  2. Formatting and Encoding Your API Key:
    1. Prepare the API Key: Append a colon to your API Key (e.g., abc123:) to signify an empty password.
  3. Encode the API Key:
    1. Base64 encode your API Key.
    2. Enter your API Key followed by a colon and click Encode.
  4. Include in Your Request:
    1. Use the encoded API Key in the Authorization header as Basic {encoded_string}.

Example:

API Key: abc123:

Encoded: YWJjMTIzOg==

HTTP Header:

Content-Type: application/json
Authorization: Basic YWJjMTIzOg==

Include this header in your HTTP requests to access the Tracking API.

POST https://api.dreamdata.cloud/v1/batch

Payloads: Track & Identify

The endpoint only supports batch events of up to 500kb worth of data (the total size of the body of the request). The below example shows how to construct such a request with an a couple of identify and track events in it:

The timestamp needs to be UTC timezone, and format is RFC3339 YYYY-MM-DDTHH:MM:SSZ
{
  "messageId": "6f47f5a0-4118-42de-9e15-95cf9ed2a426",
  "sentAt": "2015-12-02T00:30:08.276Z",
  "batch": [
    {
      "type": "identify",
      "messageId": "6ad2be86-6d78-43bd-8a5b-846ddbc042c2",
      "userId": "019mr8mf4r",
      "traits": {
        "email": "jake@yahoo.com",
        "name": "Jake Peterson",
        "age": 26
      },
      "context": {
        "ip": "24.5.68.47",
        "library": {
          "name": "customer",
          "version": "v1"
        },
        "campaign": {
          "name": "my_campaign",
          "source": "demo",
          "medium": "calendly",
          "term": "",
          "content": ""
        }
      },
      "timestamp": "2012-12-02T00:30:08.276Z"
    },
    {
      "type": "track",
      "messageId": "3f8236bc-c010-43bb-a341-cd30b5228e9d",
      "userId": "019mr8mf4r",
      "event": "Song Played",
      "properties": {
        "name": "Fallin for You",
        "artist": "Dierks Bentley"
      },
      "context": {
        "ip": "24.5.68.47",
        "page": {
          "referrer": "http://localhost:3000/test",
          "url": "http://localhost:3000/test/path?param=a088fb06-a208-4552-b4b7-28fb7f95aeaf"
        },
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36",
        "campaign": {
          "name": "my_campaign",
          "source": "demo",
          "medium": "calendly",
          "term": "",
          "content": ""
        }
      },
      "timestamp": "2012-12-02T00:30:12.984Z"
    }
  ]
}

Endpoint

To send a list of events to the Dreamdata Analytics Serverside APIs send a POST request to the following endpoint. The example uses the example payload from above:

curl -u "abc123:" -X POST https://api.dreamdata.cloud/v1/batch \
  -H 'Content-Type: application/json' \
  -d @example.json

Software Development Kit (SDKs)

Here are the SDKs supported by Dreamdata.

NodeJS SDK

The Node SDK is documented in the public GitHub repository here.

Go SDK

The Go SDK is documented in the public GitHub repository here.

Curl

Combining the above sections into an example payload, and with the above batch payload example written to a file called example.json , the below would be the curl request that would result in those events being tracked by the dreamdata analytics api:

curl -u "abc123:" -X POST https://api.dreamdata.cloud/v1/batch \
  -H 'Content-Type: application/json' \
  -d @example.json

How did we do?