Login with Passport

📋Prerequisites

• Setup

Passport offers three approaches for user authentication:

1. Embedded WebView Login - Login UI rendered directly within your Unity application using the PassportUI prefab (recommended for better UX)
2. Standard Login - Login handled in an external browser window or in-app browser using the basic Login() method
3. Bring Your Own Auth (Preview) - Integrate Passport with your existing authentication system

Embedded WebView Login (Recommended)

The PassportUI prefab provides a seamless, embedded authentication experience that keeps users within your application. This approach offers better user experience and higher conversion rates.

Setting up the PassportUI Prefab

💡Platform Support

• Windows: Uses Volt Unity Web Browser (UWB)
• iOS/Android/macOS: Uses Vuplex WebView (paid third-party product)

1. Add the PassportUI Prefab to Your Scene

Choose the appropriate prefab for your target platform:

• PassportLogin_Windows.prefab - For Windows builds using UWB
• PassportLogin_Vuplex.prefab - For iOS, Android, and macOS builds using Vuplex

Drag the prefab into your scene and position it as needed within your UI hierarchy.

2. Configure the PassportUI Component

The PassportUI component can be configured in the Unity Inspector:

• Client ID: Your Passport application's client ID
• Environment: Select Sandbox or Production
• Redirect URI: The callback URL for your application
• Logout Redirect URI: The callback URL for your application
• WebView Width/Height: Dimensions of the embedded WebView (default: 800x600)

3. Initialize PassportUI

The PassportUI component supports both automatic and manual initialization:

Automatic Initialization (Recommended):

// The PassportUI component will automatically initialize on Start()
// using the settings configured in the Inspector

Manual Initialization:

public class MyAuthScript : MonoBehaviour
{
    public PassportUI passportUI;
    
    async void Start()
    {
        // Initialize with existing Passport instance
        await passportUI.InitializeWithPassport(Passport.Instance);
        
        // Or initialize PassportUI with automatic Passport creation
        // (uses the clientId/environment/URIs set in the Inspector)
        await passportUI.InitializeWithPassport();
    }
}

4. Handle Authentication Events

The PassportUI component integrates with the standard Passport event system:

void Start()
{
    // Subscribe to authentication events
    Passport.Instance.OnAuthEvent += OnAuthEvent;
}

private void OnAuthEvent(PassportAuthEvent authEvent)
{
    switch (authEvent)
    {
        case PassportAuthEvent.LoginPKCESuccess:
            Debug.Log("User logged in successfully");
            // Handle successful login
            break;
        case PassportAuthEvent.LogoutPKCESuccess:
            Debug.Log("User logged out");
            // Handle logout
            break;
        case PassportAuthEvent.ReloginSuccess:
            Debug.Log("User re-logged in with cached credentials");
            break;
    }
}

Platform-Specific Setup

Windows (UWB)

• No additional packages required
• Uses Volt Unity Web Browser for easy setup
• Supports both Legacy and New Unity Input Systems

iOS/Android/macOS (Vuplex)

• Requires Vuplex WebView package (paid third-party product)
• The SDK automatically detects Vuplex availability and enables WebView features
• Uses native WebView implementations for optimal performance

💡Vuplex WebView Package

The embedded WebView login for iOS, Android, and macOS requires Vuplex WebView, a paid third-party package. You can purchase it from Vuplex's website and import it into your project. Once installed, the SDK will automatically detect and use Vuplex for embedded authentication.

Don't want to use Vuplex? You can explore free WebView packages or build your own WebView. Note that you'll need to integrate it yourself. Alternatively, you can use the standard login flow which doesn't require any WebView.

Identity-only Login

💡Note

The player will not have a wallet until the ZkEvmRequestAccounts function is called. This method retrieves user profile information only.

Customizing the Login Experience

For a more streamlined user experience, the standard Passport login prompt can be bypassed by providing the DirectLoginOptions parameter to the Login() method. This allows you to streamline the user experience by rendering a customised authentication prompt within your own application.

Once an authentication option (email, Google, Apple, or Facebook) is passed to the Login() method, an external browser window will be opened so that the user can authenticate securely.

Using Direct Login Options:

The directLoginOptions parameter accepts a DirectLoginOptions object with the following properties:

• DirectLoginMethod: The authentication provider (Email, Google, Apple, or Facebook)
• email: Required when DirectLoginMethod is Email, specifies the user's email address
• marketingConsentStatus: Marketing consent setting (OptedIn or Unsubscribed)

// Customized login with email
await passport.Login(directLoginOptions: new DirectLoginOptions(
    DirectLoginMethod.Email,
    "user@example.com",
    MarketingConsentStatus.OptedIn
));

// Customized login with specific provider
await passport.Login(directLoginOptions: new DirectLoginOptions(
    DirectLoginMethod.Google // or Apple, Facebook
));

Standard Login Prompt:

Alternatively, you can use the basic Login() method without any parameters to show the standard Passport login prompt:

await passport.Login();

This will open an external browser window on desktop or an in-app browser on mobile devices, prompting the user to select an authentication option and complete the authentication process securely.

The direct login options approach offers a more streamlined user experience, particularly for games or applications that want to feature individual authentication options in their UI, and has been shown to lead to faster user onboarding and improved conversion rates.

Bring Your Own Auth (Preview)

💡Preview Release

This feature is currently in preview and may have breaking changes in future releases.

For users who already have an existing authentication system, migrating to Passport can be uneconomical, and introducing a double login process would result in poor user experience. With Bring Your Own Auth (BYOA), you can integrate Immutable Passport with your authentication system by exchanging tokens via the BYOA API.

The BYOA integration process involves:

1. Backend Authentication Request: Once the user is authenticated with your existing system, your backend server calls the BYOA API

Note: This step requires a secret API key which you can obtain from the Immutable Hub. For more details, see API Keys.

# Use https://api.sandbox.immutable.com for sandbox
curl --location 'https://api.immutable.com/v1/token-exchange' \\
--header 'x-immutable-api-key: YOUR_SECRET_API_KEY' \\
--header 'Content-Type: application/json' \\
--data-raw '{
    "email": "user@example.com",
    "client_id": "YOUR_CLIENT_ID"
}'

2. Receive Passport Tokens: The BYOA API returns authentication tokens that your backend forwards to the application

{
  "access_token": "ACCESS_TOKEN",
  "id_token": "ID_TOKEN", 
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "expires_in": 900
}

3. Complete Authentication: Call the Passport SDK to complete authentication by passing the tokens from your backend

// Complete authentication with BYOA tokens
bool success = await passport.CompleteLogin(tokenResponse);

💡Contact Us to Use BYOA

BYOA requires whitelisting. Please contact us to get access.

Stored Credentials

Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens).

You may use Login(useCachedSession: true) to re-login the gamer to Passport using the saved credentials. However, if this fails, it will not automatically prompt the user to re-login again.

bool hasCredsSaved = await passport.HasCredentialsSaved();
if (hasCredsSaved)
{
    await passport.Login(useCachedSession: true);
    // Successfully re-logged into Passport
}