Track events

In this section, we’ll explain how to track both semantic events and custom events. To illustrate, let’s assume the following JSON represents the configuration obtained in the previous step, Get Configuration.

{
    "applicationId": "4640861f-f29b-48b6-8baa-a0f23249cf77",
    "workspaceId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
    "apiEndpoint": "https://api.bird.com",
    "allowedDomains": [
        "myapplication.com"
    ],
    "allowedAppBundles": [
        ""
    ],
    "tracking": {
        "connectorId": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "enabled": true,
        "writeKey": "a1405560-c8d3-4b1a-877d-3f449ad95352",
        "endpoint": "https://capture.eu-west-1.api.bird.com/tracking/track",
        "trackPageViews": true,
        "anonymousTracking": "enqueue",
        "trackLifecycleEvents": true
    },
    "pushNotifications": {
        "enabled": false,
        "connectorId": "00000000-0000-0000-0000-000000000000",
        "endpoint": "https://capture.eu-west-1.api.bird.com/push-notifications"
    },
    "appInbox": {
        "enabled": false,
        "connectorId": "00000000-0000-0000-0000-000000000000",
        "channelId": "00000000-0000-0000-0000-000000000000",
        "endpoint": "https://capture.eu-west-1.api.bird.com/ app-inbox"
    }
}

To inform our platform about the actions your users are performing, send the events to the tracking.endpoint endpoint retrieved in the response above. Whether you are sending semantic events or custom events to Bird CRM, the following properties must be included at the top level of the event object:

{
    "timestamp": "event-timestamp",
    "event": "event-name",
    "type": "track",
    "identity": {
        "resolutionStrategy": "lookup",
        "entityType": "contact",
        "identifiers": [{
            "key": "identifier-key",
            "value": "identifier-value"
        }]
    },
    "properties": {},
    "context": {},
    "messageId": "unique-message-ID"
}

• event: For semantic events, the event names must match the predefined names listed in the appendix. Custom events can have any name, as long as it doesn't conflict with any semantic event names.

• messageId: The message ID should be a unique string that helps identify the event within the workspace. A UUID is a good option for this.

• identity: The identity object indicates which contact the event is associated with. You must provide one or more identifiers, which will be used to search for the contact in the order presented. The first matching identifier will determine the contact. Common identifiers include external user ID or email address. If using an email address, the identifier key must be "emailaddress", and the value should be the actual email address. Phone numbers are generally not ideal identifiers unless they uniquely identify a contact and are already used as identifiers. In that case, the identifier key should be "phonenumber".

• properties: nested event properties are supported no more than five levels deep.

It’s important to include the following headers when sending POST requests to Bird CRM:

• X-Bird-Event-Name: This header specifies the event type. For more information on supported semantic event types, refer to BirdTracker.

• X-Bird-Sdk-Version: Set this to 0.0.1.

• X-Bird-Workspace-Id: Use the workspace ID retrieved from your configuration.

• X-Bird-Write-Key: Use the write key from the Get Configuration step.

Once you start tracking events for identified users, you can verify that the events are being correctly recorded by checking the contact activity timeline on the contact detail page.

Semantic events

Our platform provides a predefined set of commonly used events, known as semantic events, tailored for various verticals such as e-commerce. These events follow a standard schema that seamlessly integrates across the platform without requiring additional setup.

Below is an example of how to track a page view event for an identified user with the email address "[e-mail]":

curl -X POST https://capture.eu-west-1.api.bird.com/tracking/track \
  -H "Origin: https://example.com" \
  -H "Content-Type: application/json" \
  -H "X-Bird-Event-Name: web/page-viewed" \
  -H "X-Bird-Sdk-Version: 0.0.1" \
  -H "X-Bird-Workspace-Id: a1405560-c8d3-4b1a-877d-3f449ad95352" \
  -H "X-Bird-Write-Key: a1405560-c8d3-4b1a-877d-3f449ad95352" \
  -d '{
    "timestamp": "2024-11-26T15:00:00.000Z",
    "event": "web/page-viewed",
    "type": "track",
    "identity": {
        "resolutionStrategy": "lookup",
        "entityType": "contact",
        "identifiers": [{
            "key": "emailaddress",
            "value": "[e-mail]"
        }]
    },
    "properties": {
        "title": "My website",
        "url": "https://example.com/",
        "path": "/"
    },
    "context": {
        "page": {
            "path": "/",
            "referrer": "",
            "search": "",
            "title": "Flight search page",
            "url": "https://example.com/"
        },
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
        "userAgentData": {
            "brands": [
                {
                    "brand": "Not/A)Brand",
                    "version": "8"
                },
                {
                    "brand": "Chromium",
                    "version": "126"
                },
                {
                    "brand": "Google Chrome",
                    "version": "126"
                }
            ],
            "mobile": false,
            "platform": "macOS"
        },
        "locale": "en-US",
        "timezone": "Europe/Amsterdam"
    },
    "messageId": "bird-tracker-1719169959440-263ca131-f903-45aa-84fe-fb0285af811c"
}'

Custom events

Custom events can include arbitrary properties and don’t require a predefined schema. Our platform automatically infers the schema from ingested events. These events can be used to trigger journeys and flows, personalize messages, and create segments.

To track the custom event called “Book Read” for an identified user with the email "[e-mail]", you need to set the event name in the HTTP request header to "custom". Below is an example of the POST request with the necessary details:

curl -X POST https://capture.eu-west-1.api.bird.com/tracking/track \
  -H "Origin: https://example.com" \
  -H "Content-Type: application/json" \
  -H "X-Bird-Event-Name: custom" \
  -H "X-Bird-Sdk-Version: 0.0.1" \
  -H "X-Bird-Workspace-Id: a1405560-c8d3-4b1a-877d-3f449ad95352" \
  -H "X-Bird-Write-Key: a1405560-c8d3-4b1a-877d-3f449ad95352" \
  -d '{
    "timestamp": "2024-11-26T15:00:00.000Z",
    "event": "Book Read",
    "type": "track",
    "identity": {
        "resolutionStrategy": "lookup",
        "entityType": "contact",
        "identifiers": [{
            "key": "emailaddress",
            "value": "[e-mail]"
        }]
    },
    "properties": {
        "title": "The Art of Computer Programming",
        "author": "Donald E. Knuth",
        "startedAt": "2024-06-01T18:23:44Z",
        "metadata": {
            "volume": "1"
        }
    },
    "context": {},
    "messageId": "1719169959440-263ca131-f903-45aa-84fe-fb0285af811c"
}'

Playground

To help make it easier to test custom event tracking with your workspace, we have built a playground just for this.