Tracking events server side with JavaScript

[khromov]

👋 Wanted to share this JS/TS module I wrote for tracking events on the server side.

It was a little fiddly to get working, as I noticed that tracking requests to Umami requires a "non-bot" user-agent (as defined by the isbot npm package).

The limitations of the module is kind of what you expect - it does not support a concept of "session" (ie. x-umami-cache) so each request will generate a new session. I think this could perhaps be improved (one session for the whole server to not have to generate new sessions all the time?) The big point of sending events server side for me was to not track individual users and instead only aggregate usage numbers.

I welcome suggestions and improvements!

Usage

Pageview:

trackRequest('pageview', {
	url: '/hello-world',
}, userAgent);

Event:

trackRequest('event', {
	url: '/hello-world',
	event_name: 'liked-post',
}, userAgent);

(userAgent is optional, you can send it if you have access to it in your environment, otherwise a standard user agent will be used for all requests)

The module:

const UMAMI_HOSTNAME = 'localhost'; // Your sites root domain
const UMAMI_SERVER = 'https://your-server.com';
const UMAMI_SITE =  'aaaaaaaa-aaaa-aaaa-aaa-aaaaaaaaaaaa';

type PayloadType = 'pageview' | 'event';

interface Payload {
    language?: string, // Eg: en-US
    referrer?: string, // Full url or "" if empty
    screen?: string, // Eg. 414x986
    url: string // Without domain. Eg. /settings
    event_name?: string,
    // website: string // UUID for the site
    // hostname: string, // Eg. localhost
}

/**
 * This is needed to prevent bot detection check that prevents the request from being tracked in case we don't pass a user agent
 * You can also set DISABLE_BOT_CHECK=true in your umami environment to disable the bot check entirely:
 * https://github.com/umami-software/umami/blob/7a3443cd06772f3cde37bdbb0bf38eabf4515561/pages/api/collect.js#L13
 */
const DEFAULT_USER_AGENT = 'Mozilla/5.0 (iPhone; CPU iPhone OS 13_2_3 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.3 Mobile/15E148 Safari/604.1';

/**
 * Tracks the request in Umami
 * Screen and language is not possible to get from the client without JavaScript
 */
export const trackRequest = async (type: PayloadType = 'pageview', payload: Payload, userAgent: string | null = null) => {
    const { language = 'en-US', screen = '1024x1024', url, referrer = '', event_name } = payload;

    if (!url) {
        console.warn('Error: Tracking payload sent without url', url);
        return null;
    }

    const response = await sendRequest(
        {
            type,
            payload: {
                website: UMAMI_SITE,
                hostname: UMAMI_HOSTNAME,
                language,
                screen,
                url,
                referrer,
                event_name: event_name ?? undefined,
            },
        },
        userAgent,
    );

    return response;
}

export const sendRequest = async (
    data: object,
    userAgent: string | null,
) => {
    const controller = new AbortController();
    const signal = controller.signal;

    const timeoutPromise = setTimeout(() => {
        console.error('💣 Request timed out, aborting!');
        if (controller) {
            controller.abort('The request timed out.');
        }
    }, 5000);

    let response;
    try {
        response = await fetch(`${UMAMI_SERVER}/api/collect`, {
            signal,
            method: 'POST',
            body: JSON.stringify(data),
            headers: {
                'content-type': 'application/json',
                'user-agent': userAgent ?? DEFAULT_USER_AGENT,
                // This is set by umami to keep track of the user, it's a JWT token that contains the sessionUuid and websiteUuid
                // 'x-umami-cache': 'NOT-IMPLEMENTED',
            }
        });

        // Clean up the timeout after we received the data
        clearTimeout(timeoutPromise);

        const responseData = await response.text();

        return {
            status: response?.status,
            ok: response.ok ? true : false,
            data: responseData,
        };
    } catch (e) {
        console.log('Error when fetching data', e);

        // Clear timeout as there was an error
        clearTimeout(timeoutPromise);

        return {
            status: response?.status,
            ok: false,
            message: `${e}`
        };
    }
};