Custom Event Gates

A referral should validate when the referred user does the thing that makes them a real user of your app — finished onboarding, logged three workouts, made a first trade. Any event you send to Invitebase can be a qualification gate: track it from the SDK, or post it from your server.

If your gate is "became a paying subscriber", you may not need to track anything at all — see Reward on paid subscription.

Send events

Events are keyed by the referred user's ID (the same ID you pass to identify()). Gates only evaluate events belonging to the referred user of an open referral.

import invitebase from '@invitebase/js';

invitebase.track('workout_completed', { duration_min: 42 });

Invitebase.track("workout_completed", properties: ["duration_min": 42])

Invitebase.track("workout_completed", mapOf("duration_min" to 42))

const invitebase = useInvitebase();

invitebase.track('workout_completed', { duration_min: 42 });

Invitebase.track('workout_completed', {'duration_min': 42});

curl https://api.invitebase.com/v1/events \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: workout-9812-usr-123" \
  -d '{
    "name": "workout_completed",
    "referred_user_id": "usr_123",
    "properties": { "duration_min": 42 }
  }'

From the SDK, events batch, attach the current (anonymous or identified) user automatically, and work before login — anonymous activity is merged when you call identify(). Tracking also works offline: track() never blocks or throws, so events are cached on the device and flushed at the next available moment, retried with the same idempotency key so nothing is lost or double-counted.

Every ingested event appears in Developer tools → Events within seconds, and event names you have sent populate the dropdowns in the dashboard's rule builder.

Build the gate in the dashboard

Gates are built in the Invitebase dashboard. Open your campaign's qualification gate builder and add one condition per event you want to require. The event names you've already sent populate the dropdowns, so you're choosing from real data rather than typing identifiers.

For each condition you can:

• Require it, or make it optional. Every required condition must be met before the referral validates; optional conditions let you build "any one of these" gates. Mix the two to express both "all of these" and "any of these" logic in a single gate.
• Set a target and sum values toward it. Give the condition a target number. If the events carry a value — minutes listened, order total, items added — those values add up toward the target; if they don't, each occurrence counts as one. So a target of 3 on a plain event means "happened at least 3 times," while a target of 300 on an event that sends minutes means "5 hours in total."
• Restrict which events count. Narrow a condition to events matching the properties that matter — only paid plans, only USD orders — right in the builder.
• Set a window. Choose how long the referred user has to satisfy the gate; miss it and the referral expires.

Full reference: Qualification gates.

Real-world examples

Test a gate before going live

curl https://api.invitebase.com/v1/referrals/0c4f8d2e-6a17-4e93-b5c8-3e9d7f2a6b41 \
  -H "Authorization: Bearer $INVITEBASE_SECRET_KEY"

{
  "id": "0c4f8d2e-6a17-4e93-b5c8-3e9d7f2a6b41",
  "status": "in_progress",
  "gate_progress": [
    {
      "event": "workout_completed",
      "target": 3,
      "current": 1,
      "satisfied": false
    }
  ]
}

Design advice

• Gate on early value. The goal with gates is not to make it challenging to pass the gate - users will lose trust in your referral system if they find it too hard for referrals to validate. Pick events or value that are genuine to your app, that 95% of real users would complete within 24h of using your app.
• Keep the window short. Users will get frustrated waiting weeks for referrals to validate. Pick events that are likely to occur within the first 1-2 hours of using your app.

What's next