diff --git a/Source/Immutable/Public/Immutable/ImmutableDataTypes.h b/Source/Immutable/Public/Immutable/ImmutableDataTypes.h
index 768f9c23..dcc2cb41 100644
--- a/Source/Immutable/Public/Immutable/ImmutableDataTypes.h
+++ b/Source/Immutable/Public/Immutable/ImmutableDataTypes.h
@@ -38,29 +38,46 @@ struct FImmutableEngineVersionData
FString deviceModel = FGenericPlatformMisc::GetDeviceMakeAndModel();
};
+/**
+ * Structure to hold initialization data for the Immutable Passport.
+ */
USTRUCT()
struct IMMUTABLE_API FImmutablePassportInitData
{
GENERATED_BODY()
+ /** The Client Id. */
UPROPERTY()
FString clientId;
+ /**
+ * (Android, iOS, and macOS only)
+ * The URL where the browser will redirect after successful authentication.
+ */
UPROPERTY()
FString redirectUri;
+ /** The URL where the browser will redirect after logout is complete. */
UPROPERTY()
FString logoutRedirectUri;
+ /** The environment to connect to. */
UPROPERTY()
FString environment = ImmutablePassportAction::EnvSandbox;
+ /** Whether silent logout is enabled. */
UPROPERTY()
bool isSilentLogout = false;
+ /** Information about engine version */
UPROPERTY()
FImmutableEngineVersionData engineVersion;
+ /**
+ * Converts the FImmutablePassportInitData structure to a JSON string representation.
+ * @return A JSON string representation of the FImmutablePassportInitData structure.
+ * Returns an empty string if the conversion fails.
+ */
FString ToJsonString() const;
};
@@ -158,12 +175,15 @@ struct IMMUTABLE_API FImmutablePassportResult
{
GENERATED_BODY()
+ /** Whether the response was successful. */
UPROPERTY()
bool Success = false;
-
+
+ /** Error string for the response. */
UPROPERTY()
FString Error;
+ /** Response payload. */
FImtblJSResponse Response;
};
diff --git a/Source/Immutable/Public/Immutable/ImmutablePassport.h b/Source/Immutable/Public/Immutable/ImmutablePassport.h
index adde8fb4..c464178d 100644
--- a/Source/Immutable/Public/Immutable/ImmutablePassport.h
+++ b/Source/Immutable/Public/Immutable/ImmutablePassport.h
@@ -52,14 +52,36 @@ class IMMUTABLE_API UImmutablePassport : public UObject
public:
DECLARE_MULTICAST_DELEGATE(FOnPassportReadyDelegate);
+ /**
+ * Delegate used for JavaScript callbacks.
+ */
DECLARE_DELEGATE_OneParam(FImtblPassportResponseDelegate, FImmutablePassportResult);
+ /**
+ * Initialises passport. This sets up the Passport instance, configures the web browser, and waits for the ready signal.
+ * @param InitData Parameters to initialise the passport with.
+ * @param ResponseDelegate Callback delegate.
+ */
void Initialize(const FImmutablePassportInitData& InitData, const FImtblPassportResponseDelegate& ResponseDelegate);
+
+ /**
+ * Logs the user into Passport via device code auth and sets up the Immutable X provider.
+ * This will open the user's default browser and take them through Passport login.
+ * @param IsConnectImx If true, attempts to re-connect using saved credentials. Else, attempts to re-login using saved credentials.
+ * @param TryToRelogin If true, the saved access token or refresh token will be used to connect the user. If this fails, it will not fallback to device code auth.
+ * @param ResponseDelegate Callback delegate.
+ */
void Connect(bool IsConnectImx, bool TryToRelogin, const FImtblPassportResponseDelegate& ResponseDelegate);
#if PLATFORM_ANDROID | PLATFORM_IOS | PLATFORM_MAC
void ConnectPKCE(bool IsConnectImx, const FImtblPassportResponseDelegate& ResponseDelegate);
#endif
+ /**
+ * Logs the user out of Passport and removes any stored credentials.
+ * @param DoHardLogout If true, clears sessions and any stored credentials from both the SDK and the browser.
+ * Else, clears session and any stored credentials from the SDK only, browser session and stored credentials are cleared when session expires.
+ * @param ResponseDelegate Callback delegate.
+ */
void Logout(bool DoHardLogout, const FImtblPassportResponseDelegate& ResponseDelegate);
/**
@@ -116,10 +138,34 @@ class IMMUTABLE_API UImmutablePassport : public UObject
*/
void ZkEvmGetTransactionReceipt(const FZkEvmTransactionReceiptRequest& Request, const FImtblPassportResponseDelegate& ResponseDelegate);
+ /**
+ * Gets the currently saved ID token without verifying its validity.
+ * @param ResponseDelegate Callback delegate.
+ */
void GetIdToken(const FImtblPassportResponseDelegate& ResponseDelegate);
+
+ /**
+ * Gets the currently saved access token without verifying its validity.
+ * @param ResponseDelegate Callback delegate.
+ */
void GetAccessToken(const FImtblPassportResponseDelegate& ResponseDelegate);
+
+ /**
+ * Gets the wallet address of the logged in user.
+ * @param ResponseDelegate Callback delegate.
+ */
void GetAddress(const FImtblPassportResponseDelegate& ResponseDelegate);
+
+ /**
+ * Retrieves the email address of the user whose credentials are currently stored.
+ * @param ResponseDelegate Callback delegate.
+ */
void GetEmail(const FImtblPassportResponseDelegate& ResponseDelegate);
+
+ /**
+ * Gets the list of external wallets the user has linked to their Passport account via the
+ * @param ResponseDelegate Callback delegate.
+ */
void GetLinkedAddresses(const FImtblPassportResponseDelegate& ResponseDelegate);
/**
@@ -163,8 +209,25 @@ class IMMUTABLE_API UImmutablePassport : public UObject
*/
void HasStoredCredentials(const FImtblPassportResponseDelegate& ResponseDelegate);
+ /**
+ * Retrieves the "result" as string field from Response.JsonObject.
+ * @param Response The response to use to retrieve the "result" as string field.
+ * @return The "result" as string field from Response.JsonObject if Response.JsonObject is valid, otherwise, an empty string.
+ */
static FString GetResponseResultAsString(const FImtblJSResponse& Response);
+
+ /**
+ * Retrieves the "result" as bool field from Response.JsonObject.
+ * @param Response The response to use to retrieve the "result" as bool field.
+ * @return True if Response.JsonObject is valid, otherwise, false.
+ */
static bool GetResponseResultAsBool(const FImtblJSResponse& Response);
+
+ /**
+ * Retrieves the "result" as array field from Response.JsonObject and extracting them into an array of FString.
+ * @param Response The response to use to retrieve and extract.
+ * @return An array of FString extracted from the "result" field if Response.JsonObject is valid, otherwise, an empty array.
+ */
static TArray<FString> GetResponseResultAsStringArray(const FImtblJSResponse& Response);
#if PLATFORM_ANDROID
@@ -183,24 +246,80 @@ class IMMUTABLE_API UImmutablePassport : public UObject
DECLARE_DELEGATE_OneParam(FImtblPassportHandleDeepLinkDelegate, FString);
#endif
- // Calls JS with the given Action and Data, and registers the given
- // ResponseDelegate to be called when JS responds
- void CallJS(const FString& Action, const FString& Data, const FImtblPassportResponseDelegate& ClientResponseDelegate, const FImtblJSResponseDelegate& HandleJSResponse, const bool bCheckInitialized = true);
-
+ /**
+ * Calls JavaScript function to the connected browser with specified parameters.
+ * @param Action The name of the JavaScript action to be called.
+ * @param Data The data to be passed to the JavaScript action as FString.
+ * @param ClientResponseDelegate Delegate to handle the response from the client.
+ * @param HandleJSResponse Delegate to handle the response from the JavaScript function.
+ * @param bCheckInitialized (Optional) If true, check if the passport is initialized. Else, initialized checks are skipped.
+ */
+ void CallJS(const FString& Action, const FString& Data, const FImtblPassportResponseDelegate& ClientResponseDelegate, const FImtblJSResponseDelegate& HandleJSResponse, const bool bCheckInitialized = true);
+
+ /**
+ * Sets up passport with the JavaScript connector
+ * @param Connector A weak pointer to the JavaScript Connector. If the connector is invalid set up will be aborted.
+ */
void Setup(TWeakObjectPtr<class UImtblJSConnector> Connector);
+
+ /**
+ * Reinstate the connection based on the provided JavaScript response.
+ * @param Response The JavaScript response object to reinstate the connection.
+ */
void ReinstateConnection(FImtblJSResponse Response);
- // Ensures that Passport has been initialized before calling JS
+
+ /**
+ * Checks if the passport has been initialized before allowing an action to proceed.
+ * @param Action The name of the JavaScript action to be called. Used for logging purposes.
+ * @param ResponseDelegate Delegate to handle the response if the passport is not initialized.
+ * @return True if the passport is initialized, otherwise, false.
+ */
bool CheckIsInitialized(const FString& Action, const FImtblPassportResponseDelegate& ResponseDelegate) const;
- // Pulls the ResponseDelegate from the ResponseDelegates map and returns it
+
+ /**
+ * Retrieves the response delegate associated with a given JavaScript response from ResponseDelegates TMap.
+ * @param Response The Javascript response object containing the request Id.
+ * @return A TOptional containing the response delegate if found, otherwise, an empty TOptional.
+ */
TOptional<FImtblPassportResponseDelegate> GetResponseDelegate(const FImtblJSResponse& Response);
+
+ /**
+ * Confirms the device code by calling the appropriate JavaScript action.
+ * If passport is initialized, connect confirm code. Else, login confirm code.
+ * @param DeviceCode The device code to be confirmed.
+ * @param Interval The time interval to wait between attempts.
+ * @param ResponseDelegate A delegate to handle the response from the confirmation request.
+ */
void ConfirmCode(const FString& DeviceCode, const float Interval, const FImtblPassportResponseDelegate& ResponseDelegate);
- // common response callback
+ /**
+ * Common callback that handles the responses from game bridge
+ * @param Response The JavaScript response object containing the result of the callback.
+ */
void OnBridgeCallbackResponse(FImtblJSResponse Response);
- // callbacks with custom response manipulations
+
+ /**
+ * Callback from init (passport).
+ * @param Response The JavaScript response object containing the result of the callback.
+ */
void OnInitializeResponse(FImtblJSResponse Response);
+
+ /**
+ * Callback from init device flow (device code auth login flow).
+ * @param Response The JavaScript response object containing the result of the callback.
+ */
void OnInitDeviceFlowResponse(FImtblJSResponse Response);
+
+ /**
+ * Callback from logout.
+ * @param Response The JavaScript response object containing the result of the callback.
+ */
void OnLogoutResponse(FImtblJSResponse Response);
+
+ /**
+ * Callback from confirm code.
+ * @param Response The JavaScript response object containing the result of the callback.
+ */
void OnConfirmCodeResponse(FImtblJSResponse Response);
// mobile platform callbacks
@@ -217,14 +336,32 @@ class IMMUTABLE_API UImmutablePassport : public UObject
void LaunchAndroidUrl(FString Url);
#endif
+ /**
+ * Sets the specified state flags by applying a bitwise OR operation.
+ * @param StateIn The state flags to be set.
+ */
void SetStateFlags(uint8 StateIn);
+
+ /**
+ * Resets the specified state flags by applying a bitwise AND operation with the negated flags.
+ * @param StateIn The state flags to be reset.
+ */
void ResetStateFlags(uint8 StateIn);
+
+ /**
+ * Checks if the specified state flags are set.
+ * @param StateIn The state flags to check.
+ * @return True if all StateIn flags are set, otherwise, false.
+ */
bool IsStateFlagsSet(uint8 StateIn) const;
protected:
+ /** Cached pointer to the JavaScript connector used for communicating JavaScript calls. */
TWeakObjectPtr<UImtblJSConnector> JSConnector;
+ /** Cached passport init data. */
FImmutablePassportInitData InitData;
FDelegateHandle BridgeReadyHandle;
+ /** A map of JavaScript calls request Ids to their response callbacks. */
TMap<FString, FImtblPassportResponseDelegate> ResponseDelegates;
#if PLATFORM_ANDROID
@@ -242,7 +379,14 @@ class IMMUTABLE_API UImmutablePassport : public UObject
private:
+ /**
+ * Saves the current passport settings to save game object.
+ */
void SavePassportSettings();
+
+ /**
+ * Loads the passport settings from save game object.
+ */
void LoadPassportSettings();
private: