ADR-112: Onboarding experience as Portable Experience

More details about this document
Latest published version:
GitHub decentraland/adr (pull requests, new issue, open issues)
Edit this documentation:
GitHub View commits View commits on


This document presents a cross-platform, cross-renderer alternative to the Onboarding experience using regular scenes and the SDK instead of the hard-coded experience currently embedded in the renderer (unity).


During the years of Decentraland there was many experiments about the onboarding experience. It was always relatively easy to use Unity to tweak the experience. As the time passes, the complexity of the Renderer increases rendering changes in the onboarding experience too expensive to test due to the QA flow and release checks.

Also, the SDK gets more and more mature, supporting not only new features for the scenes but also new ways to run scenes like via Portable experiences.

This document will describe all the technical changes required to decouple the Onboarding experience from the renderer in the pursuit of:

Hosting of the scene

Since the onboarding is not a LAND, a Preview server will be used to host the scene. This server will also allow multiple parallel versions of the onboarding to co-exist to redirect the first time user experience to a specific cohort of A/B test or to a specialized tutorial for each platform i.e. VR may have a different tutorial because it has a different input method.

The preview server is specified in ADR-111. The configuration of the onboarding experience will be served by the /about endpoint specified in ADR-110

Some UX Considerations that need to be accounted for are:

Communications server

At first, the onboarding experience will be a offline experience.

Starting the onboarding experience

To all practical means, thanks to the /about endpoint of ADR-110, every onboarding experience will be its own Realm. And like the rest of the realms, the selection is controlled by Kernel.

Many conditions should be taken into account before deciding which realm is going to be used every time the Explorer starts (PENDING RFC). To those conditions, we will add the following.

defaultRealm =
  1. If CATALYST queryParam is set -> use `$CATALYST/about`
  2. If PREVIEW_MODE               -> use `$hostname/about`
  3. Else                          -> pickFromDaoRegistry()

RealmSelection =
+ 1. If eligibleForOnboarding() -> pickOnboardingRealm(thenGoTo: defaultRealm)
  2. Else                       -> defaultRealm

The eligibleForOnboarding conditions will use the following algorithm

eligibleForOnboarding =
  1. true if guestAccount  AND isNewGuest(guestAccount, localStorage)
  2. true if walletAccount AND NOT presentInCatalyst(walletAccount, defaultRealm)
  3. false

The pickOnboardingRealm function is used to select the proper onboarding tutorial for each user and platform. It selects the variant from the feature flags pointing to the right deployment URL.


Copyright and related rights waived via CC0-1.0. Living