Retention

Of the people first seen in a week, how many came back in each week after.

Ask your agent

The same prompt the Retention card hands out under How to add, with your own install command in it. Paste it into your coding agent.

Add UpControl retention to this app: count each person once a week from the week they first appeared. First read npx upcontrol skills retention. Then run npx upcontrol (it saves this project's key to a gitignored .env without printing it). Call seen() with this app's own stable user id wherever the app knows who it is talking to. It must be the same string for the same person every week: never a request, never an address, never a session id or a rotating cookie, or the cohorts fall apart and the churn number is one nobody experienced. If this app has no stable id to give, tell me rather than substituting one. When the app has run once, run npx upcontrol verify.

Build the card

On the dashboard press Add widget, pick Retention, then Next.
Under Event, keep Every event to read everyone the project sends, or pick one event to follow only its people. The name you gave retention() is that event: a person's first one starts their cohort, and the same event in a later week is a return. The list appears once the project has sent events.
Name the card and add it. The grid draws only the cohorts that began inside the window it read.

A weekly retention card: four cohorts of about 400 people, 100% in week 0 falling to 41%, 29%, 24% and 21% in the weeks after — A retention grid: one row per weekly cohort, one column per week since. Sample data.

The one rule: a stable id

seen() takes a string user id and nothing else: never a request, never an address.
It must be the same string for the same person every week, because a cohort is observed over weeks and an address is not the same person a week later.
A session id or a cookie that rotates produces cohorts that fall apart and a churn number nobody experienced.
If the app has no stable id to give, say so rather than substituting one.

import { retention } from '@upcontrol/sdk';
 
export const signups = retention('signups');
 
// Wherever the app knows who it is talking to:
signups.seen('u_' + user.id);