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
- Unity
- Unreal
Install Immutable's JS/TS SDK
Prerequisite: Node Version 20 or later
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
- yarn
npm install -D @imtbl/sdk
# if necessary, install dependencies
npm install -D typescript ts-node
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:
const passportInstance = new passport.Passport({
baseConfig: {
environment: config.Environment.SANDBOX, // or config.Environment.SANDBOX
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',
});
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 |
Install Immutable's Unity SDK
Install from a Git URL
Via UPM window
- Since
.dll
files are stored on Git Large File Storage, you must download and install git-lfs from here - Open the Package Manager
- Click the add + button and select "Add package from git URL..."
- Enter
https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Passport
and click 'Add'
Via manifest.json
- Since
.dll
files are stored on Git Large File Storage, you must download and install git-lfs from here - Open your project's
Packages/manifest.json
file - Add
"com.immutable.passport": "https://github.com/immutable/unity-immutable-sdk.git?path=/src/Packages/Passport"
in thedependencies
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
- 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;
// 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
.
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
- iOS
On Android, we utilise Chrome Custom Tabs (if available) to seamlessly connect gamers to Passport from within the game.
For example, on Unity 2019.4, you must upgrade from 3.4.* to 3.4.3 (see Android's blog post):
- In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Base Gradle Template under the Build section
- Open the newly generated
Assets/Plugins/Android/baseProjectTemplate.grade
file - Update
classpath 'com.android.tools.build:gradle:3.4.0'
toclasspath 'com.android.tools.build:gradle:3.4.3'
- In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Main Manifest and Custom Main Gradle Template under the Build section
- 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>
- Open the newly generated
Assets/Plugins/Android/mainTemplate.gradle
file. Add the following code insidedependencies
block:
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.
- In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Proguard File under the Build section
- 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.
- In Unity go to Build Settings -> Player Settings -> iOS -> Other Settings -> Supported URL schemes
- Increment the Size number
- Add your URL scheme in the Element field, e.g. if the deeplink URL is
mygame://callback
, add the schememygame
to the field.
Install Immutable's Unreal SDK
- 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 - Clone the unreal-immutable-sdk repository or download the zip/tarball from one of the versions here
- Copy the cloned repo into your project's
Plugins
folder, e.g.:MyGame/Plugins/unreal-immutable-sdk
- Restart your project (Unreal Editor & Jetbrains Rider IDE), upon restart it should load the
unreal-sdk-plugin
and should be good to use
- For Unreal Engine 4.26, 4.27, and 5.0, we use BLUI plugin instead of
WebBrowserWidget
plugin. - Please disable
WebBrowserWidget
plugin in theimmutable.uplugin
file, which can be found at the root of theunreal-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 folderimmutable-BLUI
folder toBLUI
. Your projects plugin directory should look likeMyGame/
|__Plugins/
|__BLUI/
|__unreal-immutable-sdk/
3. Use Passport
Passport is now setup in your application, you are now ready to explore:
- Passport identity where you will walk you through the different authentication methods Passport supports
- Passport wallet where you will learn how to interact with the Passport wallet