@dfds-platform/tracking-nodejs

@dfds-platform/tracking-nodejs

Server-side Tracking Framework meant for use in DFDS BFFs or any other NodeJS Application needing DFDS tracking.

There are multiple advantes of using server-side tracking over client-side:

Advantage

There are multiple advantes of using server-side tracking over client-side:

• End to End control of tracking data
• Improved GDPR compliance
• Stay unaffected by tracking prevention
• Improved application performance
• Improved tracking data quality

Disadvantages

However, there are few disadvanteges as well:

• Data tracked server side cannot be passed into the tools only supporting client side approach such as HotJar and tools using AD pixels.
• Data tracked server side is not auto collecting information from the browser such as utm tags, page details, ip address, user agent etc.

Installation

Install with npm:

npm install --save @dfds-platform/tracking-nodejs

Install with yarn:

yarn add @dfds-platform/tracking-nodejs

How to use

The module exposes a method that creates Segment client, which you need to initialize with your Segment source’s write key, like so:
⚠️ You must use different Segment write keys for development, staging and production environments ⚠️

import { segmentClient } from '@dfds-platform/tracking-nodejs'

const client = segmentClient({
    writeKey: 'YOUR_WRITE_KEY',
})

Configuration

Only writeKey property is required, other configuration properties are optional.

If no other configuration is passed to segmentClient then the default configuration will be used. However, you can always overwrite it providing your own config settings.

Default configuration will create Segment client with the following settings that can be overwritten if necessary:

const client = segmentClient({
    writeKey: 'YOUR_WRITE_KEY',
    flushAt: 1,
    flushInterval: 1000,
    enableFlush: true,
    disableAnonymousTraffic: true,
    enableAnonymousIdAutoGeneration: false,
})

flushAt Number	The number of messages to enqueue before flushing.
flushInterval Number	The number of milliseconds to wait before flushing the queue automatically.
enableFlush Boolean	Enable (default) or disable flush. Useful when writing tests and you do not want to send data to Segment Servers.
disableAnonymousTraffic Boolean	Disable (default) or enable tracking of anonymous users (users without permanent dfds user id)
enableAnonymousIdAutoGeneration Boolean	Disable (default) or enable auto generation of anonymous uuid. Only relevant if anonymous user tracking is enabled and it is impossible to pass existing anonymous user id

Identify User

identifyUser lets you tie a user to their actions and record traits about them. It includes a unique User ID and/or anonymous ID, and any optional traits you know about them.

You should call identifyUser once when the user’s account is first created, and then again any time their traits change.

client.identifyUser({
    anonymous_id: 'ANONYMOUS_ID',
    user_id: 'DFDS_USER_ID',
    traits: {
        booking_engine: 'dotcom',
        business_area: 'logistics',
        email: 'USER_EMAIL',
    },
    context: {
        consent: {
            all_cookies_accepted: true,
            cookie_category_preferences: {
                consent_cookie_functional: true,
                consent_cookie_marketing: true,
                consent_cookie_necessary: true,
                consent_cookie_statistic: true,
            },
        },
        page: {
            path: '/en/logistics-solutions/book-and-track-online/direct/bookings',
            referrer: '',
            search: '',
            title: 'DFDS Direct',
            url: 'https://www.dfds.com/en/logistics-solutions/book-and-track-online/direct/bookings',
        },
        ip: '193.9.230.100',
        userAgent:
            'Mozilla/5.0 (iPhone; CPU iPhone OS 15_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.3 Mobile/15E148 Safari/604.1',
    },
})

You can use anonymous_id and/or user_id to identify a user and update user traits, but keep in mind that anonymous_id is cookie based, therefore it is highly recommended to not use it when identifying users.

⚠️ Try to always attach both anonymous_id (which you should get from a client application) and user_id when identifying a user. This will allow to attach a permanent id to an anoymous user tracking session / history ⚠️

The identifyUser call accepts the following fields:

user_id String, optional	The DFDS user ID for this user. Note: at least one of user_id or anonymous_id must be included in any identifyUser call.
anonymous_id String, optional	An ID associated with the user when you don't know who the user is. This ID is generated by segment client side library and saved in a user's browser. So it is higly recommended to get this id from a client whenever possible.
traits Object, optional	A dictionary of traits you know about the user. Things like: email, business_area, first_name. You must always pass required traits and pass as many optional traits as possible.
timestamp Date, optional	A Javascript date object representing when the identifyUser took place. If the identify just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure to send a timestamp.
context Object, optional	A dictionary of extra context to attach to the call. Note: context differs from traits because it is not attributes of the user itself.
integrations Object, optional	A dictionary of destinations to enable or disable. This is relevant if you don't want to send events to all destinations connected to Segment source, but instead only send events to the destinations specified in the integrations object.

Track Event

trackEvent lets you record the actions your users perform. Every action triggers what we call an “event”, which can also have associated properties.

You’ll want to track events that are indicators of success for your site, like Booking Created, User Logged In or Cart Abandoned.

trackEvent is a collection of predefined methods allowing you to only track specific events. If you are missing an event from that collection then please inform Experience Orchestration team and we will add it.

client.trackEvent.formSubmitted({
    anonymous_id: 'ANONYMOUS_ID',
    user_id: 'DFDS_USER_ID',
    properties: {
        booking_engine: 'dotcom',
        business_area: 'logistics',
        form_id: 'form_id',
        form_name: 'form_name',
        ga_client_id: 'ga_client_id',
        locale: 'da-DK',
        page_id: 'page_id',
        status: 'success',
        additional_payload: {
            weather_type: 'sunny',
        },
    },
    context: {
        consent: {
            all_cookies_accepted: true,
            cookie_category_preferences: {
                consent_cookie_functional: true,
                consent_cookie_marketing: true,
                consent_cookie_necessary: true,
                consent_cookie_statistic: true,
            },
        },
        page: {
            path: '/en/logistics-solutions/book-and-track-online/direct/bookings',
            referrer: '',
            search: '',
            title: 'DFDS Direct',
            url: 'https://www.dfds.com/en/logistics-solutions/book-and-track-online/direct/bookings',
        },
        ip: '193.9.230.100',
        userAgent:
            'Mozilla/5.0 (iPhone; CPU iPhone OS 15_3_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/15.3 Mobile/15E148 Safari/604.1',
    },
})

You can attach anonymous_id and/or user_id to a trackEvent call (at least one id is required).

⚠️ Try to always attach both anonymous_id (which you should get from a client application) and user_id when tracking an event. This will allow to attach a permanent id to an anoymous user tracking session / history as well as will allow to continue user tracking session that initially started in a client-side application. ⚠️

The trackEvent call accepts the following fields:

user_id String, optional	The DFDS user ID of a user performing an event. Note: at least one of user_id or anonymous_id must be included in any trackEvent call.
anonymous_id String, optional	An ID associated with the user when you don't know who the user is. This ID is generated by segment client side library and saved in a user's browser. So it is higly recommended to get this id from a client whenever possible.
properties Object, optional	A dictionary of properties for the event including required and optional properties. You must always pass required traits and pass as many optional traits as possible.
timestamp Date, optional	A Javascript date object representing when the trackEvent took place. If the track just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure to send a timestamp.
context Object, optional	A dictionary of extra context to attach to the call. Note: context differs from properties because it is not attributes of the event information itself.
integrations Object, optional	A dictionary of destinations to enable or disable. This is relevant if you don't want to send events to all destinations connected to Segment source, but instead only send events to the destinations specified in the integrations object.

Group User

groupUser lets you associate an identified user with a group. A group could be a company, organization, account, project or team! It also lets you record custom traits about the group, like industry or number of employees.

You can use anonymous_id and/or user_id to attach a user to a group, but keep in mind that anonymous_id is cookie based, therefore it is highly recommended to use user_id holding the value of dfds user id.

⚠️ Try to always attach both anonymous_id (which you should get from a client application) and user_id when doing group calls. This will allow to attach a permanent id to an anoymous user tracking session / history ⚠️

client.groupUser({
    anonymous_id: 'ANONYMOUS_ID',
    user_id: 'DFDS_USER_ID',
    group_id: 'GROUP_UNIQUE_ID',
    traits: {
        booking_engine: 'directportal',
        business_area: 'logistics',
        vat_number: 'DK-1234',
        name: 'DFDS A/S',
        address: {
            country: 'Denmark',
        },
        additional_payload: {
            number_of_employess: 12000,
        },
    },
})

The groupUser call accepts the following fields:

user_id String, optional	The DFDS user ID of a user that is being added to a group. Note: at least one of user_id or anonymous_id must be included in any groupUser call.
anonymous_id String, optional	An ID associated with the user when you don't know who the user is. This ID is generated by segment client side library and saved in a user's browser. So it is higly recommended to get this id from a client whenever possible.
group_id String	The unique ID of the group.
traits Object, optional	A dictionary of required and optional properties you know about the group. You must always pass required traits and pass as many optional traits as possible.
timestamp Date, optional	A Javascript date object representing when the groupUser took place. If the group just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past make sure to send a timestamp.
context Object, optional	A dict containing any context about the request. To see the full reference of supported keys, check them out in the context reference
integrations Object, optional	A dictionary of destinations to enable or disable. This is relevant if you don't want to send events to all destinations connected to Segment source, but instead only send events to the destinations specified in the integrations object.