arcadible.links
Links to your game that a player makes and shares: an invite to a match, a challenge to beat a score. Whoever opens one starts your game, with what the link carries. It's in the Arcadible SDK, the package and the hosted script alike. How to use it: Invites.
interface Links {
share(options?: ShareOptions): Promise<Shared>;
}
type ShareOptions = { data?: unknown; text?: string };
type Shared = { id: string; url: string; how: "shared" | "copied" | string | null };
// how this run started: arcadible.context.link
type Link = { id: string; data: unknown; by: Player | null };
type Player = { id: string; guest: boolean; name: string | null };
Members
| Member | Description |
|---|---|
links.share(options) | Makes a link to your game, and shares it |
context.link | The link this run was opened with, or null |
An invite
Sam presses your game's Invite button, and your game shares a link that names the match:
const link = await arcadible.links.share({ data: { match: "q8Zk2pWm" } });
// { id: "k7Qx2mLp4T9z", url: "https://play.arcadible.com/reversi/?l=k7Qx2mLp4T9z", how: "shared" }
Alex opens it from a message, and your game starts with it:
// after init()
const link = arcadible.context?.link;
if (link) {
// { id: "k7Qx2mLp4T9z", data: { match: "q8Zk2pWm" }, by: { id: "3f2b…", guest: false, name: "Sam" } }
// … show the invite from link.by.name, and seat the player in link.data.match …
}
A link
- Its address is your game's own play page, with the link's id:
https://play.arcadible.com/<handle>/?l=<id>. One tap from a message opens your game, for anyone, logged in or not. The id is random and long, so no one guesses one. - The address holds only the id. What the link carries stays on Arcadible, so nothing of it is pasted or logged with the address, and no one changes it by editing one.
- A link is for the channel it was made on. One made on a staging build opens staging, so you can test an invite end to end before a release; it never opens production.
- A link opens the channel's current version, which may be newer than the one that made it. If you change what your
datameans, keep a version in it. - A link lasts 30 days. After that, the play page says "This link has expired", and your game starts with no link, as from the store. What a link still leads to before then, such as a match that ended, is your game's to say.
- Anyone with the link can open it, as many times as they like, so a link grants nothing by itself: your game, or its function, decides what an opener gets, such as a seat that's still free.
- A link is deleted with its maker's account.
- In a message, a link shows as a card: your game's art, its title, and who invited ("Sam invited you to Reversi").
links.share(options)
share(options?: ShareOptions): Promise<Shared>
Makes a link to your game, and has Arcadible share it.
const { how } = await arcadible.links.share({
data: { seed: 42, time: "3:12" },
text: "Beat my time at Solitaire",
});
| Option | Value |
|---|---|
data | What the link carries: anything JSON, up to 1 KB as JSON text. Whoever opens the link is given it. Left out, it's null |
text | A line the share carries, plain text, up to 200 characters. Left out, it's Arcadible's own, such as "Sam invited you to Reversi" |
- Arcadible shares it, not your game: on a phone, the system's share sheet; elsewhere, a small sheet of Arcadible's over your game, with the link, Copy link, and Email. Your game is paused while it's up, and resumed after.
- Call it from the player's own action, such as a press of your Invite button, never by itself: a phone only opens its share sheet for a tap.
- A link can be shared wherever
arcadible.buildisn'tnull: on Arcadible, and underarc serve. Elsewhere, such as your own development server,sharefails withunsupported, so show your Invite button only wherearcadible.buildis set. - Resolves once the player is done, with the link: its
id, itsurl, andhowthey sent it:"shared"through a share sheet or by email,"copied"with Copy link, ornullwhen they backed out, when the link exists and simply goes unused. More values may be added: treat one you don't know as"shared". datais JSON, by JSON's own rules: what's kept is whatJSON.stringifymakes of it, and only what it can't make text of at all (undefined, a function, a cycle) fails withinvalid.datais yours, and public to whoever has the link: ids, a seed, a score to beat. Put nothing secret in it. Something larger, such as a level, goes in values, and the link carries its key.- A guest shares links too.
- Fails with
invalid, before anything is asked, for options that aren't an object,datathat isn't JSON, ortextthat isn't a string;too_largefordataover 1 KB ortextover 200 characters;limit_reachedfor more links than a player may make in an hour;unavailablewhen a link can't be made now, such as offline; andunsupportedoff Arcadible.
context.link
readonly link: Link | null
The link this run was opened with, or null, on arcadible.context, set once init() has resolved; context itself is null where no page says, such as off Arcadible, and undefined before.
| Field | Value |
|---|---|
id | The link's id, as its address carries it |
data | What the game that made it put in it, as it was given: anything JSON |
by | Who made it, a player: their id in your game, guest, and name. null for a link no player made |
- It never changes during a run. A link opened while your game is running starts a new run: the page pauses your game, which saves, and loads again with the new link.
byis Arcadible's word, not the link's: your game can say "Sam invited you" and trust it, and compareby.idwithplayers.primary.idto tell a player opening their own link. A guest'snameisnull.datais whatever the maker's game sent, and a player can make a link with a changed game: read it as input, and check it, as anything from a player. Check its shape before you use it.- Show the invite yourself. What a link means is your game's, so the play page says nothing of its own when one is opened, only when one has expired.
- A link that's expired, or isn't this game's, is
null, as if the game were opened from the store.
Codes
A call that fails rejects with an ArcadibleError: act on its code, and on its retry for a code you don't handle.
| Code | Means | retry | What to do |
|---|---|---|---|
invalid | Options that aren't an object, data that isn't JSON, or a text that isn't a string | no | Pass what the call takes |
too_large | data over 1 KB, or text over 200 characters | no | Carry an id in the link; shorten the text |
limit_reached | The player made the most links they may in an hour | later | Say so; a link already made still works |
unavailable | A link can't be made now: offline, or Arcadible couldn't be reached | yes | Say so, and play on; try again on the next press |
unsupported | Off Arcadible, or on a play page from before links | no | Hide your Invite button |
New codes may be added, each with its retry.
Limits
| Limit | Value | When you reach it | What to do |
|---|---|---|---|
A link's data | 1 KB, as JSON | The share fails as too_large | Carry an id, and keep the rest in values |
A share's text | 200 characters | The share fails as too_large | Shorten it |
| A link | 30 days | It opens your game with no link | Share a new one |
| Links an hour | 60, for a player's account, and for their address | The share fails as limit_reached | Try again later |
Every limit is also in Limits.
Under arc serve
arc serve makes links itself, and nothing reaches Arcadible.
- A link's address is the local play page's, such as
http://localhost:4100/?l=k7Qx2mLp4T9z, and the sheet is Arcadible's own, as on a desktop.arc serveprints each link it makes too,Link made: <address>, so a script or an agent can open it with no sheet. - Open it in a second window as another player by adding
&player=<name>:http://localhost:4100/?l=k7Qx2mLp4T9z&player=Alex. That's an invite, end to end, with no deploy. - Links last until
arc servestops. A link from an earlier run, or any id it didn't make, is the expired case: the page says "This link has expired", and your game starts with no link. - Nothing is counted, so
limit_reachednever happens there.