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 by cloning the repository
- Since
.dll
files are stored on Git Large File Storage, you must download and install git-lfs from here before cloning the repository - Clone the unity-immutable-sdk repository or download the zip/tarball from one of the versions here
- Open the Package Manager
- Click the add + button and select "Add package from disk..."
- Navigate to the Passport package root folder (
src/Packages/Passport
) - Double-click the
package.json
file
Install from a zip file
- Go to our Unity SDK GitHub Releases
- Click on the version you would like to install
- Download the
Immutable-Passport.zip
and extract the zip file - Open the Package Manager
- Click the add + button and select "Add package from disk..."
- Navigate to the Passport package root folder (
src/Packages/Passport
) - Double-click the
package.json
file
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 Unity SDK requires UniTask package (version 2.3.3) as specified in package.json
.
How to install UniTask
Follow the instructions here.
If you encounter any conflicts, please check out Unity's guide here.
Create a script with the following code and bind it to an object:
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Immutable.Passport;
public class InitPassport : MonoBehaviour
{
private Passport passport;
async void Start()
{
string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
string environment = Immutable.Passport.Model.Environment.SANDBOX; // or PRODUCTION
passport = await Passport.Init(clientId, environment);
}
}
Passport is now accessible from anywhere via Passport.Instance
.
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