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)
  • macOS (minimum version 12.5)
  • Android (minimum version 5.1)
  • iOS (minimum version 13.0)
💡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 Developer 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;
        passport = await Passport.Init(clientId, environment);
    }
}

Passport is now accessible from anywhere via Passport.Instance.

Environment​

The environment argument can be one of the following:

EnvironmentDescription
Environment.SANDBOXThe default test network (currently, it is Sepolia)
Environment.PRODUCTIONThe Ethereum mainnet network

Log into Passport​

⚠️Warning
The gamer will not have a wallet unless ZkEvmRequestAccounts 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 zkEVM, you will need to instantiate the Passport's zkEVM provider:

await passport.ConnectEvm();

and then call

await passport.ZkEvmRequestAccounts();

to initialise the gamer's wallet.

⚠️Warning

ZkEvmRequestAccounts is a resource-intensive function. To ensure optimal gaming experience and performance, it is recommended to call this function separately or asynchronously from the login process.

For example, call Login to log users into the game and let them start playing:

  • In the background, call ConnectEvm and ZkEvmRequestAccounts functions to initialise their wallet.
  • Or later, when users need to use their wallet, call ConnectEvm and ZkEvmRequestAccounts functions to initialise their wallet.

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) to re-login 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
}

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 ZkEvmRequestAccounts 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 Developer 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 instead of Login
    2. Log out: Call LogoutPKCE instead of Logout
  2. Follow the Android, iOS and macOS setup below
💡Note
To re-login the gamer to Passport using the saved credentials, continue to use Login(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.

zkEVM Send Transaction​

📋Prerequisites
  • The zkEVM send transaction feature requires pre-approval from Immutable. Please contact us before making use of it.
  • to: The destination address
  • value: The value to transfer for the transaction in wei
  • data: Byte string containing the associated data of the message
TransactionRequest request = new TransactionRequest()
{
    to = address,
    value = amount,
    data = data
}

string transactionHash = await passport.ZkEvmSendTransaction(request);

See here for more details.

Supported Functionality​

MethodDescription
LoginLog 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.
LoginPKCE(Android, iOS and macOS only) Log into Passport using Authorization Code Flow with Proof Key for Code Exchange (PKCE)
CheckStoredCredentialsCheck if there are stored credits from the previous login
GetAccessTokenGet the gamer's access token
GetIDTokenGet the gamer's ID token
LogoutLog the gamer out of Passport and remove any stored credentials.

It is recommended to be used alongside Login 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 to keep the gamer experience consistent.
GetEmailGet the gamer's email address
GetPassportIdGet the gamer's Passport ID
ConnectEvmInstantiate the zkEVM provider
ZkEvmRequestAccountsAttempt to authenticate the gamer and initialise their Passport wallet before returning an array of wallet addresses
ZkEvmGetBalanceGet the balance of the given address in wei
ZkEvmSendTransactionCreate a new message call transaction or a contract creation if the data field contains code

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​