Skip to content

Server-side events API

Getting Started

Our server-side event API allows you to send customer events from your server (backend) to Tracify .

Integrating will consist of three main steps.

  1. Review the following documentation to familiarize yourself with events Tracify supports and determine which events you would like to track.
  2. Instrument sending of events on customer actions in your application's business logic.
  3. Confirm with your Customer Success Manager that events are being recorded.

Before you get started you'll need an account with Tracify, and your API key. If you don't have an account or API key, please contact your Customer Success Manager.

Supported Events

We support the following events. Evens may be sent individually or in batches.

Event Name When to use
Pageview Trigger when a user visits any page.
Product view Trigger when a user visits a product page.
Add to cart Trigger when a user adds a product to their cart.
Purchase Trigger when a user completes a purchase.
Conversion Trigger when a user completes a conversion.

Event Properties

Events are sent to Tracify as a JSON payload. The following is a description of each possible json field. Not all fields are required for all events (see example payloads below, per event).

url · string

The full URL (domain + path) where the event occurred.

customer_site_id · string

Your customer site ID (CSID). Your account representative will provide this value.

identity_data · object

Tracify tracks customer journeys using anonymized information passed as key-value pairs. Each pair represents a distinct customer identifier. The key for each pair is the is the hashed identity data, and the value is the identity reference value, which is 1, 2, 3, or 4 depending on the type of identity data.

Example keys and values:

Identity data key Identity data value Description
"d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e" 1 Anonymized email address (optional, if available)
"b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6" 2 Anonymized session id. To generate concatenate IP and User Agent with "|" and hash. Ex: "192.168.1.1|Mozilla/5.0"
"e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6" 3 Anonymized IP address (required)
"a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4" 4 Anonymized User Agent (required)

You are required to anonymize any identifying information (email, IP, user-agent, etc.) that you collect before you send it to Tracify. Below you can find examples of the anonymization algorithm in a few different languages.

function calcGroup($dt) {
    $digest = hash('sha256', $dt, false);
    $group = substr($digest, 0, strlen($digest) - 5);
    return hash('sha256', $group, false);
}

import hashlib

def calcGroup(dt):
    digest = hashlib.sha256(dt.encode()).hexdigest()
    group = digest[:-5]
    return hashlib.sha256(group.encode()).hexdigest()

const crypto = require('crypto');

function calcGroup(dt) {
    const digest = crypto.createHash('sha256').update(dt).digest('hex');
    const group = digest.slice(0, digest.length - 5);
    return crypto.createHash('sha256').update(group).digest('hex');
}

def calc_group(dt)
  digest = Digest::SHA256.hexdigest(dt)
  group = digest[0..-5]
  Digest::SHA256.hexdigest(group)
end

datetime · string

The date and time, formatted as %Y-%m-%d %H:%M:%S at which the event occurred. This must be sent in UTC.

type · string

The type of event. See Supported Events for more details.

data · object

Data properties specific to the event type sent.

Property Required Description
Referer If Available The full URL (domain + path) where the event occurred, if available.
origin Required The domain the website, see Origin.
url_parameters Required for first session event Pass each URL parameter as it's own key-value pair within the data object. For example

"trc_mcmp_id": "120206067078490109"
"trc_mag_id": "120206067078690109"
"trc_mad_id": "120206067078730109"
"utm_medium": "paid"
"utm_source": "fb"
order_id Required for purchase events. The order ID associated with the purchase. Must be unique for purposes of depuplication.
conversion_id Required for conversion events. The conversion ID associated with the conversion. Must be unique for purposes of depuplication.
currency Required for purchase and conversion events. The currency used to make the purchase. Please use the appropriate 3-letter ISO-4217 code.
amount Required for purchase and conversion events. The amount of the purchase. Required for purchase events.
ITEM1 Optional for purchase events. The name of the first item in the cart. Optional, for purchase events. For additional items pass as ITEM2, ITEM3 and so on.
AMT1 Optional for purchase events. The amount of the first item in the cart. Optional, for purchase events. For additional items pass as AMT2, AMT3 and so on.
QTY1 Optional for purchase events. The quantity of the first item in the cart. Optional, for purchase events. For additional items pass as QTY2, QTY3 and so on.

Example Payloads

The following are example payloads for each event type. You can use these as a starting point to structure your own event information.

Pageview Event 

{
    "events": [
        {
            "url": "https://www.yourwebsite.com/your-full-path-here",
            "customer_site_id": "00000000-0000-0000-0000-000000000000",
            "identity_data": { 
                "d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e": 1, 
                "b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6": 2, 
                "e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6": 3, 
                "a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4": 4  
            }, 
            "datetime": "2024-06-21 12:36:37",
            "type": "pageview",
            "data": {
                "Referer": "https://www.referringwebsite.com", 
                "origin": "https://www.yourwebsite.com",
                "trc_mcmp_id": "1111111111111111111", 
                "trc_mag_id": "2222222222222222222",
                "trc_mad_id": "3333333333333333333",
                "utm_medium": "paid",
                "utm_source": "fb"
            }
        }
    ]
}

Product View Event 

{
    "events": [
        {
            "url": "https://www.yourwebsite.com/your-full-path-here",
            "customer_site_id": "00000000-0000-0000-0000-000000000000",
            "identity_data": { 
                "d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e": 1, 
                "b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6": 2, 
                "e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6": 3, 
                "a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4": 4  
            }, 
            "datetime": "2024-06-21 12:36:40",
            "type": "productview",
            "data": {
                "Referer": "https://www.referringwebsite.com", 
                "origin": "https://www.yourwebsite.com",
                "trc_mcmp_id": "1111111111111111111", 
                "trc_mag_id": "2222222222222222222",
                "trc_mad_id": "3333333333333333333",
                "utm_medium": "paid",
                "utm_source": "fb"
            }
        }
    ]
}

Add to Cart Event 

{
    "events": [
        {
            "url": "https://www.yourwebsite.com/your-full-path-here",
            "customer_site_id": "00000000-0000-0000-0000-000000000000",
            "identity_data": { 
                "d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e": 1, 
                "b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6": 2, 
                "e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6": 3, 
                "a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4": 4  
            }, 
            "datetime": "2024-06-21 12:36:40",
            "type": "addtocart",
            "data": {
                "origin": "https://www.yourwebsite.com"
            }
        }
    ]
}

Purchase Event 

{
    "events": [
        {
            "url": "https://www.yourwebsite.com/your-full-path-here",
            "customer_site_id": "00000000-0000-0000-0000-000000000000",
            "identity_data": { 
                "d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e": 1, 
                "b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6": 2, 
                "e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6": 3, 
                "a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4": 4  
            }, 
            "datetime": "2024-06-21 12:36:40",
            "type": "purchase",
            "data": {
                "origin": "https://www.yourwebsite.com",
                "order_id": "123456789",
                "currency": "EUR",
                "amount": "100.00", 
                "ITEM1": "Name of Product 1",
                "AMT1": "25",
                "QTY1": "2",
                "ITEM2": "Name of Product 2",
                "AMT2": "50",
                "QTY2": "1"
            }
        }
    ]
}

Conversion Event 

{
    "events": [
        {
            "url": "https://www.yourwebsite.com/your-full-path-here",
            "customer_site_id": "00000000-0000-0000-0000-000000000000",
            "identity_data": { 
                "d6c77f0e3e6c1c276c2e9e6e7e1d8d0a5b4e7c7e3f1e7e7e5d8f7e2e7d5a5d7e": 1, 
                "b4e6a7c8d9e0f1d2c3b4a5e6f7e8d9c0b1a2d3e4f5d6c7e8a9b0c1d2e3f4d5c6": 2, 
                "e7d6c5b4a3b2c1d0e9f8e7d6c5b4a3d2e1f0d9c8b7a6e5d4c3b2a1d0e9f8c7b6": 3, 
                "a5b4c3d2e1f0e9d8c7b6a5d4c3b2e1d0c9b8a7d6e5f4c3b2a1d0e9f8c7b6a5d4": 4  
            }, 
            "datetime": "2024-06-21 12:36:40",
            "type": "conversion",
            "data": {
                "origin": "https://www.yourwebsite.com",
                "conversion_id": "123456789",
                "currency": "EUR",
                "amount": "100.00", 
            }
        }
    ]
}

API Specification

All events are sent to Tracify via a single endpoint (POST request).