Skip to main content

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​

MemberDescription
links.share(options)Makes a link to your game, and shares it
context.linkThe 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 …
}
  • 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 data means, 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",
});
OptionValue
dataWhat the link carries: anything JSON, up to 1 KB as JSON text. Whoever opens the link is given it. Left out, it's null
textA 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.build isn't null: on Arcadible, and under arc serve. Elsewhere, such as your own development server, share fails with unsupported, so show your Invite button only where arcadible.build is set.
  • Resolves once the player is done, with the link: its id, its url, and how they sent it: "shared" through a share sheet or by email, "copied" with Copy link, or null when they backed out, when the link exists and simply goes unused. More values may be added: treat one you don't know as "shared".
  • data is JSON, by JSON's own rules: what's kept is what JSON.stringify makes of it, and only what it can't make text of at all (undefined, a function, a cycle) fails with invalid.
  • data is 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, data that isn't JSON, or text that isn't a string; too_large for data over 1 KB or text over 200 characters; limit_reached for more links than a player may make in an hour; unavailable when a link can't be made now, such as offline; and unsupported off Arcadible.
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.

FieldValue
idThe link's id, as its address carries it
dataWhat the game that made it put in it, as it was given: anything JSON
byWho 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.
  • by is Arcadible's word, not the link's: your game can say "Sam invited you" and trust it, and compare by.id with players.primary.id to tell a player opening their own link. A guest's name is null.
  • data is 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.

CodeMeansretryWhat to do
invalidOptions that aren't an object, data that isn't JSON, or a text that isn't a stringnoPass what the call takes
too_largedata over 1 KB, or text over 200 charactersnoCarry an id in the link; shorten the text
limit_reachedThe player made the most links they may in an hourlaterSay so; a link already made still works
unavailableA link can't be made now: offline, or Arcadible couldn't be reachedyesSay so, and play on; try again on the next press
unsupportedOff Arcadible, or on a play page from before linksnoHide your Invite button

New codes may be added, each with its retry.

Limits​

LimitValueWhen you reach itWhat to do
A link's data1 KB, as JSONThe share fails as too_largeCarry an id, and keep the rest in values
A share's text200 charactersThe share fails as too_largeShorten it
A link30 daysIt opens your game with no linkShare a new one
Links an hour60, for a player's account, and for their addressThe share fails as limit_reachedTry 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 serve prints 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 serve stops. 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_reached never happens there.