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" });
}