Deep linking from Bunch

When Bunch sends players from the Bunch app to your game, it uses a URI scheme defined by your game to open it directly. Each mobile app chooses their URI scheme and sets it up in the app configuration. Typically the URI scheme reflects the app name, for example for the Bunch app it's simply bunch:// For the purpose of this document we will use yourgame:// as a placeholder for your game's URI scheme.

💡

To learn more about setting up deep linking URI scheme for your app, see the developer documentation for iOS and Android.

In addition to launching your game, the Bunch platform has the ability to use a custom deep link containing additional data in the link's parameters which can be used to direct players to a specific destination within your game. In general, handling deep links from Bunch is how you can enable people in the same Bunch party to quickly and seamlessly play together. Bunch platform offers two main options for how the deep linking can be configured:

Separate links for the session host and participants
Single deep link for the entire Bunch party.

Separate links for the session host and participants

When using the host and participant model Bunch assigns one person in the party to be the "host" of the game session and using a deep link, sends her to the screen where she can create an invite to a multiplayer session in your game. Those invites can have a different format depending on the game, such as a friend invite, team invite or a room code.

Once the invite is created and ready for other participants to join, the game sends the information about how others can join the same session to Bunch (via a REST API call), and Bunch sends the remaining players from party there.

Implementation in the game

First, Bunch sends the host to the game using a specific deep link:

yourgame://bunch.app/createSession?
	roomId={$roomid}&
	userId={$userid}&
	userName={$name}&
	sessionRequestToken={$token}

Bunch sets the parameters passed to the game through this deep link:

roomId: Bunch identifier of the current party
userId: User identifier of the person acting as the host
userName: Host's display name
sessionRequestToken: This is a token used to authenticate the following REST call (see below).

When a player opens the game with this deep link, the game should take her to the appropriate screen where a game session invite can be created. Typically at this point, the game would allow the host to share this link to invite their friends to play together, like in the example below:

Instead of having the player share the invite link, the game should post the link to Bunch using a REST API endpoint.

curl -X PATCH \
  https://REST_API_HOST/v1/rooms/ROOM_ID/session \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: REST_API_KEY' \
  -d '{
    "sessionRequestToken": "TOKEN",
    "userId": "USER_ID"
    "sessionLink": "INVITE_LINK"
}'

REST_API_HOST and REST_API_KEY will be provided by Bunch when you're ready to start working on the optimization.

ROOM_ID and USER_ID need to match the id passed to the game in the roomId and userId parameters of the deep link which sent the host to the game.

TOKEN needs to match the access token passed in the deep link's sessionRequestToken parameter.

INVITE_LINK is the invite link generated by the game that allows others to join the same game and play together. It could be a friend invite, a team invite, a room invite etc. The invite link can either be a deep link or a web link, for example:

// deep link example
yourgame://invite/multiplayer?tag=XYZVHJDT
// web link example
https://link.yourgame.com/invite/multiplayer?tag=XYZVHJDT

Then Bunch will use this link to open the game for all remaining players in the same party. The game should then take players who open the app with this link directly to a place where they can easily play together with the host, just as they would if they entered it in the "Join with code" UI.

Single deep link for the entire Bunch party

In this option, everyone who is in the same Bunch party opens your game using the same deep link. Your game is then responsible for ensuring that the same deep link brings players to the same multiplayer game session.

Example deep link:

yourgame://bunch.app/createOrJoinSession?
	partyId={$partyid}&
	userName={$username}

In the example above every player who is in the same Bunch party would have the same values passed in the partyId parameter included in the deep link the Bunch app uses to open your game. In order for this to work your game should be able to accept multiplayer session ids that are generated by Bunch (which

When players open your game via such a deep link, your game should create a multiplayer session with the unique id specified in the link (if it doesn't exist yet); add the player to the session and drop her into the appropriate multiplayer screen in your game.

Choose the best option for your game

The options described above will result in a slightly different user experience and will require a varying degree of effort depending on how multiplayer invites are already implemented in your game. As the "host and participants" model is a commonly adopted way to implement multiplayer session invites and therefore for most games it would be the recommended way to optimize for traffic from Bunch.

Next steps

Once the game handles the deep links from Bunch, it's worth considering making a couple of additional adjustments to user experience to make it even more seamless for people coming to your game from the same Bunch party. Check Best practices section to learn more.

Apart from optimizing your game to offer the best possible experience for people coming from Bunch, further integrating Bunch brings the party experience directly into your game making it easy for players to connect with their friends and play together. Integration overview is a good starting point to learn more about it.