3. Log into Passport
step_03
.ZkEvmRequestAccounts
function is called, which will be covered in step 5.In this section of the tutorial, you’ll learn how to use the Unity SDK to authenticate and authorise players into Passport using two different methods:
- Log in via the Device Code Authorisation (available for all supported platforms): This method opens the player's default browser and guides them through the authentication flow.
- Log in via the Authorisation Code Flow with Proof Key for Code Exchange (PKCE) (available for Android, iOS and macOS): This method further 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.
For optimal gaming experience on Android, iOS, or macOS, it is recommended to use the PKCE flow.
Log into Passport
In Immutable Runner, let's say players can play level one without creating or logging into a Passport account. However, to play other levels, they must log into Passport after completing level one.
To enforce this, you will prompt the players to log into Passport after they complete a level.
First, edit the LevelCompleteScreen.cs
to set up and show the "Continue with
Passport" button.
Assets/Shared/Scripts/UI/LevelCompleteScreen.cs
public void OnEnable()
{
// Set listener to 'Next' button
m_NextButton.RemoveListener(OnNextButtonClicked);
m_NextButton.AddListener(OnNextButtonClicked);
// Set listener to "Continue with Passport" button
m_ContinuePassportButton.RemoveListener(OnContinueWithPassportButtonClicked);
m_ContinuePassportButton.AddListener(OnContinueWithPassportButtonClicked);
// Hide 'Next' button
ShowNextButton(false);
// Show "Continue with Passport" button
ShowContinueWithPassportButton(true);
}
Log the player into Passport. If login fails, show the "Continue with Passport" button again so the player can retry.
- Log in via Device Code Authorisation
- Log in via PKCE (available for Android, iOS and macOS only)
To use Device Code Auth flow for Passport login, use the Login
function.
Assets/Shared/Scripts/UI/LevelCompleteScreen.cs
using Immutable.Passport;
private async void OnContinueWithPassportButtonClicked()
{
try
{
// Show loading
ShowContinueWithPassportButton(false);
ShowLoading(true);
// Log into Passport
await Passport.Instance.Login();
// Successfully logged in, show next button
// Save a persistent flag in the game that the player is logged in
SaveManager.Instance.IsLoggedIn = true;
// Successfully logged in, hide 'Logout' button
ShowLogoutButton(false);
// Reset all other values
SaveManager.Instance.Clear();
}
catch (Exception ex)
{
Debug.Log($"Failed to log out: {ex.Message}");
// Failed to log in so show 'Logout' button again
ShowLogoutButton(true);
}
// Hide loading
ShowLoading(false);
}
Logging in via PKCE is similar to logging in via Device Code Authorisation. The key difference lies in how you configure your Passport client and initialise Passport in step 2.
Passport configuration
- Return to the Immutable Hub and click on your Passport client.
- Add your game's deep links into the Redirect URLs and Logout URLs fields and clickSave Changes.
- Device Code Authorisation flow does not utilise these two fields. Therefore, whatever you input in these fields will not impact it.
- Update your Passport initialisation code to include the deep link URLs:
Assets/Shared/Scripts/UI/MainMenu.cs
// Initialise Passport
string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
string environment = Immutable.Passport.Model.Environment.SANDBOX;
string redirectUri = "immutablerunner://callback";
string logoutUri = "immutablerunner://logout";
passport = await Passport.Init(clientId, environment, redirectUri, logoutUri);
Login via PKCE
To implement the PKCE flow for Passport login, use the LoginPKCE
function.
After the player logs in to Passport through the browser, they will be redirected back to the game using the Redirect URL or deep link you set up. Step 4 will explain how the Logout URL or deep link you configured will be used.
Assets/Shared/Scripts/UI/LevelCompleteScreen.cs
private async void OnContinueWithPassportButtonClicked()
{
try
{
// Show loading
ShowContinueWithPassportButton(false);
ShowLoading(true);
// Log into Passport
await Passport.Instance.LoginPKCE();
// Successfully logged in, show next button
// Save a persistent flag in the game that the player is logged in
SaveManager.Instance.IsLoggedIn = true;
// Show 'Next' button
ShowNextButton(true);
ShowLoading(false);
}
catch (Exception ex)
{
Debug.Log($"Failed to log into Passport: {ex.Message}");
// Show Continue with Passport button again
ShowContinueWithPassportButton(true);
ShowLoading(false);
}
}
SaveManager.Instance.IsLoggedIn = true
saves a persistent flag in the game to indicate player login status. You can use this flag to determine whether to display the "Continue to Passport" button.
SaveManager
to store values. These values will be saved and carried over between game sessions. So, if you close and reopen the game, the values will remain the same as what you had set them to be in the previous session.Assets/Shared/Scripts/UI/LevelCompleteScreen.cs
public async void OnEnable()
{
// Set listener to 'Next' button
m_NextButton.RemoveListener(OnNextButtonClicked);
m_NextButton.AddListener(OnNextButtonClicked);
// Set listener to "Continue with Passport" button
m_ContinuePassportButton.RemoveListener(OnContinueWithPassportButtonClicked);
m_ContinuePassportButton.AddListener(OnContinueWithPassportButtonClicked);
// Show 'Next' button if player is already logged into Passport
ShowNextButton(SaveManager.Instance.IsLoggedIn);
// Show "Continue with Passport" button if the player is not logged into Passport
ShowContinueWithPassportButton(!SaveManager.Instance.IsLoggedIn);
}
Re-login the player
If a player has logged in previously, you can use HasCredentialsSaved
to verify if their login credentials are saved. If credentials are saved, you can automatically log them back into the Passport using Login(useCachedSession: true)
. This verification should be done when the game is launched.
As the main menu is the first screen that appears to the player after opening the game, performing this check after Passport has been initialised makes sense.
Assets/Shared/Scripts/UI/MainMenu.cs
async void OnEnable()
{
// omitted
// Initialise Passport
// omitted
// Check if the player is supposed to be logged in and if there are credentials saved
if (SaveManager.Instance.IsLoggedIn && await Passport.Instance.HasCredentialsSaved())
{
// Try to log in using saved credentials
bool success = await Passport.Instance.Login(useCachedSession: true);
// Update the login flag
SaveManager.Instance.IsLoggedIn = success;
} else {
// No saved credentials to re-login the player, reset the login flag
SaveManager.Instance.IsLoggedIn = false;
}
ShowLoading(false);
ShowStartButton(true);
}
Login(useCachedSession: true)
, regardless of whether the Device Code Auth or PKCE login flow was used.