Skip to main content

Unity SDK

The Immutable SDK for Unity helps you integrate your game with Immutable Passport.

Sections
💡Supported Platforms
  • Windows (64-bit): Supports Mono builds. For IL2CPP support, see the Custom Windows WebView guide.
  • macOS: Requires version 12.5 or later.
  • Android: Requires version 10 or later.
  • iOS: Requires version 15.2 or later.
  • WebGL: Not officially supported.
💡Supported Unity Versions
Unity 2021.3 and newer are supported.
💡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 PlatformWindowsmacOSAndroidiOSWebGL
Windows Unity Editor✅❌✅✅✅
macOS Unity Editor❌✅✅✅✅

Installation​

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.

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:

  1. Authorisation Code Flow with Proof Key for Code Exchange (PKCE) is available for Android, iOS, macOS and WebGL (not officially supported). This method provides a seamless and secure authentication experience by opening a pop-up window on macOS or an in-app browser on mobile devices. Players are automatically redirected back to the game once authenticated, eliminating manual switching.

  2. Device Code Authorisation is available for Windows, Android, iOS and macOS. This method opens the player's default browser and guides them through the authentication flow.

💡Recommendation
Whenever possible, use the PKCE flow as it is the most secure and seamless method for authentication on Android, iOS and macOS.

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:

PropertyDescription
Application TypeYou must register your game as a Native client.
Application NameThe name you wish to use to identify your game.
Redirect URLsSet your game's deep link (e.g. mygame://callback).
Logout URLsSet your game's logout deep link (e.g. mygame://logout) (this must differ from Redirect URLs).
Web Origins URLsThe 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:

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.

Log into Passport​

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

To log the gamer into Passport:

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:

await passport.ConnectImxPKCE();

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

💡Note
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:

  1. 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 no logoutRedirectUri is specified, the SDK will default to using the logout redirect URI configured in the Immutable Hub client settings.

  2. 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 to false. However, keep in mind that with this option, gamers will remain logged in to Passport in the browser until their session expires.

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

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

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 gamer 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 – Explore the sample application for examples on how to use each Immutable Unity SDK function.

Further documentation​

IMX Whitepaper • IMX Tokenomics • Block Explorer • Careers • Contact Us