Tracking contact events

The Bird CRM offers APIs to identify visitors and track events. If you are going to track events on websites, we strongly recommend using our web SDK which simplifies the process. To track events from multiple sources or on the server-side, please follow this tutorial to enable the tracking API endpoints and send events to Bird CRM.

If you have already installed one of the ecommerce platform connectors like the Shopify connector, the web SDK is automatically installed on your store website. You can skip this tutorial entirely.

Installation

Navigate to the Application settings in the Developer Cloud.
Enable an Application by following the on-screen instructions.
Specify your website domain(s) as the allowed domains if events will be emitted from your website directly. For example:
1. If your website homepage is "https://example.com", use "example.com" as the allowed domain. If there are any subdomains like “shop.example.com”, list them as well.
2. Multiple domains can be specified with commas separating them.
3. If events will be emitted from servers, you can leave the allowed domains empty.
Once enabled, you'll see a config page with a snippet similar to:

<script
  src="https://embeddables.mbirdcdn.net/sdk/v0/bird-sdk.js"
  data-config-url="YOUR_CONFIG_URL"
/>

If you plan to use the API endpoints directly, you just need to remember the config URL in the snippet above. The config is unique to your workspace.

Usage

The typical process of tracking events is to first get the tracking API endpoints and request headers from the config URL, then send the events to Bird CRM.

1. Getting tracking endpoint and headers

Send an HTTP GET request to the config URL to retrieve the workspace-specific tracking information.

Example request:

GET https://api.bird.com/workspaces/ea56259f-3985-4f04-bace-ddc843f12d2c/applications/f181ef50-4d1e-46e8-b401-8b23657062c2/signature/2024-04-08T08-33-12_6240e235a4

Example response:

{
    "workspaceId": "ea28660a-1863-4e21-b976-c3756c8eee77",
    "name": "Website Connector",
    "apiEndpoint": "https://api.bird.com",
    "allowedDomains": [
        "example.com"
    ],
    "tracking": {
        "enabled": true,
        "writeKey": "137f46e8-0996-4dec-85ab-b649066f4f50",
        "endpoint": "https://capture.eu-west-1.api.bird.com/tracking/track",
        "trackAnonymousEvents": false,
        "trackPageViews": true,
        "enqueueAnonymousEvents": false,
        "anonymousTracking": "enqueue"
    },
    "createdAt": "2024-06-14T17:26:57.165Z",
    "updatedAt": "2024-06-20T11:30:42.679Z"
}

You will need the following information from the response in the subsequent steps,

workspaceId
apiEndpoint
tracking.endpoint
tracking.writeKey

We recommend retrieving the config at the beginning of the session and cache the response for the duration of the tracking session.

2. Tracking events

To tell Bird CRM about the actions your users are performing, you can send the events to Bird CRM via the “/track” endpoint retrieved above.

Bird CRM pre-defines a set of commonly used events in different verticals such as ecommerce, called semantic events. These events have a standard schema that is well integrated into the entire platform without any additional work.

Besides semantic events, Bird CRM also accepts custom events to meet different needs. Custom events can have arbitrary properties. There is no need to define the schema for custom events before ingestion. Bird CRM automatically discovers the schema from ingested events. Custom events can be used to trigger journeys and flows, used for message personalization, and for segmentation.

Regardless of whether you are sending semantic events or custom events to Bird CRM, the following properties must exist 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 pre-defined event names in the appendix. Custom events can have arbitrary names as long as they don’t collide with any semantic event names.
identity: The “identity” object tells Bird CRM which contact the event belongs to. One or more identifiers must be provided. The identifiers will be used to look up the contact in the order presented. The first identifier that matches a contact’s identifier will determine the contact the event will be associated with. Common identifiers to use in events are external user ID or email address. For email address, the identifier key must be “emailaddress” and the value is the actual email address. Phone numbers are generally not a good identifier unless they uniquely identify a contact and are used as contact identifiers already. In that case, the identifier should be “phonenumber”.
messageId: The message ID at the end can be any string as long as they uniquely identify the event across all events in the workspace. A UUID works well here.

The following subsections describe how to send semantic events and custom events to Bird CRM.

Semantic events

Here’s a call to track a page view event of an identified user with the email address “john@example.com”.

POST {tracking.endpoint}

HTTP Headers:
Origin: https://example.com
Content-Type: application/json
X-Bird-Event-Name: web/page-viewed
X-Bird-Sdk-Version: 0.0.1
X-Bird-Workspace-Id: {workspaceId}
X-Bird-Write-Key: {tracking.writeKey}

Request Body:
{
    "timestamp": "2024-06-23T19:12:39.440Z",
    "event": "web/page-viewed",
    "type": "track",
    "identity": {
        "resolutionStrategy": "lookup",
        "entityType": "contact",
        "identifiers": [{
            "key": "emailaddress",
            "value": "john@example.com"
        }]
    },
    "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"
}

Replace the “tracking.endpoint”, “contactId”, “workspaceId”, and “tracking.writeKey” with the values retrieved from the steps above.

The event name must be one of the semantic event names defined in the appendix.

Custom events

Here’s a call to track a custom event called “Book Read” of an identified user with the email address “john@example.com”. Note that the event name in the HTTP request header must be set to “custom”.

POST {tracking.endpoint}

HTTP Headers:
Origin: https://example.com
Content-Type: application/json
X-Bird-Event-Name: custom
X-Bird-Sdk-Version: 0.0.1
X-Bird-Workspace-Id: {workspaceId}
X-Bird-Write-Key: {tracking.writeKey}

Request Body:
{
    "timestamp": "2024-06-23T19:12:39.440Z",
    "event": "Book Read",
    "type": "track",
    "identity": {
        "resolutionStrategy": "lookup",
        "entityType": "contact",
        "identifiers": [{
            "key": "emailaddress",
            "value": "john@example.com"
        }]
    },
    "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"
}

Replace the “tracking.endpoint”, “contactId”, “workspaceId”, and “tracking.writeKey” with the values retrieved from the steps above.

Nested event properties are supported no more than five levels deep.

Sending custom events is much simpler when using our SDKs. Once your preferred SDK has been properly initialized by following these guides, you can just call the track method directly with your custom event and properties, for example using the web SDK:

Bird.tracker.track("my-event", { "event_property": "value" })

Once you start to track events of identified users, you can verify that they are correctly recorded by checking the contact activity timeline on the contact detail page in Bird CRM.

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

For more information on supported semantic event types, please refer to BirdTracker.

Last updated 1 month ago