Node.js and servers

This page installs Analytics Web (@grainql/analytics-web) on a server and sends events with the SERVER_SIDE strategy. It ends with Express, Fastify, AWS Lambda, and Vercel examples. Grain Tag is for browsers. For a browser install, read Install Grain.

Before you start

You need three things:

Your tenant alias. The dashboard at https://grainql.com/dashboard shows it. It is not the UUID.
A secret key from the dashboard, in the environment variable GRAIN_SECRET_KEY. Read Authentication.
Node.js with fetch, or a serverless runtime.

Do not commit the secret key, and do not ship it in browser code. Anyone who holds the secret key can send events as your tenant.

1. Install the package

npm install @grainql/analytics-web

2. Create the client

Create one client per process, at module scope, and reuse it. In a serverless function, a module-scope client survives across warm invocations.

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!
});

3. Make sure that events arrive

Run this script one time with debug: true in the configuration.

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: process.env.GRAIN_TENANT_ID!,
  authStrategy: 'SERVER_SIDE',
  secretKey: process.env.GRAIN_SECRET_KEY!,
  debug: true
});

await grain.track('installation_test', { timestamp: new Date().toISOString() }, { flush: true });

The console shows the request. The dashboard shows the installation_test event within seconds. If the event does not appear, read Troubleshooting.

4. Track an event

Call track with an event name and a properties object. Analytics Web queues the event and sends the queue every 5 seconds, or when it holds 50 events, whichever comes first.

await grain.track('order_processed', {
  order_id: order.id,
  total: order.total,
  items_count: order.items.length
});

await grain.flush();

Call flush after a batch job, before the process exits. Otherwise the events in the queue are lost. Read Track an event.

5. Identify a user and set properties

identify sets the user ID for every later event. setProperty stores properties on the user.

grain.identify(user.id);

await grain.setProperty({
  email: user.email,
  plan: 'free',
  signup_date: new Date().toISOString()
});

await grain.track('user_signed_up', { method: 'email' }, { flush: true });

Read Identify users and User properties.

6. Read a configuration value

getConfig returns a configuration value from the cache. Every value is a string.

if (grain.getConfig('use_new_algorithm') === 'true') {
  result = await newAlgorithm(data);
} else {
  result = await oldAlgorithm(data);
}

const maxRetries = parseInt(grain.getConfig('max_retries') || '3');

Read Remote configuration.

7. Express

Track every request in a middleware, and flush on SIGTERM.

app.use((req, res, next) => {
  const startTime = Date.now();

  res.on('finish', () => {
    grain.track('api_request', {
      path: req.path,
      method: req.method,
      status: res.statusCode,
      duration: Date.now() - startTime
    });
  });

  next();
});

process.on('SIGTERM', async () => {
  await grain.flush();
  process.exit(0);
});

8. Fastify

Track every response in an onResponse hook, and flush in onClose.

fastify.addHook('onResponse', async (request, reply) => {
  await grain.track('api_request', {
    path: request.url,
    method: request.method,
    status: reply.statusCode,
    duration: reply.getResponseTime()
  });
});

fastify.addHook('onClose', async () => {
  await grain.flush();
});

9. AWS Lambda

Create the client outside the handler. Pass { flush: true } to every track call, so the event leaves before the function stops.

import { Handler } from 'aws-lambda';

export const handler: Handler = async (event, context) => {
  const result = await processEvent(event);

  await grain.track('lambda_invoked', {
    function_name: context.functionName,
    success: true
  }, { flush: true });

  return { statusCode: 200, body: JSON.stringify(result) };
};

10. Vercel

A Vercel function stops after the response. Pass { flush: true } to every track call.

import type { VercelRequest, VercelResponse } from '@vercel/node';

export default async function handler(req: VercelRequest, res: VercelResponse) {
  await grain.track('api_request', { path: req.url, method: req.method }, { flush: true });

  res.json({ success: true });
}

Next steps

Core methods

Every method of both SDKs, with signatures.

Authentication

The three strategies, secret keys, and API keys.

Export and query data

Read events out with the Query API.

Configuration options

Every option of both SDKs, with defaults.

Start here

Install without code

Install with code

Track events

Dashboard

Remote configuration

Guides

React

Advanced

Before you start

1. Install the package

2. Create the client

3. Make sure that events arrive

4. Track an event

5. Identify a user and set properties

6. Read a configuration value

7. Express

8. Fastify

9. AWS Lambda

10. Vercel

Next steps

Core methods

Authentication

Export and query data

Configuration options

​Before you start

​1. Install the package

​2. Create the client

​3. Make sure that events arrive

​4. Track an event

​5. Identify a user and set properties

​6. Read a configuration value

​7. Express

​8. Fastify

​9. AWS Lambda

​10. Vercel

​Next steps

Core methods

Authentication

Export and query data

Configuration options

Before you start

1. Install the package

2. Create the client

3. Make sure that events arrive

4. Track an event

5. Identify a user and set properties

6. Read a configuration value

7. Express

8. Fastify

9. AWS Lambda

10. Vercel

Next steps