In a campaign where Prizerail draws from entries, your backend sends entrants to Prizerail as they enter. At each cutoff Prizerail locks the period’s list, commits its fingerprint, and draws the winners from it with the random value, each entrant in proportion to their weight. You don’t pick winners.
Each entry is either:
- a string, the entrant’s id, or
- an object with
entrantId plus an optional weight, displayName (up to 40 characters) and avatarUrl (https, up to 2,048 characters). The name and avatar show on the campaign page if they win.
Send up to 1,000 entries per request, and as many requests as you like. A drawing takes up to 100,000 entrants.
Which draw an entry goes to
An entry goes to the drawing whose cutoff is next when it arrives. After a cutoff, new entries go to the following drawing. The response says which drawing they went to.
weight is a whole number from 1 to 4,294,967,295, the entrant’s number of entries. Leave it out and it’s 1, so if you never send weights, every entrant has the same chance. An entrant with weight 3 is three times as likely to win as one with weight 1. Nobody wins twice in one draw.
Sending again
Sending an entrant again before the cutoff sets their weight, name and avatar to what you sent, so a retry is always safe and you can send a running total. Sending them without a weight sets it back to 1, so if you use weights, always send them.
The response counts what happened:
count and totalWeight are the drawing’s totals so far.
Checking what Prizerail has
It returns the drawing’s count, totalWeight and its entries in arrival order, the order the list locks in. Without drawing, it’s the drawing taking entries now. Pass the response’s next as after for the following page, until next is null. Each entry shows its position in the list once it has locked.
Entrant ids
Every locked list is published, hashed, so anyone can check a draw. Use an entrant id that can’t be guessed or linked back to a person: an HMAC of your user id with a secret key, or a random id you store. A plain hash of a sequential or public user id can be reversed by trying ids. Keep the key fixed for the life of the campaign, and never use emails or usernames.
