Invite Tracking

Discord never tells a bot which invite somebody used. Arclo works it out by holding every code's use count and re-reading them on each join to find the one that went up, which is why attribution is a system rather than a field.

The number

One formula, used by the invite card, the leaderboard image, the web table, the /invites command and the reward checks:

total = regular − left − fake + bonus

• Regular counts every credited join, including the ones later marked fake, which is what makes a fake net to exactly zero rather than to minus one.
• Left is arrivals who have since left. It is subtracted while Subtract members who leave is on, which it is by default; off, the board ranks who has ever brought people in.
• Fake is an arrival that failed your rules: an account younger than Fake if the account is younger than (three days by default), or a rejoin while Count rejoins is off. Arclo can only recognize rejoins it has seen.
• Bonus is what you add by hand, from the dashboard or with /invites-add.
• Pending sits outside the sum: an arrival still serving out Hold new invites for, which is off (0 days) by default.

Setting it up

1. 1

   Switch it on

   Essentials → Invite Tracking. Arclo needs Manage Server to read your invite list.

2. 2

   Decide what counts

   On Tracking: the minimum account age for a real invite, whether rejoins count, whether leavers are subtracted, and how long a new invite is held before it counts. Who can earn invites keeps members, roles or particular links off the credit (staff, usually) and can hide people from the board.

3. 3

   Pick a join channel

   Optional, on Overview: a message each time somebody arrives, saying who brought them, a matching one when somebody leaves, and a private note to the inviter.

4. 4

   Add rewards

   On Rewards: roles at N invites, up to 50 tiers. Take rewards back when the total drops (on by default) removes a role again when somebody's total falls, and Keep every reward earned (on) lets members wear every tier rather than only their highest. A Top inviter role can follow whoever leads the board.

#joins

ArcloBOTToday at 12:00 PM

newcomer joined

@newcomer was invited by @Mira. They're now on 34 invites.

Today at 12:00 PM

Per-code roles and labels

Under Invite links on the Tracking tab, give a specific invite link a label and up to five roles: anybody arriving through it gets them automatically. This is how partner links, event links and campaign links are separated without asking anybody to pick a role afterwards.

The label and the code are available in your welcome message as {invite_label} and {invite_code}.

In the welcome message

{inviter}, {inviter_name} and {inviter_invites} are resolved before the greeting is sent: Welcome waits a few seconds for the tracker's answer, so “Welcome @newcomer, invited by @someone” arrives complete rather than being edited a second later. With Invite Tracking off, or when nobody can be credited (a vanity URL, say), the inviter reads someone. See Welcome & Goodbye.

Cards, boards and the web page

• The invite card is designed in the same studio as the level cards. The leaderboard picture /invites-leaderboard posts draws its rows over a Leaderboard banner you choose.
• The leaderboard has a public web page (Publish the leaderboard, on by default) at an address you can choose, which can hide who is on it, and the board can live as a pinned message Arclo keeps up to date.
• Weekly and monthly highlights post the members who brought the most people in over the period that just finished, early on Monday or on the 1st (UTC): a top-ten board image wearing your Leaderboard banner, in a message you design on the Leaderboard tab.
• Members can design their own invite card: every /invites card carries a Change Background button that opens the card studio on the website, unless you switch off Let members design their own card. See Your cards.
• Server Analytics reads the same join records for its growth, retention and join-source views.

Settings

• Invite management: the standings, with manual adjustments and per-member resets.
• When a member leaves: Remove their invite data is off by default, so a returning member keeps their count. On, their standing and their own arrival records are removed the moment they leave, and the joins they were credited for stop counting; whoever invited them keeps their own count.
• Logging: the audit line for every attribution, reward and adjustment. The Join history tab keeps every arrival, where it came from and the reason behind its verdict.

Commands

Limitations

• Vanity URLs cannot be attributed to a person. Discord reports the use but not an inviter, so those arrivals are filed under the vanity URL, as Server Discovery arrivals are under Discovery.
• An invite whose uses ran out between two joins is ambiguous; Arclo handles the common case but perfect attribution is not possible from Discord's API.
• Arclo needs one read of your invite list before it can attribute anything. It reads it when it starts, when it joins a server and once tracking is switched on, and follows new and deleted invites after that.