Skip to main content

Unreal SDK

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

Sections
💡Supported Platforms
  • Windows (64-bit)
  • macOS (minimum version 10.5)
  • Android (minimum version 8.0)
  • iOS (minimum version 13.0)
💡Supported Unreal Versions

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.

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.

Redirect URLs​

On Android, iOS and macOS clients, you should set your application's deep link scheme (e.g. mygame://callback) if you wish to make use of PKCE login, otherwise set the same as Logout URLs.

PKCE login is not supported on Windows clients. Hence, they do not use Redirect URLs. You may set Redirect URLs to be the same as Logout URLs, as it is a required field.

Web Origins URLs​

  • For Unreal Engine 5.0 and above you may leave it blank.
  • For Unreal Engine versions between 4.26 and 5.0. Add file:// to the list of Web Origins URLs. This is required to work with Blui browser.

See here for more details.

Installation​

  1. 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
  2. Clone the unreal-immutable-sdk repository or download the zip/tarball from one of the versions here
  3. Copy the cloned repo into your project's Plugins folder, e.g.: MyGame/Plugins/unreal-immutable-sdk
  4. Restart your project (Unreal Editor & Jetbrains Rider IDE), upon restart it should load the unreal-sdk-plugin and should be good to use
💡Note on the CEF plugin
For Unreal Engine 4.26 and above, we use Blui as a browser instead of the inbuilt browser. Install the Blui Plugin by copying this repository to your project's `Plugins` folder. Please update immutable.uplugin -> Plugins -> WebBrowserWidget to false and restart your UE4 editor. For Unreal Engine 5.0 and above, we use the inbuilt browser.

Setup​

Blueprint​

See the included sample widgets in All->Plugins->Immutable Content in the Unreal Editor content browser for examples of how to use the plugin in Blueprint. If you don't see a Plugins folder under All you may need to enable Show Plugin Content in the content browser's Settings menu.

C++​

Check out the ImmutablePassport.h file for the C++ Passport API. In order to know the list of methods to call for the Passport Login Flow and the Passport Log out Flow, follow the same sequence of steps as the Blueprint widget examples below.

Quick Start​

Log into Passport​

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

To log the gamer into Passport

Passport Login Blueprint

  1. Login blueprint node has to be called. This will open the gamer's default browser and take them through the auth flow.
  2. Then, in order to interact with Immutable zkEVM, you will need to instantiate the Passport's zkEVM provider via ConnectEvm.
  3. Call ZkEvmRequestAccounts blueprint node to initialise the gamer's wallet.
⚠️Warning
The gamer will not have a wallet unless ZkEvmRequestAccounts is called.

Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens). If assign useCachedSession to true, while using Login blueprint node, stored credentials will be used to relogin the gamer. If relogin fails, it will fall back to Device Code Authorisation.

💡Info
The environment argument can be one of the following:

EnvironmentDescription
sandboxThe default test network (currently, it is Sepolia)
productionThe Ethereum mainnet network

The RedirectUri and LogoutUri fields are not required for the Device Code Authorisation flow and can be left empty however they are required for PKCE login flow

Log out of Passport​

To initiate the logout process in Passport, utilise the Logout node demonstrated below. Two logout options are available:

  1. Hard Logout: This option clears sessions from both the SDK (local) and the browser used for login. The SDK will open a browser to clear the browser session during the logout process.
  2. Soft Logout: If there is a desire to bypass opening the browser during the logout process, set the DoHardLogout parameter to false. This will perform only a local logout, and gamers will remain logged in to Passport in the browser until the session expires.

Passport Logout Blueprint

Android, iOS and macOS PKCE login​

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

For Android, iOS and macOS, you can use the Authorization Code Flow with Proof Key for Code Exchange (PKCE) login flow instead of Device Code Authorisation. 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://callback/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 Initialise
  4. Call LoginPKCE instead of Login

Passport PKCE Login Blueprint

Unreal Editor Android setup​

  1. Create an Unreal Plugin Language XML file (e.g. Source/MyGame/MyGame_UPL_Android.xml) and add the following code:
<?xml version="1.0" encoding="utf-8"?>
<root xmlns:android="http://schemas.android.com/apk/res/android">
    <androidManifestUpdates>
        <addElements tag="application">
            <activity
                    android:name="com.immutable.unreal.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:host="callback" android:scheme="mygame" />
                    <data android:host="logout" android:scheme="mygame" />
                </intent-filter>
            </activity>
        </addElements>
    </androidManifestUpdates>
</root>
  1. Open your game's build file (e.g. Source/MyGame/MyGame.Build.cs) and add:
if (Target.Platform == UnrealTargetPlatform.Android)
{
  string MyPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
  AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(MyPath, "MyGame_UPL_Android.xml"));
}

Your game will now open when the device processes any link that starts with mygame://callback or mygame://logout.

Unreal Editor iOS setup​

  1. In Unreal Editor go to Project Settings -> iOS -> Extra PList Data
  2. Add the following code inside the Additional Plist Data field:
<key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>mygame</string></array></dict></array>

After this set-up and the redirect URI you set in Initialize Passport, your game can log in using mygame://callback.

Unreal Editor macOS setup​

Since there is no way to add extra plist data like iOS from the Unreal Editor Project Settings, you will need to edit the Engine's default Info.plist.

  1. In your preferred IDE, open the engine's Info.plist file (e.g. Engine/Source/Runtime/Launch/Resources/Mac/Info.plist)
  2. Add the following code inside the root <dict>...</dict>:
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>mygame</string>
        </array>
    </dict>
</array>

After setting up and specifying the redirect URI in Initialize Passport, the user will be automatically redirected back to the game through mygame://callback upon completing the login process.

See the sample game for an example of how to set up PKCE for Android, iOS and macOS.

zkEVM Send Transaction​

📋Prerequisites
  • The zkEVM send transaction requires pre-approval from Immutable. Please contact us before making use of it.
  • Must have first called `ConnectEvm` to set up the zkEVM provider and `ZkEvmRequestAccounts` to login the user.

To send a transaction on zkEVM use UImmutablePassport::ZkEvmSendTransaction method. See this Blueprint example showing how to use Zk Evm Send Transaction.

See here for more details.

Zk Evm Send Transaction

Supported Functionality​

MethodDescription
InitializePassportInitialises Passport
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 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)
LogoutLog out Passport
HasStoredCredentialsCheck if there are stored credits from the previous login
GetEmailGet the email address associated with the wallet address
GetAccessTokenGet Passport user's access token
GetIdTokenGet Passport user's ID token
ConnectEvmInitialise the zkEVM provider
ZkEvmRequestAccountsAttempt to authenticate the user 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 Blueprints - see the sample blueprints for examples of how to use the Immutable Unreal SDK.
  • Sample Game - see the sample game for an example of how to use the Immutable Unreal SDK.

Further documentation​