Open a webshop from your game

Understand how a game opens a webshop with an authenticated player session and how players are authenticated.

Read time 4 minutes

Last updated 21 days ago

A webshop runs outside the Unity game context. To identify the player in the webshop, your game opens the shop with an outbound link that includes an authenticated player session. This is the recommended way to open the shop; the player can complete a purchase without an extra sign-in step. Players can also open the shop directly from a browser, bookmark, marketing link, or shared link. If the shop doesn’t receive a player session, it shows an unauthenticated landing page instead of the product list. After a purchase, the shop can return the player to your game with a return deep link. The shop also uses this link to handle unauthenticated players automatically. For more information, refer to Handle inbound deep links. Webshops handle authentication from the session your game passes. You don’t need to build a separate sign-in flow. For more information, refer to Authenticate players and persist sessions.

Outbound links

The game opens the shop URL using the platform's standard external URL handling. On a mobile device, this typically opens the shop in the system browser or an in-app web view. The URL format is the following:


https://shop.unity.com/{studio}/game/{slug}?sessionToken={token}&projectId={projectId}&environment={env}

To resolve this URL at runtime for the live published shop or for an environment's draft preview, refer to Integrate a webshop into a Unity game. The following query parameters identify the player and load the correct webshop context:

Parameter	Purpose
`sessionToken`	A short-lived session token from the Unity Authentication SDK. The shop exchanges this token in the player's browser for an authenticated player session.
`projectId`	The Unity Cloud project ID the player belongs to. The shop uses this value to load the correct webshop and catalog.
`environment`	The Unity Environment name to load. This parameter is optional and defaults to `production` .

You can also pass

locale

and

currency

so the catalog returns products for the player's region:


https://shop.unity.com/acme/game/dungeons?sessionToken=…&projectId=…&environment=production&locale=ja-JP&currency=JPY

After the shop parses the authentication and store parameters, it removes them from the URL. This helps prevent screenshots or accidentally shared URLs from exposing the session token. If you omit

sessionToken

and

projectId

, the shop displays an unauthenticated landing page instead of the product list. Without player identity, the player can't complete a purchase. The authenticated URL is required whenever the game opens the shop.

Authenticate players and persist sessions

Webshops authenticate player sessions through Unity Authentication. When the game opens the shop, it includes a short-lived Unity Authentication token in the

sessionToken

query parameter. The webshop exchanges the token in the player’s browser for a persistent player session. Players can’t view the catalog or complete a purchase unless they’re authenticated. If a player opens the shop without authentication context, the shop shows the unauthenticated landing page instead of the product list. After a successful

sessionToken

exchange, the shop stores the player identity in the browser’s

localStorage

. The stored identity is scoped to the project and environment. If the same player opens the shop URL later, for example from a browser bookmark, the shop can reuse the cached identity and skip the authentication exchange. The player doesn’t need to reopen the shop from the game. The session refreshes automatically while the stored session token is valid. Sessions that start from the Dashboard preview path,

/_preview/...

, use

sessionStorage

instead of

localStorage

. This preserves the same player ID during a Stripe redirect in the current tab, but doesn’t persist the session after the tab closes. For more information, refer to Catalog and payments in webshops.

Handle the unauthenticated landing page

When a player opens the shop URL without authentication context and without a cached session in

localStorage

for the project and environment, the shop displays an unauthenticated landing page instead of the product list. To reach the product list, the player opens the webshop from your game, which carries their authenticated session. The landing page also displays a Connect to game button. When the player selects this button, the shop opens your game through the deep link. The player’s authentication information is collected automatically, and the Unity IAP SDK reopens the shop with an authenticated session on the product list. If no deep link is configured, the button prompts the player to open the shop from your game instead. For this sign-in flow, the shop automatically modifies the Deeplink URL.

Post-purchase return to the game

After a purchase, the webshop can send the player back to your game with a return deep link. Configure it in the Deeplink URL field in the dashboard, for example

mygame://purchase-success

. For the return, the webshop uses the link exactly as you enter it, so you can add a custom post-purchase path. Entering a value enables both the return link and the Connect to game launch from the unauthenticated landing page. Leaving the field empty disables both. There’s no separate on/off setting. For more information about the field and its limits, refer to Create a webshop and Webshop limits reference.

Note

The return deep link is separate from the payment provider redirect URL. After checkout, the payment provider redirects the player back to the webshop, where the purchase result screen appears. The return deep link is the webshop’s next step from that screen back to your game. It appears as the Back to game button. Configuring the return deep link doesn’t change the provider redirect URL.

When the return link is enabled, the webshop appends the purchase outcome as query parameters:


mygame://purchase-success?status=success&playerId={playerId}

The webshop appends

status=success

after a completed purchase and appends

playerId

when a player identity is available. If the configured URL has no path, the webshop appends the parameters to the scheme directly:


mygame://?status=success

The game registers the custom URL scheme and reads the query parameters to resume the player where they left off. The Back to game button appears on the purchase result screen only when all of the following conditions are met:

The player opened the shop from your game through a deep link.
The player is on a mobile device, such as iOS or Android.
The webshop has a return deep link configured.

On desktop, or when the player didn’t open the shop through a deep link, the result screen shows Continue shopping instead. The Back to game button also appears on the failure screen so players can return to the game after a canceled or failed purchase.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

In-App Purchasing

IAP Client API

IAP SDK API

Webshop Admin API

Webshop Client API