Goals and server events

A goal is an outcome you care about: a signup, a purchase, a booked demo.

Two kinds of goal

• Browser goals match an event or a page view, like a click on Buy or a visit to /thanks. They are quick to set up and good for intent.
• Server-confirmed goals count only events your server sends with a secret key. Browser clicks with the same name never count toward them. Use these for money and anything else that must be true.

Each goal definition has a version number, so you can tell when a goal's meaning changed.

Match on event properties

An event goal can also require up to 3 of the event's properties to equal values you choose. A goal on signup.completed with plan equal to pro counts pro signups only. Every condition must hold.

import { track } from '@littlefriend/tracker';

// After the signup really went through
track('signup.completed', { plan: 'pro', seats: 5 });

littlefriend goals create --name "Pro signup" --event signup.completed --prop plan=pro

• In the dashboard, edit an event goal on the Goals page and choose Add a property. With the CLI, repeat --prop key=value for each condition. goals update with --prop replaces the conditions, and --no-props removes them.
• Conditions read the properties Little Friend stored. A property the collector dropped never matches.
• Keys are lowercase snake case, up to 32 characters, each used once. Values are up to 64 characters, with spaces at either end dropped. A value that looks like an email address, phone number or card number is refused, because no event can carry one.
• Values compare as text: seats equal to 5 matches the number 5, and trial equal to true matches true. Capitals count, so Pro matches only Pro.
• Page view goals take no conditions. An event goal without any matches on the event alone.
• Changing the conditions makes a new version of the goal. Counts already made keep the definition they were made with. Session timelines, funnel goal steps and flows use the current one.

Send outcomes from your server

Create a server key in Settings, Keys. It starts with lfs_. Keep it in an environment variable on your server, never in a browser.

From Node.js

@littlefriend/node checks, batches and retries events for you. It needs Node 18.17 or later.

pnpm add @littlefriend/node

import { LittleFriend } from '@littlefriend/node';

const lf = new LittleFriend({ key: process.env.LF_SERVER_KEY! });

// After the payment really went through
lf.track({
  id: 'order_8812', // the same id on a resend counts once
  name: 'purchase',
  props: { plan: 'pro' },
  value: { amount: 4900, currency: 'USD' },
});

Events wait in memory and go out in batches. Call await lf.flush() before a serverless function returns, and await lf.shutdown() before a long-running process exits.

From any other language

Post a batch to /v1/server with your server key as a bearer token. A batch holds up to 50 events.

{
  "v": 1,
  "events": [
    {
      "id": "order_8812",
      "name": "purchase",
      "correlationId": "chk_4f1a9c2e7b3d8a61",
      "value": {
        "amount": 4900,
        "currency": "USD"
      },
      "props": {
        "plan": "pro"
      }
    }
  ]
}

// After the payment really went through
const res = await fetch('https://in.littlefriend.io/v1/server', {
  method: 'POST',
  headers: {
    authorization: `Bearer ${process.env.LF_SERVER_KEY}`,
    'content-type': 'application/json',
  },
  body: JSON.stringify(batch),
});

if (res.status === 429 || res.status === 503) {
  // Busy: wait Retry-After seconds, then send the same batch again
}

Event fields

Responses