Skip to main content

3. Log into Passport

💡Info
The complete code for this step can be found in the branch named step_03.
⚠️Warning
Logging into Passport does not automatically create a wallet. A wallet is only created when the 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:

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

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

💡Save Manager
The game uses a class called 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);
}
💡Note
To re-login the player into the game using saved credentials, always use Login(useCachedSession: true), regardless of whether the Device Code Auth or PKCE login flow was used.