Setup

1. Create a Passport Client

You will need to create and configure a passport client for each application type (e.g. a mobile app, a website) where you intend to use Passport. If you haven't already setup a project in Immutable Hub, login and add a new project from the dashboard.

When you add a project you will need to name it and choose whether your project will run on Immutable zkEVM or Immutable X. You then need to choose whether your project will run on Testnet or Mainnet and name the environment.

Once your project and environment are setup, navigate to its Passport Configuration page and add a new client. You will need choose the Application Type (Native or Web), then add your Application Name, a Redirect URL and a Logout URL to save the client.

Configuring your Passport client

There are a few crucial details that must be provided when adding a client:

Property	Description
Application Type	The type of your application. Available types: Website / Native (e.g. Mobile App, Desktop Game)
Application Name	The name you wish to use to identify your application inside Passport.
Redirect URLs	The URL that your users will be redirected to once the authentication is complete. This is also where your application process the authentication response.
Logout URLs	The URL that your users will be redirected to upon logging out of your application.
Web Origins URLs	The URLs that are allowed to request authorisation. This field is available when you select the Native application type.

For example, if you're developing a wesbite locally, your Redirect and Logout URLs may be something like; http://localhost:3000/redirect and http://localhost:3000/logout respectively.

2. Configure Passport

Web

Install Immutable's JS/TS SDK

Prerequisite: Node Version 20 or later

Immutable's Typescript SDK requires **Node v20** (Active LTS version) or **higher**. Node v20 can be installed via `nvm`.

To install nvm follow these instructions. Once installed, run:

nvm install --lts

Immutable's Web SDK is written in TypeScript and we recommend using a TypeScript framework, preferrably React, to build your web application.

In the terminal, navigate to the root directory of your web application and install the following dependencies using your preferred package manager.

npm

npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node

yarn

yarn add --dev @imtbl/sdk
# if necessary, install dependencies
yarn add --dev typescript ts-node

To enable code splitting (importing only the SDK modules you need) there are additional prerequisites.

Next, we'll need to initialise the Passport client inside your application as follows:

View on GitHub

export const passportInstance = new passport.Passport({
    baseConfig: {
      environment: config.Environment.SANDBOX, // or config.Environment.PRODUCTION
      publishableKey:
        process.env.NEXT_PUBLIC_PUBLISHABLE_KEY || '<YOUR_PUBLISHABLE_KEY>', // replace with your publishable API key from Hub
    },
    clientId: process.env.NEXT_PUBLIC_CLIENT_ID || '<YOUR_CLIENT_ID>', // replace with your client ID from Hub
    redirectUri: 'http://localhost:3000/redirect', // replace with one of your redirect URIs from Hub
    logoutRedirectUri: 'http://localhost:3000/logout', // replace with one of your logout URIs from Hub
    audience: 'platform_api',
    scope: 'openid offline_access email transact',
  });

note

Examples on how to integrate Passport with common web frameworks and 3rd party libraries are available here.

More detail on each of the fields:

Field	Description
publishableKey	Publishable Keys are used to identify your integration for tracking and analytics purposes. You can find it by logging into Immutable Hub, choosing your Project and Environment then navigating to the API Keys page.
clientId	Client IDs are used to identify your the passport client you wish to use in this integration. You can find it by logging into Immutable Hub, choosing your Project and Environment then navigating to Passport Configuration page.
redirectUri	The URI of your application that users will be redirected to after successfully authenticating. This value must match one of the Redirect URLs that have been set in your Immutable Hub's Passport Configuration for the Passport client you are wanting to integrate. If no value is specified, then Passport will default to the redirect logout mode.
logoutRedirectUri	The URI of your application that users will be redirected to after successfully logging out. This value must match one of the Logout URLs that have been set in your Immutable Hub's Passport Configuration for the Passport client you are wanting to integrate. If no value is specified, then Passport will default to your Passport client's first logout redirect URI.
audience	The platform_api audience is required for all Passport clients.
scope	The transact, openid & offline_access scopes are all currently required for all Passport clients. Request the email scope to access the user's email. Learn about scopes here.
popupOverlayOptions	Options for disabling the Passport overlays that appear when the Passport transaction confirmation pop-up is requested. The overlays are designed to help the user focus the pop-up or open the pop-up when Passport detects the pop-up was blocked. There are two Passport pop-up overlays, a generic overlay that is always shown when the pop-up opens and an overlay that appears when the pop-up has been blocked. Each overlay has a separate option to disable depending on whether you want to show both overlays, only the blocked overlay or disable the blocked overlay to implement a custom solution for handling blocked pop-ups.

Troubleshooting

Error Code	Cause	Resolution
INVALID_CONFIGURATION	The environment configuration or OIDC Configuration is incorrect	Verify that you are passing an environment configuration and OIDC configuration, and that all the mandatory properties have been set

Unity

Install Immutable's Unity SDK

Install from a Git URL

Via UPM window

1. Since .dll files are stored on Git Large File Storage, you must download and install git-lfs from here
2. Open the Package Manager
3. Click the add + button and select "Add package from git URL..."
4. Enter https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Passport and click 'Add'

Via manifest.json

1. Since .dll files are stored on Git Large File Storage, you must download and install git-lfs from here
2. Open your project's Packages/manifest.json file
3. Add "com.immutable.passport": "https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Passport" in the dependencies block

Install a specific version

To install a specific version of the SDK from a git URL, append '#' followed by the version tag. For example, https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Passport#v1.0.0 will add the Unity SDK version 1.0.0.

Dependencies

The UniTask package (v2.3.3) is a dependency of our SDK. Follow the instructions here to install it.

If you encounter any conflicts, refer to Unity’s guide on resolving package conflicts here.

Create a script with the following code and bind it to an object:

Device Code Authorisation

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Immutable.Passport;
  
public class InitPassport : MonoBehaviour
{
    private Passport passport;
    
    async void Start()
    {
        // Replace with your actual Passport Client ID
        string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
        
        // Set the environment to SANDBOX for testing or PRODUCTION for production
        string environment = Immutable.Passport.Model.Environment.SANDBOX;
        
        // Initialise Passport
        passport = await Passport.Init(clientId, environment, logoutRedirectUri: "https://www.example.com");
    }
}

Once initialised, you can access the Passport instance from anywhere in your project via Passport.Instance.

PKCE (Recommended for Android, iOS, macOS and WebGL)

using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Immutable.Passport;
  
public class InitPassport : MonoBehaviour
{
    private Passport passport;
    
    async void Start()
    {
        // Replace with your actual Passport Client ID
        string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
        
        // Set the environment to SANDBOX for testing or PRODUCTION for production
        string environment = Immutable.Passport.Model.Environment.SANDBOX;
 
        // Your game's redirect URLs
        string redirectUri = "mygame://callback";
        string logoutRedirectUri = "mygame://logout";
        
        // Initialise Passport
        passport = await Passport.Init(clientId, environment, redirectUri, logoutRedirectUri);
    }
}

Once initialised, you can access the Passport instance from anywhere in your project via Passport.Instance.

To get PKCE working on Android and iOS, you need to set up a few more things.

Android

On Android, we utilise Chrome Custom Tabs (if available) to seamlessly connect gamers to Passport from within the game.

💡Unity versions below 2021.3

To check if Chrome Custom Tabs are available, older Unity versions may require a specific Gradle plugin version.
For example, on Unity 2019.4, you must upgrade from 3.4.* to 3.4.3 (see Android's blog post):

1. In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Base Gradle Template under the Build section
2. Open the newly generated Assets/Plugins/Android/baseProjectTemplate.grade file
3. Update classpath 'com.android.tools.build:gradle:3.4.0' to classpath 'com.android.tools.build:gradle:3.4.3'

1. In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Main Manifest and Custom Main Gradle Template under the Build section
2. Open the newly generated Assets/Plugins/Android/AndroidManifest.xml file. Add the following code inside the <application> element:

<activity
  android:name="com.immutable.unity.RedirectActivity"
  android:exported="true" >
  <intent-filter android:autoVerify="true">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="mygame" android:host="callback" />
    <data android:scheme="mygame" android:host="logout" />
  </intent-filter>
</activity>

3. Open the newly generated Assets/Plugins/Android/mainTemplate.gradle file. Add the following code inside dependencies block:

💡Compile SDK version

For this version of the Chrome Custom Tabs to work, the compileSdkVersion must be at least 33. This is usually the same value as the targetSdkVersion, which you can set in Build Settings -> Player Settings -> Android -> Other Settings -> Target API Level.

implementation('androidx.browser:browser:1.5.0')

The application will now open when the device processes any link that starts with mygame://callback or mygame://logout.

See the sample app AndroidManifest.xml and mainTemplate.gradle for examples.

Proguard

If you enable Minify in your project settings, you will need to add a custom Proguard file to your project.

1. In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Proguard File under the Build section
2. Open the newly generated Assets/Plugins/Android/proguard-user.txt file. Add the following code inside the <application> element

-dontwarn com.immutable.**
-keep class com.immutable.** { *; }
-keep interface com.immutable.** { *; }

-dontwarn androidx.**
-keep class androidx.** { *; }
-keep interface androidx.** { *; }

See the sample app proguard-user.txt for an example.

iOS

1. In Unity go to Build Settings -> Player Settings -> iOS -> Other Settings -> Supported URL schemes
2. Increment the Size number
3. Add your URL scheme in the Element field, e.g. if the deeplink URL is mygame://callback, add the scheme mygame to the field.

Unreal

Install Immutable's Unreal SDK

1. Since .uasset and .umap files are stored on Git Large File Storage, you must download and install git-lfs from here before cloning the respository
2. Clone the unreal-immutable-sdk repository or download the zip/tarball from one of the versions here
3. Copy the cloned repo into your project's Plugins folder, e.g.: MyGame/Plugins/unreal-immutable-sdk
4. Restart your project (Unreal Editor & Jetbrains Rider IDE), upon restart it should load the unreal-sdk-plugin and should be good to use

💡Unreal Engine 4 and 5.0 additional requirements

• For Unreal Engine 4.26, 4.27, and 5.0, we use BLUI plugin instead of WebBrowserWidget plugin.
• Please disable WebBrowserWidget plugin in the immutable.uplugin file, which can be found at the root of the unreal-immutable-sdk folder, e.g. MyGame/Plugins/unreal-immutable-sdk/immutable.uplugin, and restart your UE4 editor.

  {
    "Plugins": [
    {
     "Name": "WebBrowserWidget"
     "Enabled": false
    }
   ]
  }

• Download or clone BLUI from https://github.com/immutable/immutable-BLUI to your project's Plugins folder. Then rename the folder immutable-BLUI folder to BLUI. Your projects plugin directory should look like

  MyGame/
  |__Plugins/
    |__BLUI/
    |__unreal-immutable-sdk/
  

⚠️Warning

Please make sure your project is properly configured in the Immutable Hub before attempting to log in to Passport, especially if you're developing your game in Unreal Engine 4.26, 4.27, or 5.0. Pay special attention when configuring Web Origins URLs.

3. Use Passport

Passport is now setup in your application, you are now ready to explore:

1. Passport identity where you will walk you through the different authentication methods Passport supports
2. Passport wallet where you will learn how to interact with the Passport wallet