Guides

Counting and holdouts

Fetching a decision is free; showing it is what counts. How holdout users are measured.

Fetching is free#

Asking Tug what to show (GET /decisions/:surface, getPlacement, getDecision) never uses a frequency cap or your quota. Fetch as often as your rendering needs: prefetch, retry, render on the server and again on the client.

A repeat fetch for the same user and surface within 30 minutes reuses the same logId, so retries don't create new entries either.

Shown is what counts#

A decision becomes a serve when your app reports shown. That is the moment it is:

  • billed, as one decision on your plan;
  • counted toward the message's frequency cap for that user;
  • counted in the lift measurement.

The React components, Tug.mountBanner, placement.shown() and reportShown(placement) all report it when the slot renders. If you render yourself, report it yourself.

Holdout groups#

Each approved message holds back a share of its users as a control group (default 10%, up to 50%). They see nothing. Comparing them with users who saw the message shows whether it worked.

The split is deterministic: the same user is always in the same group for a message. Holdout entries are never billed.

Report holdout users too#

A holdout user's response has decision: null and their entries in holdoutLogIds. Report shown on those at the same moment you would have shown the message, so both groups are counted the same way.

const placement = await tug.getPlacement({ surface: "banner", userId });
if (placement.decision) render(placement.decision);

// Message or not: reports the message, or the holdout entries
placement.shown();

Results appear per message on Recommendations once each group has at least 30 serves. They are shown as an interval, not a single number. See Attribution.

Rendering on the server#

With a server API key, a call that renders straight away can count the serve in the same request with shown=true. Browser calls can't: a public-key request with shown=true gets 401 server_key_required.

TypeScript

// Rendering now, on the server: count the serve in the same call (needs apiKey).
const decision = await tug.getDecision({ surface: "banner", userId: "user_123", shown: true });

if (decision) {
  // …render it, then report what the user did:
  await tug.feedback({ distinctId: "user_123", logId: decision.logId, action: "clicked" });
}

  • PageOverviewGet started
  • PageQuick startGet started
  • PageConceptsGet started
  • PageScript tag (tug.js)Install
  • PageReactInstall
  • PageNode and serverInstall
  • PageIdentity verificationGuides
  • PageCounting and holdoutsGuides
  • PagePostHogGuides
  • PageEnvironmentsGuides
  • PageData requestsGuides
  • PageOperator consoleGuides