Before using Passport, you must register your application as an OAuth 2.0 Native client in the Immutable Developer Hub. First, you'll need to create a project and a testnet environment. Then you can navigate to the Passport config screen and create a passport client for your created environment. When you're ready to launch your application on the mainnet, please ensure you configure a passport client under a mainnet environment.
See here for more details.
📋 Prerequisites
git-lfs: since
.dllfiles are stored on Git Large File Storage, you must download and install git-lfs from here.
- Clone the unity-immutable-sdk repository or download the zip/tarball from one of the versions here
- Open the Package Manager
- Click the add + button and select "Add package from disk..."
- Navigate to the Passport package root folder (
src/Packages/Passport) - Double-click the
package.jsonfile
Create a script with the following code and bind it to an object:
using System.Collections;
using System.Collections.Generic;
using UnityEngine;
using Immutable.Passport;
public class InitPassport : MonoBehaviour
{
private Passport passport;
async void Start()
{
string clientId = "YOUR_IMMUTABLE_CLIENT_ID";
string environment = Immutable.Passport.Model.Environment.SANDBOX;
passport = await Passport.Init(clientId, environment);
}
}Passport is now accessible from anywhere via Passport.Instance.
We use the Device Code Authorisation flow to authenticate and authorise gamers.
await passport.Connect();This will open the gamer's default browser and take them through the auth flow.
Once the gamer is connected to Passport, the SDK will store your credentials (access, ID, and refresh tokens).
You may use await passport.ConnectSilent() to connect to Passport using the saved credentials. This is similar to Connect(). However, if the saved access token is no longer valid and the refresh token cannot be used, it will not fall back to the Device Code Authorisation flow.
try
{
bool hasCredsSaved = await passport.HasCredentialsSaved();
if (hasCredsSaved)
{
await passport.ConnectSilent();
// Successfully connected to Passport
}
}
catch (Exception)
{
// Attempted to connect to Passport silently but could not use saved credentials.
// You may prompt the gamer to connect again (e.g. await passport.Connect())
// or ignore this error and prompt the gamer to connect at another point.
}await passport.Logout();For Android and iOS you can use the PKCE login flow instead of Device Code. This means the gamer has one less step to complete and will be redirected back to the game after successfully authenticating.
To use this flow you will need to:
- Define a deep link scheme for your game (e.g.
mygame://callback) - Login to the Immutable Developer Hub and add the deeplink to your clients Callback URLs and Logout URLs
- Set this deep link as your redirect URI in the Passport Init:
Passport passport = await Passport.Init("YOUR_IMMUTABLE_CLIENT_ID", "mygame://callback");- Call
try { await ConnectPKCE(); } catch(Exception) { ... }instead ofConnect() - Follow the Android and iOS setup below
- In Unity go to Build Settings -> Player Settings -> Android -> Publishing Settings -> Enable Custom Main Manifest under the Build section
- Open the newly generated
Assets/Plugins/Android/AndroidManifest.xmlfile - Add the following code inside the
<Activity>element:
<intent-filter>
<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" />
</intent-filter>The application will now open when the device processes any link that starts with mygame://callback.
See the sample's app AndroidManifest.xml for an example.
- In Unity go to Build Settings -> Player Settings -> iOS -> Other Settings -> Supported URL schemes, increment the Size number and include your URL scheme in the Element field.
After this set-up, your game can log in using PKCE.
- In Unity go to Build Settings -> Player Settings -> Mac -> Other Settings -> Supported URL schemes, increment the Size number and include your URL scheme in the Element field.
After this set-up, your game can log in using PKCE.
Note: The transfers features require pre-approval from Immutable. Please reach out to us before making use of it.
An unsigned transfer request for ETH, ERC20 or ERC721 is expected for the ImxTransfer method.
UnsignedTransferRequest request = UnsignedTransferRequest.ERC721(
receiver,
tokenId,
tokenAddress
);
CreateTransferResponseV1 response = await passport.ImxTransfer(request);Batch NFT transfers are also supported:
NftTransferDetails[] details = {
new NftTransferDetails(
receiver1,
tokenId1,
tokenAddress1
),
new NftTransferDetails(
receiver2,
tokenId2,
tokenAddress2
)
};
CreateBatchTransferResponse response = await passport.ImxBatchNftTransfer(details);Note: The zkEVM send transaction feature requires pre-approval from Immutable. Please reach out to us before making use of it.
To: The destination addressValue: The value to transfer for the transaction in weiData: Byte string containing the associated data of the message
TransactionRequest request = new TransactionRequest()
{
To = address,
Value = amount,
Data = data
}
string? transactionHash = await passport.ZkEvmSendTransaction(request);See here for more details.
- Get wallet address
- Get access token
- Get ID token
- Get email
- Checks if there are any credentials saved
- Immutable X Transfer (ERC20, ETH and ERC721)
- Immutable X NFT Batch Transfer
- zkEVM Request Accounts
- zkEVM Get balance
- zkEVM Send transaction
- Sample code - see the sample application for examples of how to use the Immutable Unity SDK.
The following headings should be used as appropriate.
- Added
- Changed
- Deprecated
- Removed
- Fixed
What follows is an example with all the change headings, for real world use only use headings when appropriate. This goes at the top of the CHANGELOG.md above the most recent release.
...
## [Unreleased]
### Added
for new features.
### Changed
for changes in existing functionality.
### Deprecated
for soon-to-be removed features.
### Removed
for now removed features.
### Fixed
for any bug fixes.
...The package's package.json will hold the value of the previous release (e.g. src/Packages/Passport)
"version": "0.1.0",If you would like to contribute, please read the following:
- We use the Conventional Commits specification when writing our commit messages. Why use Conventional Commits? Read here.
Immutable X is open to all to build on, with no approvals required. If you want to talk to us to learn more, or apply for developer grants, click below:
To get help from other developers, discuss ideas, and stay up-to-date on what's happening, become a part of our community on Discord.
You can also join the conversation, connect with other projects, and ask questions in our Immutable X Discourse forum.
You can also apply for marketing support for your project. Or, if you need help with an issue related to what you're building with Immutable X, click below to submit an issue. Select I have a question or issue related to building on Immutable X as your issue type.
Immutable Unity SDK repository is distributed under the terms of the Apache License (Version 2.0).