Spirit Island Launch URL Specification 

Apps and websites can launch the Spirit Island app on iOS, Android, or Steam using custom URLs to provide an initial game setup.

GENERAL

On mobile the game uses the spiritisland:// custom URL scheme. You can launch the game directly on mobile using that URL, or pass exactly the same path to this website for a shareable URL that is clickable no matter what: http://play.spiritislanddigital.com

The website attempts to detect mobile or PC usage and displays the appropriate version more prominently. However, both mobile and Steam links are shown in case of device misidentification.

This documentation is valid for Spirit Island version 1.6.3 and later. Earlier versions do not support this feature.

  • Version 2.2 added support for the aspects parameter.

The game uses identifiers for each card and board. These identifiers must be used in order to set up the game. We maintain the canonical list of identifiers.

You can pass whatever identifiers you want to the game, but be aware that there are some restrictions. The game will attempt to select whatever you send, except for:

  • Expansion content that the player does not own. These will be ignored.

  • Invalid board layouts. These will be ignored or repaired.

  • Invalid configuration combinations (e.g. using Sharp Fangs Behind the Leaves without tokens).

IOS/ANDROID

You can launch the game without providing information using this URL:

spiritisland://launch (or) http://play.spiritislanddigital.com/launch

To launch and start a new local game, build a URL starting with the following:

spiritisland://screen/NewGame? (or) http://play.spiritislanddigital.com/screen/NewGame?

Add parameters describing the setup.

  • spirits - up to 4 unique comma separated Spirit identifiers

  • boards - up to 4 unique comma separated Island Board identifiers (same number of boards as spirits)

  • layout - comma separated side pairs (see below for details)

  • adversary - Adversary identifier

  • adversaryLevel - Adversary level number (between 1-6 inclusive; for base adversary level, do not pass this parameter)

  • scenario - Scenario identifier

  • useExpansions - comma separated expansion identifiers

  • useTokens - must be "1" to use tokens. Automatically set if useExpansions contains BranchAndClaw.

  • useEvents - must be "1" to use events.

  • progressionSpirits - comma separated Spirit identifiers to use Power Progression

  • practiceModes - comma separated Practice Mode identifiers

  • aspects - comma separated aspect identifiers (matched with spirits automatically)

Board Layout

The board layout is a list of board side adjacencies using pairs of side identifiers (e.g. A0, A1, A2, A3). 0 is the “top" side (ocean on the left) and the numbers go clockwise until 3 is the ocean side. Example: Board A above board C, Ocean to the left. That would be Board A Side 0 adjacent to Board C Side 2 = A0:C2. 

If no layout is provided, the default layout will be used. When using the thematic boards, the layout parameter is ignored as they have a fixed layout.

Expansions

The only supported expansion identifiers at this time are BranchAndClaw and JaggedEarth. Using one or more are required in order to enable tokens, events, and Spirits that require tokens.

Examples:

Sharp Fangs Behind the Leaves and Vital Strength of the Earth (progression) on boards A and B vs. Sweden 3, Blitz scenario, using B&C content, events and tokens, and bonus start of game Growth

http://play.spiritislanddigital.com/screen/NewGame?spirits=SharpFangsBehindTheLeaves,VitalStrengthOfTheEarth&boards=A,B&layout=A1:B2&adversary=TheKingdomOfSweden&adversaryLevel=3&scenario=Blitz&useExpansions=BranchAndClaw&useEvents=1&progressionSpirits=VitalStrengthOfTheEarth&practiceModes=StartOfGameGrowth

Sun-Bright Whirlwind and River Surges in Sunlight on boards East and West vs England (base), no B&C content

http://play.spiritislanddigital.com/screen/NewGame?spirits=SunBrightWhirlwind,RiverSurgesInSunlight&boards=East,West&adversary=TheKingdomOfEngland

STEAM

The Steam version uses the same URL format, but it must be escaped and wrapped in another URL so that Steam can launch the game and pass the information to Spirit Island. If the game is already running, the URL will not be passed along.

The wrapper format is:

steam://run/1236720/?url=<encoded spiritisland:// URL>

Example:

steam://run/1236720/?url=spiritisland%3A%2F%2Fscreen%2FNewGame%3Fspirits%3DSunBrightWhirlwind%2CRiverSurgesInSunlight%26boards%3DEast%2CWest%26adversary%3DTheKingdomOfEngland

QUESTIONS?

If you have any problems or have a suggestion, please contact us.