Skip to main content

Unity SDK


💡Supported Platforms
  • Windows (64-bit)
  • macOS (minimum version 12.5)
  • Android (minimum version 5.1)
  • iOS (minimum version 15.2)
💡Supported Unity Versions
  • 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.
💡Target Platform vs Unity Editor Platform

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 PlatformWindowsmacOSAndroidiOS
Windows Unity Editor
macOS Unity Editor

Registering your game

Before using Passport, you must register your application as an OAuth 2.0 Native client in the Immutable Hub.

First, you'll need to create a project and a testnet environment. Then, you can navigate to the Passport config screen and create a passport client for your created environment. When you're ready to launch your application on the mainnet, please ensure you configure a passport client under a mainnet environment.

Here's how you can configure the fields while creating a client:

Creating an OAuth2.0 Native client

Application Type

This field is required.

You must register your application as an OAuth 2.0 Native client.

Client name

This field is required.

The name you wish to use to identify your application.

Redirect URLs

This field is required.

If you wish to use PKCE login on Android, iOS and macOS clients, you must set your application's deep link (e.g. mygame://callback). Otherwise, set it to your website or https://localhost:3000.

Windows clients do not support PKCE login, so they do not use Redirect URLs.

Logout URLs

This field is required.

If you wish to use PKCE login on Android, iOS and macOS clients, you must set your application's logout deep link (e.g. mygame://logout). The deep link for Logout URLs must differ from Redirect URLs. Otherwise, use your website, https://localhost:3000 or set it to be the same as Redirect URLs.

Windows clients do not support PKCE login, so Logout URLs are unused.

Web Origins URLs

The Unity SDK doesn't utilise this field. You may leave it blank.

See here for more details.

Installation

Install by cloning the repository

  1. Since .dll files are stored on Git Large File Storage, you must download and install git-lfs from here before cloning the repository
  2. Clone the unity-immutable-sdk repository or download the zip/tarball from one of the versions here
  3. Open the Package Manager
  4. Click the add + button and select "Add package from disk..."
  5. Navigate to the Passport package root folder (src/Packages/Passport)
  6. Double-click the package.json file

Install from a zip file

  1. Go to our Unity SDK GitHub Releases
  2. Click on the version you would like to install
  3. Download the Immutable-Passport.zip and extract the zip file
  4. Open the Package Manager
  5. Click the add + button and select "Add package from disk..."
  6. Navigate to the Passport package root folder (src/Packages/Passport)
  7. Double-click the package.json file

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 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.

Quick Start

Initialise Passport

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.

Log into Passport

⚠️Warning
The gamer will not have a wallet unless ConnectImx is called.

We use the Device Code Authorisation flow to authenticate and authorise gamers.

To log the gamer into Passport:

await passport.Login();

This will open the gamer's default browser and take them through the auth flow.

Initialise the provider and wallet

In order to interact with Immutable X, you will need an IMX Provider:

await passport.ConnectImx();

This will initialise the gamer's wallet and instantiate an IMX Provider instance.

💡Note
ConnectImx will also log the gamer into Passport (if the gamer is not already logged in), which means you may skip calling Login 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 fall back to the Device Code Authorisation flow.

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

To fully log out of Passport, you must clear sessions from both the SDK (local) and the browser used to log in. This requires the SDK to open a browser to clear the browser session when logging out.

To perform a full/hard logout, call:

await passport.Logout(/* hardLogout: true */);

If you don't want the browser to open during the logout process, you can skip logging out of the browser and only perform a local logout by setting hardLogout to false. However, if you choose to do so, gamers will stay logged in to Passport in the browser until the session expires.

Android, iOS and macOS PKCE login and logout

⚠️Warning
The gamer will not have a wallet unless ConnectImxPKCE is called.

For Android, iOS and macOS you can use the PKCE login flow instead of Device Code. This means the gamer has one less step to complete and will be redirected back to the game after successfully authenticating.

To use this flow you will need to:

  1. Define a deep link scheme for your game (e.g. mygame://callback for logging in and mygame://logout for logging out)
  2. Login to the Immutable Hub and add the deep links to your clients Redirect URLs and Logout URLs
  3. Set this deep links as your redirect URI and logout redirect URI in the Passport Init:
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;
string redirectUri = "mygame://callback";
string logoutRedirectUri = "mygame://logout";
passport = await Passport.Init(clientId, environment, redirectUri, logoutRedirectUri);
}
}
  1. To:
    1. Log in: Call LoginPKCE/ConnectImxPKCE instead of Login/ConnectImx
    2. Log out: Call LogoutPKCE instead of Logout
  2. Follow the Android, iOS and macOS setup below
💡Note
To re-login/reconnect the gamer to Passport using the saved credentials, continue to use Login(useCachedSession: true)/ConnectImx(useCachedSession: true). See Stored Credentials for more details.

Android setup

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>
  1. 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 setup

  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.

macOS setup

No additional setup is required.

Immutable X Transfer

📋Prerequisites
  • 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. Note that 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

MethodDescription
LoginLogs 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.
ConnectImxLogs 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
CheckStoredCredentialsChecks if there are stored credits from the previous login
GetAccessTokenGets the gamer's access token
GetIDTokenGets the gamer's ID token
LogoutLogs 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.
LogoutPKCELog 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.
GetLinkedAddressesGets the list of external wallets the user has linked to their Passport account via the Dashboard.
IsRegisteredOffchainChecks if the logged-in gamer is registered off-chain
RegisterOffchainRegisters a gamer to Immutable X if they are not already registered
GetAddressGets the wallet address
GetEmailGets the gamer's email address
GetPassportIdGets the gamer's Passport ID
ImxTransferSends tokens of type ERC20 or ERC721 to a receiver's address
ImxBatchNftTransferSends 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

IMX Whitepaper IMX Tokenomics Block Explorer Careers Contact Us