Unity SDK
The Immutable SDK for Unity helps you integrate your game with Immutable Passport.
- Windows (64-bit) - Supports Mono builds. For IL2CPP, refer to this.
- macOS (minimum version 12.5)
- Android (minimum version 5.1)
- iOS (minimum version 15.2)
- WebGL
- Unity 2021.3 or newer for Windows, macOS, Android and iOS
- Unity 2019.4 or newer for macOS, Android, and iOS. Windows isn't supported on Unity versions from 2019.4 up through 2021.2.
We have added compilation flags to our Unity SDK to ensure that specific Unity editors can only build certain platform targets. Please note that the table below indicates which editor you can use to build a platform target, but it does not determine whether you can run the SDK in that editor.
For example, our SDK allows you to build iOS games using a macOS Unity Editor, but you cannot use the Windows Unity Editor.
- Target Platform: The platform you're building for
- Unity Editor Platform: The OS you're running the Unity Editor on
Target Platform | Windows | macOS | Android | iOS | WebGL |
---|---|---|---|---|---|
Windows Unity Editor | ✅ | ❌ | ✅ | ✅ | ✅ |
macOS Unity Editor | ❌ | ✅ | ✅ | ✅ | ✅ |
Installation
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.
Registering your game
Before using Passport, you must register your game as an OAuth 2.0 Native client in the Immutable Hub.
Authentication methods
There are two methods to authenticate and authorise players into Passport:
Device Code Authorisation Device Code Authorisation is available for all supported platforms. This method opens the player's default browser and guides them through the authentication flow.
Authorisation Code Flow with Proof Key for Code Exchange (PKCE) PKCE is available for Android, iOS, macOS and WebGL. This method simplifies the process by opening a pop-up window on macOS or an in-app browser on mobile devices, guiding users through the authentication flow. Once authenticated, players are automatically redirected back to the game, eliminating the need for manual switching.
Recommendation: For an optimal gaming experience on Android, iOS, macOS or WebGL, it is recommended to use the PKCE flow.
Configuration in Immutable Hub
How you configure your game in the Immutable Hub will depend on the authentication method you choose to log users into Passport.
Here's how you can configure the necessary fields when creating a client:
- Device Code Authorisation
- PKCE (Recommended for Android, iOS, macOS and WebGL)
Property | Description |
---|---|
Application Type | You must register your game as a Native client. |
Application Name | The name you wish to use to identify your game. |
Redirect URLs | This field is not used, but it is required. You can set it to your website or http://localhost:3000 . |
Logout URLs | The URL where the browser will redirect after logout is complete. |
Web Origins URLs | The Unity SDK does not utilise this field. You can leave it blank. |
Property | Description |
---|---|
Application Type | You must register your game as a Native client. |
Application Name | The name you wish to use to identify your game. |
Redirect URLs | Set your game's deep link (e.g. mygame://callback ). |
Logout URLs | Set your game's logout deep link (e.g. mygame://logout ) (this must differ from Redirect URLs). |
Web Origins URLs | The Unity SDK does not utilise this field. You can leave it blank. |
Quick Start
Initialise Passport
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.
Log into Passport
ConnectImx
is called.To log the gamer into Passport:
- Device Code Authorisation
- PKCE (Recommended for Android, iOS and macOS)
await passport.Login();
This will open the gamer's default browser and take them through the auth flow.
await passport.LoginPKCE();
This opens a pop-up window on macOS or an in-app browser on mobile devices, guiding players through the auth flow.
Initialise the provider and wallet
In order to interact with Immutable X, you will need anIMX Provider:
- Device Code Authorisation
- PKCE (Recommended for Android, iOS and macOS)
await passport.ConnectImx();
await passport.ConnectImxPKCE();
This will initialise the gamer's wallet and instantiate an IMX Provider instance.
ConnectImx
/ConnectImxPKCE
will also log the gamer into Passport (if the gamer is not already logged in), which means you may skip calling Login
/LoginPKCE
entirely.Once the IMX provider is instantiated, we need to ensure that the gamer has been registered with Immutable X:
bool isRegistered = await passport?.IsRegisteredOffchain();
if (!isRegistered)
{
await passport.RegisterOffchain();
}
Stored Credentials
Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens).
You may use
Login(useCachedSession: true)
/ConnectImx(useCachedSession: true)
to re-login/reconnect the gamer to Passport using the saved credentials.
However, if this fails, it will not automatically prompt the user to re-login again.
bool hasCredsSaved = await passport.HasCredentialsSaved();
if (hasCredsSaved)
{
await passport.Login(useCachedSession: true);
// Successfully re-logged into Passport
}
or
bool hasCredsSaved = await passport.HasCredentialsSaved();
if (hasCredsSaved)
{
await passport.ConnectImx(useCachedSession: true);
// Successfully reconnected to Passport
}
Log out of Passport
There are two ways to log out from the SDK:
Hard Logout (default): This option clears sessions from both the SDK (local) and the browser used for login. During the logout process, a browser is opened to clear the browser session.
Once the browser session is cleared, the browser redirects to the
logoutRedirectUri
that was configured during Passport initialisation. If nologoutRedirectUri
is specified, the SDK will default to using the logout redirect URI configured in the Immutable Hub client settings.Soft Logout: This option clears only the SDK's local session without affecting the browser session. No browser is opened during the process. To use soft logout, set the
hardLogout
parameter tofalse
. However, keep in mind that with this option, gamers will remain logged in to Passport in the browser until their session expires.
- Device Code Authorisation
- PKCE (Recommended for Android, iOS and macOS)
await passport.Logout(/* hardLogout: true */);
await passport.LogoutPKCE(/* hardLogout: true */);
Immutable X Transfer
- The transfers feature requires pre-approval from Immutable. Please contact us before making use of it.
To transfer tokens of type ERC20 or ERC721, use the ImxTransfer
method.
Games can only request to transfer ERC-20 tokens issued by themselves.
UnsignedTransferRequest request = UnsignedTransferRequest.ERC721(
receiver,
tokenId,
tokenAddress
);
CreateTransferResponseV1 response = await passport.ImxTransfer(request);
To transfer multiple NFT, use ImxBatchNftTransfer
:
NftTransferDetails[] details = {
new NftTransferDetails(
receiver1,
tokenId1,
tokenAddress1
),
new NftTransferDetails(
receiver2,
tokenId2,
tokenAddress2
)
};
CreateBatchTransferResponse response = await passport.ImxBatchNftTransfer(details);
Supported Functionality
Method | Description |
---|---|
Login | Logs into Passport using Device Code Authorisation. If useCachedSession is true, stored credentials will be used to re-login the gamer. If re-login fails, it will not fall back to Device Code Authorisation. |
ConnectImx | Logs into Passport using Device Code Authorisation, initialises the gamer's wallet and instantiates the IMX provider. If useCachedSession is true, stored credentials will be used to reconnect the gamer. If reconnect fails, it will not fall back to Device Code Authorisation. |
LoginPKCE | (Android, iOS and macOS only) Logs into Passport using Authorization Code Flow with Proof Key for Code Exchange (PKCE) |
ConnectImxPKCE | (Android, iOS and macOS only) Logs into Passport using Authorization Code Flow with Proof Key for Code Exchange (PKCE), initialises the gamer's wallet and instantiates the IMX provider |
CheckStoredCredentials | Checks if there are stored credits from the previous login |
GetAccessToken | Gets the gamer's access token |
GetIDToken | Gets the gamer's ID token |
Logout | Logs the gamer out of Passport and removes any stored credentials. It is recommended to be used alongside Login or ConnectImx to keep the gamer experience consistent. |
LogoutPKCE | Log the gamer out of Passport and remove any stored credentials. It is recommended to be used alongside LoginPKCE or ConnectImxPKCE to keep the gamer experience consistent. |
GetLinkedAddresses | Gets the list of external wallets the gamer has linked to their Passport account via the Dashboard. |
IsRegisteredOffchain | Checks if the logged-in gamer is registered off-chain |
RegisterOffchain | Registers a gamer to Immutable X if they are not already registered |
GetAddress | Gets the wallet address |
GetEmail | Gets the gamer's email address |
GetPassportId | Gets the gamer's Passport ID |
ImxTransfer | Sends tokens of type ERC20 or ERC721 to a receiver's address |
ImxBatchNftTransfer | Sends multiple NFT tokens in a single transaction to a receiver's address |
Examples
- Sample App - see the sample application for examples of how to use the Immutable Unity SDK.
- Sample Game - see the sample game for examples of how to use use the Immutable Unity SDK.
Further documentation
- See the Developer homepage for general information on building on Immutable.
- Build on Immutable zkEVM:
- Build on Immutable X: