From 041f61efe0f33e626d5d6f1e7036039b36b5f2cd Mon Sep 17 00:00:00 2001 From: Jeffrey Date: Tue, 15 Oct 2024 19:39:43 +1300 Subject: [PATCH] docs: add documentation to passport methods --- .../Public/Immutable/ImmutableDataTypes.h | 22 ++- .../Public/Immutable/ImmutablePassport.h | 160 +++++++++++++++++- 2 files changed, 173 insertions(+), 9 deletions(-) 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 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 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 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 JSConnector; + /** Cached passport init data. */ FImmutablePassportInitData InitData; FDelegateHandle BridgeReadyHandle; + /** A map of JavaScript calls request Ids to their response callbacks. */ TMap 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: