@deldico/tracking-client NPM

Deldico Tracking

Deldico Tracking uses fingerprinting technology to identify website visitors and track leads across multiple devices. It is a robust and configurable tracking system that is self-hosted and uses server-side GTM to ensure compliance with GDPR standards. It integrates with Pipedrive and a mailer to keep contacts and leads up-to-date and allows users to register webhooks to pipe events straight to their apps for further processing.

Setup

We have already deployed the necessary servers for the tracking system: a Server-side GTM and a Tracking API. In order to begin using it, you will have to add a JavaScript module to your website that will connect with the GTM dataLayer events, and then deploy the "Server-side tracking" workspace changes to your web GTM container.

Update your GTM containers

You now have two Google Tag Manager (GTM) containers: a web container, which is the script that is injected into the document's <head> section, and a server-side container, which is a replacement for Google's GTM servers. This means that all GTM tracking activities will be taken off of Google servers and put onto your own infrastructure.

Look over and merge all the changes in the "Server-side tracking" workspace. These tags add the Deldico Tracking client and associated events, and they also update existing tags to point to the server-side GTM container.
Update the injected script in your frontend's <head> section to point to your GTM server URL (the container ID stays the same). Use the following code:

  <!-- Google Tag Manager -->
  <script>(function (w, d, s, l, i) {
      w[l] = w[l] || []; w[l].push({
        'gtm.start':
          new Date().getTime(), event: 'gtm.js'
      }); var f = d.getElementsByTagName(s)[0],
        j = d.createElement(s), dl = l != 'dataLayer' ? '&l=' + l : ''; j.async = true; j.src =
              'https://<Your GTM server>/gtm.js?id=' + i + dl; f.parentNode.insertBefore(j, f);
    })(window, document, 'script', 'dataLayer', '<GTM web container ID>');</script>
  <!-- End Google Tag Manager -->
  <!-- Google tag (gtag.js) -->
  <script async src="https://<Your GTM server>/gtag/js?id=<Google Analytics measurement ID>"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag() { dataLayer.push(arguments); }
    gtag('js', new Date());

    gtag('config', '<Google Analytics measurement ID>', {
      transport_url: 'https://<Your GTM server>',
      first_party_collection: true
    });
  </script>
  <!-- End Google tag (gtag.js) -->

After that you may connect analytics to your Facebook Pixel. Be aware that enabling this and leaving the Pixel on your frontend will create duplicated events.

Set “API Access Token”, “Facebook Pixel ID”, and clear "Test ID" in the Facebook Proxy tag in the server container.

Once you set the Facebook Pixel up in GTM, you'll be able to remove it entirely from your frontend (and any related tags in GTM). This is because now your GA4 tag events will be piped directly to your Facebook Pixel through the GTM server.

Install the JavaScript client

You can install the client directly from NPM:

npm install @deldico/tracking-client

Use the following pattern to import and initialize the client in Angular:

import { Component, OnInit } from '@angular/core';
import DeldicoTrackingClient from '@deldico/tracking-client';

const trackingClient = new DeldicoTrackingClient({
  token: '<Your tracking client token>',
  gtmURL: '<Your GTM server URL>',
});

@Component({
  selector: 'app-xyz',
  templateUrl: './xyz.component.html',
  styleUrls: ['./xyz.component.scss'],
})
export class XyzComponent implements OnInit {
  constructor() {}

  ngOnInit(): void {
    // Assuming consent approval. Normally you should set this in a consent banner or form field.
    trackingClient.updateConsent(true, true);

    trackingClient.init().then(() => {
      console.log(trackingClient.fingerprint);
    });
  }
}

The client will fetch the user's device fingerprint and tracking ID on init() and set the appropriate dataLayer variables. This should be done once on page load. Now you’ll be able to use the special tracking dataLayer events, which are described in detail in the Usage section of this document.

Setup webhooks in the API (optional)

The tracking API can push raw event data to your own apps, and all you need to do is register an endpoint through a POST request like below:

curl --location --request POST 'https://<API URL>/webhook' \
--header 'X-Api-Key: <API key>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "<Your webhook endpoint>"
}'

The API will retry sending events to each webhook until it gets a 200 status response.

Usage

Consent

Before sending any events you'll need to configure consent for page visitors. It doesn't matter how you implement this, whether it's a banner or a form field, but tracking will be blocked unless a user gives approval.

You can set the consents for a user with the following method:

  trackingClient.updateConsent(true, true); // Enable both analytics and ads
  trackingClient.updateConsent(false, false); // Disable tracking
  trackingClient.updateConsent(true, false); // Only enable analytics
  
  // Now init the client to get fingerprint and tracking ID
  await trackingClient.init();
  
  // You can also update consent afterwards to block tracking on request

GTM dataLayer

The tracking system is connected to your website through GTM dataLayer events, and requires specific event data to properly track devices and associate them with leads.

Deldico Tracking specific dataLayer fields are: fingerprint, trackingId, event, userData, and metaData.

The JavaScript client will automatically set fingerprint and trackingId on initialization if they are available, but you can always set them yourself later.

Fields

fingerprint: The unique fingerprint ID of the visitor's device. This is the first layer of lead tracking, because a visitor may have a fingerprint but no lead yet. Visitors without leads are still tracked with a generated trackingId.
trackingId: The unique visitor tracking ID. A single trackingId may be associated with multiple fingerprints through the use of the tid UTM link parameter (see UTM links section).
event: Basic dataLayer parameter. Deldico Tracking connected events are described in the Events subsection.
userData: User-submitted form field values. Deldico Tracking is only concerned with name, email, and phone for creating new leads in Pipedrive. All other form fields are passed through (ignored by the API but pushed to webhooks).
Example value:
```
userData: { name: "John Doe", email: "john@doe.com", phone: "12345678" }
```
metaData: Additional information about the event required by the API in order to correctly generate leads and activities. Currently has three possible parameters: context, step (for step completion tracking), and createActivity (to create an activity for the event - if applicable - in Pipedrive).
Example value:
```
metaData: { context: "signup" }
```

Events

You'll need to trigger the following dataLayer events in order to create leads and track visitors. The most important event is new_lead, which generates a lead for a visitor in Pipedrive.

page_visit: Tracks page navigations for visitors and leads.

window.dataLayer.push({
  event: "page_visit",
  // no other data needed,
  // path and page title are automatically extracted
  // UTM parameters are also automatically extracted
  metaData: {
    // leave this out or set to false to avoid
    // spamming information-less lead activities
    // like homepage visits
    createActivity: true
  }
});

new_lead: Creates a lead in Pipedrive if there's no other lead associated with the current visitor. If the metaData.context value is "contact" the lead will be considered warm, and if it's set to "signup" then it will be hot.

window.dataLayer.push({
  event: "new_lead",
  userData: {
    // partial lead data is OK, email is required
    name: "John Doe",
    email: "john@doe.com",
    phone: "12345678"
  },
  metaData: {
    context: "contact", // may be "contact" or "signup"
  },
});

step_completed: Updates leads with partial lead data in the case of split forms (sign up), where email may be present in one step but name in another.

window.dataLayer.push({
  event: "step_completed",
  userData: {
    // partial lead data is OK
    name: "John Doe"
  },
  metaData: {
    context: "signup_form", // any identifier string
    step: stepNumber, // integer
  },
});

conversion: Used for keeping track of conversions in the API for reporting.

window.dataLayer.push({
  event: "conversion",
  metaData: {
    context: "partial", // may be "partial" or "full"
  },
});

Tracking links

In order to associate new fingerprints with existing tracking IDs and leads, visitors need to navigate to your website with tracked links.

Tracking IDs are associated with contacts in both Pipedrive and your mailer, so all you need to do is generate a link with the tracking ID added to the URL in the tid parameter.

Example:

https://yoursite.com?tid=123

Anyone who clicks the above link will have their device fingerprint permanently associated with tracking ID 123 and their lead, if any.

Tracking API

The API exposes some HTTP endpoints to help you manage webhooks and manually send tracking events, if necessary.

Making requests requires authorization using the X-Api-Key header. If you fail to authenticate you will receive a 403 Forbidden response.

GET /webhooks: Returns a list of existing webhook configurations.

curl --location --request GET 'http://localhost:3030/webhooks' \
--header 'X-Api-Key: 1234abcd'

EXAMPLE RESPONSE (json):
{
  "webhooks": [
    {
      "id": 1,
      "url": "https://yoursite.com/yourwebhook",
      "created_at": "2022-11-03 15:57:50",
      "updated_at": "2022-11-03 15:57:50"
    }
  ],
  "ok": true
} - 200

POST /webhooks: Creates a webhook.

curl --location --request POST 'http://localhost:3030/webhooks' \
--header 'X-Api-Key: 1234abcd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://yoursite.com/yourwebhook"
}'

EXAMPLE RESPONSE:
OK - 200

DEL /webhooks: Deletes a webhook.

curl --location --request DELETE 'http://localhost:3030/webhooks' \
--header 'X-Api-Key: 1234abcd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "url": "https://yoursite.com/yourwebhook"
}'

EXAMPLE RESPONSE:
OK - 200

POST /event: Handles an event. Normally called by GTM with appropriate tags, follows the exact same structure as dataLayer pushes.

curl --location --request POST 'http://localhost:3030/event' \
--header 'X-Api-Key: 1234abcd' \
--header 'Content-Type: application/json' \
--data-raw '{
    "fingerprint": "asd31dffgh0jz", 
    "trackingId": "123",
    "path": "/",
    "pageTitle": "",
    "utmCampaign": "",
    "utmSource": "",
    "utmMedium": "",
    "utmTerm": "",
    "utmContent": "",
    "event": "page_visit",
    "timestamp": "2022-11-03T00:00:00",
    "userData": null,
    "metaData": null
}'

EXAMPLE RESPONSE:
OK - 200

Pipedrive integration

The tracking API will create leads on new_lead for visitors without any existing leads, and will update contact info on step_completed events.

Leads are considered warm if the event's metaData.context value is "contact", and hot if the value is "signup". The API assigns labels for the lead according to type.

The API also creates activities for existing lead events to enable behavioural filtering.

Mailer integration

Whenever an event comes in where userData.email is set, the API checks if such a contact/customer exists in your mailer and sets their "Tracking ID" field accordingly.