Invites
A player presses Invite in your game, shares a link, and whoever opens it is in your game, with what the link carries: a match to join, a deal to play, a score to beat. One tap from a message, for anyone, logged in or not. It's the Arcadible SDK's links.
// Sam presses Invite
inviteButton.addEventListener("click", async () => {
await arcadible.links.share({ data: { match } });
});
// Alex opens the link: after init()
const link = arcadible.context?.link;
if (link) {
join(link.data.match);
}
Sharing a link
links.share() makes a link to your game and shares it, in one call. Arcadible opens the share sheet, the system's on a phone and its own elsewhere, with your game paused under it, and the call resolves once the player is done.
try {
const { how } = await arcadible.links.share({
data: { match },
text: "Play me at Reversi",
});
if (how !== null) status.textContent = "Invite sent. Waiting for your friend…";
} catch (err) {
// … offline, or off Arcadible: say so, and play on …
status.textContent = "Couldn't make a link right now.";
}
- Put your own button in your game, worded for what it does there: Invite, Challenge a friend. Call
share()from its press. datais what the opener's game needs to find the place: a match's id, a seed. Up to 1 KB of JSON.textis the line that goes with the link in a message. Leave it out, and Arcadible writes one, such as "Sam invited you to Reversi".howis how the player sent it,"shared"or"copied", andnullwhen they backed out. The link still exists; nothing needs undoing.- A link lasts 30 days, and anyone who has it can open it.
Opening one
arcadible.context.link is the link this run was opened with, or null, set once init() has resolved, and the same for the whole run.
await arcadible.init({ splash: true });
const link = arcadible.context?.link;
if (link && typeof link.data?.match === "string") {
banner.textContent = `${link.by?.name ?? "A friend"} invited you`; // never innerHTML
await join(link.data.match);
}
- Show the invite in your game. The play page opens your game and says nothing: what an invite means, and how it looks, is yours.
byis who made the link, by Arcadible's word: theiridin your game, theirname, and whether they're aguest. A guest's name isnull, so have a word of your own ready.- Check
databefore you use it. It's what the maker's game sent, and anyone can make a link, so treat it as you would anything a player typed. - Most who open an invite are guests. They play at once, with no log-in in the way. Let a guest take the seat: a function knows a guest by an id that stays the same on their device.
- A link that's expired opens your game with no link, and the play page says so. Your game starts as it does from the store.
- A player may open their own link. Compare
link.by?.idwitharcadible.players.primary?.id.
An invite to a match
A link gets the right person to the right place. What they get there is decided by your game's server, since data is only what the maker's game sent. Here the server is a function, which keeps each match's seats in values only it can read.
The function makes a match, and seats whoever asks while a seat is free:
import { players, values, isArcadibleError } from "@arcadible/function-sdk";
export default {
async fetch(request: Request): Promise<Response> {
// a guest has an id too: enough to hold a seat
const me = players.primary(request);
if (me === null) return Response.json({ code: "no_player" }, { status: 403 });
const path = new URL(request.url).pathname;
if (path === "/create") {
const match = crypto.randomUUID();
await values.write([{ scope: "server", key: `match/${match}`, value: { seats: [me.id] }, revision: 0 }]);
return Response.json({ match, seat: 0 });
}
if (path === "/join") {
const { match } = await request.json().catch(() => ({}));
if (typeof match !== "string" || !/^[0-9a-f-]{36}$/.test(match)) {
return Response.json({ code: "invalid" }, { status: 400 });
}
const key = `match/${match}`;
const [record] = await values.read([{ scope: "server", key }]);
if (!record) return Response.json({ code: "no_match" }, { status: 404 });
const { seats } = record.value as { seats: string[] };
// back again, such as after a reload: the same seat
if (seats.includes(me.id)) return Response.json({ match, seat: seats.indexOf(me.id) });
if (seats.length >= 2) return Response.json({ code: "full" }, { status: 409 });
try {
// the revision makes the seat one player's: a second write loses
await values.write([{ scope: "server", key, value: { seats: [...seats, me.id] }, revision: record.revision }]);
} catch (err) {
if (isArcadibleError(err, "conflict")) {
return Response.json({ code: "full" }, { status: 409 });
}
throw err;
}
return Response.json({ match, seat: seats.length });
}
return Response.json({ code: "not_found" }, { status: 404 });
},
};
The game asks for a match and shares it, or asks for the seat a link names:
const functions = arcadible.functions;
// Sam presses Invite
async function invite() {
const { match } = await (await functions.fetch("/create", { method: "POST" })).json();
await arcadible.links.share({ data: { match } });
return match;
}
// Alex opened the link
async function accept(link) {
const res = await functions.fetch("/join", {
method: "POST",
body: JSON.stringify({ match: link.data.match }),
});
if (!res.ok) return null; // full, or gone: say so, and offer a new match
return res.json(); // { match, seat }
}
- The link carries the match's id, and nothing more. The function decides who sits: the first to ask takes the seat, and a third finds it full.
- Seats are kept in
"server"values, which only the function reads, never in"game", which every player can. - A match's id is long and random, so it needs no code to read out or type.
- Don't refuse guests a seat. Check
guestonly for what should take an account, such as a ranked score.
A challenge
A link can carry all there is to share, with no server at all: the deal a player just won, and their time.
// after a win
await arcadible.links.share({
data: { seed, moves: 98, time: 192 },
text: "Beat my time at Solitaire",
});
// whoever opens it plays the same deal
const link = arcadible.context?.link;
if (link && Number.isInteger(link.data?.seed)) {
deal(link.data.seed);
toBeat = { name: link.by?.name ?? "A friend", time: Number(link.data.time) };
}
A challenge is meant to be opened by many, and a score in a link is only what its maker's game said: fine between friends, not for a prize.
Without the SDK, and off Arcadible
- Off Arcadible,
share()fails withunsupported, andarcadible.contextisnull. Hide your Invite button whereverarcadible.buildisnull. - Offline,
share()fails withunavailable: a link needs the network. Your game plays on, and the next press tries again.
Trying it
arc serve makes links itself. Press your Invite button, copy the link, and open it in a second window with &player=Alex added: the first window is one player, and the second another. Links last until arc serve stops, so an old one is how you see the expired case (its reference).
To see the share sheet on a phone, and a link's card in a message, deploy a prerelease: a link made on staging opens staging (Testing Your Game).
Checklist
- Shares from the player's own press, with a button worded for your game
- Shows the invite itself when opened with a link, with the maker's name as text
- Checks a link's
databefore using it, and plays on when it isn't what's expected - Lets a guest accept an invite
- Says so, and plays on, when a link can't be made
- Starts as usual with no link, and with one that's expired
Next steps
arcadible.links: every member, code, and limit.- Players: who's playing, and what a guest is.
- Pausing: what your game does while the share sheet is up.