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.

Log in via Device Code Authorisation

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);
    }
}

Log in via PKCE (available for Android, iOS and macOS only)

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

1. Return to the Immutable Hub and click on your Passport client.
2. 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.
   
3. 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
        // 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.