Setup

Install the Passport package

💡Supported Platforms and Versions

Refer to this page for the supported platforms and Unity versions.

📋Prerequisites

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.

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.

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

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

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.

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

Initialise Passport

Create a script with the following code and bind it to an object:

Device Code Authorisation

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.

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;
 
        // 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

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>

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

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.