From 81a8d8e913876ad8e99798864b04e3e431c86fe4 Mon Sep 17 00:00:00 2001 From: Jeffrey Date: Tue, 15 Oct 2024 19:39:43 +1300 Subject: [PATCH 1/2] docs: add documentation to passport methods --- .../Public/Immutable/ImmutableDataTypes.h | 23 ++- .../Public/Immutable/ImmutablePassport.h | 191 +++++++++++++++++- 2 files changed, 205 insertions(+), 9 deletions(-) diff --git a/Source/Immutable/Public/Immutable/ImmutableDataTypes.h b/Source/Immutable/Public/Immutable/ImmutableDataTypes.h index 768f9c2..ea7211a 100644 --- a/Source/Immutable/Public/Immutable/ImmutableDataTypes.h +++ b/Source/Immutable/Public/Immutable/ImmutableDataTypes.h @@ -38,29 +38,47 @@ struct FImmutableEngineVersionData FString deviceModel = FGenericPlatformMisc::GetDeviceMakeAndModel(); }; +/** + * Structure to hold initialisation 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 +176,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 adde8fb..a3e6570 100644 --- a/Source/Immutable/Public/Immutable/ImmutablePassport.h +++ b/Source/Immutable/Public/Immutable/ImmutablePassport.h @@ -52,14 +52,40 @@ 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, the "re-connect" method is used to authenticate into Passport with Immutable X. + * Else, "re-login" is used for authentication. To access a wallet with Immutable X or zkEVM later, you must call "Connect" again with this value set to true, or use "ConnectEvm." + * @param TryToRelogin If true, the game bridge will use a cached session to re-connect or re-login the user, avoiding the need for a web browser. If this attempt fails, it will fall back to device code authentication. + * @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. + * + * @param DoHardLogout If true, clears sessions and any stored credentials from both the SDK/plugin 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 +142,39 @@ 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 +218,31 @@ 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 +261,92 @@ 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 initialised. Else, initialised 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 initialised 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 initialised. + * + * @return True if the passport is initialised, 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. + * + * @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 +363,36 @@ 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 +410,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: From f55606b9d6992a30bcf0ec44093e273cc7112270 Mon Sep 17 00:00:00 2001 From: Jeffrey Date: Wed, 16 Oct 2024 15:38:45 +1300 Subject: [PATCH 2/2] docs: add documentation to passport methods (#3340) --- .../Public/Immutable/ImmutablePassport.h | 103 ++++++++++++++++-- 1 file changed, 93 insertions(+), 10 deletions(-) diff --git a/Source/Immutable/Public/Immutable/ImmutablePassport.h b/Source/Immutable/Public/Immutable/ImmutablePassport.h index a3e6570..f424543 100644 --- a/Source/Immutable/Public/Immutable/ImmutablePassport.h +++ b/Source/Immutable/Public/Immutable/ImmutablePassport.h @@ -13,7 +13,13 @@ #include "ImmutablePassport.generated.h" - +/** + * Converts a UStruct instance to a JSON string representation. + * + * @param InStruct The UStruct instance to convert. + * + * @return A JSON string representation of the input struct. + */ template FString UStructToJsonString(const UStructType& InStruct) { @@ -22,6 +28,13 @@ FString UStructToJsonString(const UStructType& InStruct) return OutString; } +/** + * Converts a JSON object to a UStruct instance. + * + * @param JsonObject The JSON object to convert into a UStruct. + * + * @return An optional UStruct instance, or an empty optional if conversion fails. + */ template TOptional JsonObjectToUStruct(const TSharedPtr& JsonObject) { @@ -50,6 +63,9 @@ class IMMUTABLE_API UImmutablePassport : public UObject friend class UImmutableSubsystem; public: + /** + * Delegate used for when passport is ready. + */ DECLARE_MULTICAST_DELEGATE(FOnPassportReadyDelegate); /** @@ -244,23 +260,45 @@ class IMMUTABLE_API UImmutablePassport : public UObject * @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 + /** + * Handle deep linking. This is called from Android JNI. + * + * @param DeepLink The deep link URL, passed from the Android JNI. This string contains the deep link data to be processed. + */ void HandleDeepLink(FString DeepLink) const; + + /* + * Handles the dismissal of custom tabs. + * + * @param Url The URL associated with the custom tab that was dismissed. + */ void HandleCustomTabsDismissed(FString Url); #elif PLATFORM_IOS | PLATFORM_MAC + /** + * Handle deep linking. This is called from Objective-C. + * + * @param DeepLink The deep link URL, passed from the iOS/Mac. This string contains the deep link data to be processed. + */ void HandleDeepLink(NSString* sDeepLink) const; #endif protected: #if PLATFORM_ANDROID + /* + * Delegate used for handling the dismissal of the PKCE flow on Android. + */ DECLARE_DELEGATE(FImtblPassportOnPKCEDismissedDelegate); #endif #if PLATFORM_ANDROID | PLATFORM_IOS | PLATFORM_MAC + /* + * Delegate used for handling deep links. + */ DECLARE_DELEGATE_OneParam(FImtblPassportHandleDeepLinkDelegate, FString); #endif - + /** * Calls JavaScript function to the connected browser with specified parameters. * @@ -351,38 +389,75 @@ class IMMUTABLE_API UImmutablePassport : public UObject // mobile platform callbacks #if PLATFORM_ANDROID | PLATFORM_IOS | PLATFORM_MAC + /** + * Callback from Get PKCE Auth URL. + * + * @param Response The JavaScript response object containing the result of the callback. + */ void OnGetPKCEAuthUrlResponse(FImtblJSResponse Response); + + /* + * Callback from Connect PKCE. + * + * @param Response The JavaScript response object containing the result of the callback. + */ void OnConnectPKCEResponse(FImtblJSResponse Response); + + /* + * Callback when deep link is activated. + * + * @param DeepLink The deep link URL that was activated. + */ void OnDeepLinkActivated(FString DeepLink); - void CompleteLoginPKCEFlow(FString Url); + + /* + * Completes the PKCE login flow using the provided URL. + * + * @param Url The URL containing the authorisation code and state. + */ + void CompleteLoginPKCEFlow(FString Url); #endif #if PLATFORM_ANDROID + /** + * Callback when Login PKCE is dismissed. + */ void HandleOnLoginPKCEDismissed(); + + /** + * Calls a static void method in Java using JNI. + * + * @param Env The JNI (Java Native Interface) environment. + * @param Class The Java class containing the method. + * @param Method The method ID of the method to call. + * @param ... Additional parameters to forward to the method to call. + */ void CallJniStaticVoidMethod(JNIEnv* Env, const jclass Class, jmethodID Method, ...); + + /** + * Launches a URL on Android using JNI. + * + * @param Url The URL to launch. + */ 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. + * @param StateIn The state flags to check. + * @return True if all StateIn flags are set, otherwise, false. */ bool IsStateFlagsSet(uint8 StateIn) const; @@ -396,14 +471,17 @@ class IMMUTABLE_API UImmutablePassport : public UObject TMap ResponseDelegates; #if PLATFORM_ANDROID + /** Delegate called when the PKCE flow is dismissed. */ FImtblPassportOnPKCEDismissedDelegate OnPKCEDismissed; #endif #if PLATFORM_ANDROID | PLATFORM_IOS | PLATFORM_MAC + /** Delegate for handling deep link activation. */ FImtblPassportHandleDeepLinkDelegate OnHandleDeepLink; // Since the second part of PKCE is triggered by deep links, saving the // response delegate here so it's easier to get FImtblPassportResponseDelegate PKCEResponseDelegate; + /** Delegate for handling PCKE logout. */ FImtblPassportResponseDelegate PKCELogoutResponseDelegate; // bool IsPKCEConnected = false; #endif @@ -421,6 +499,9 @@ class IMMUTABLE_API UImmutablePassport : public UObject void LoadPassportSettings(); private: + /** + * State flgas for Immutable Passport. + */ enum EImmutablePassportStateFlags : uint8 { IPS_NONE = 0, @@ -433,8 +514,10 @@ class IMMUTABLE_API UImmutablePassport : public UObject IPS_HARDLOGOUT = 1 << 6 }; + /** Passport state flags. */ uint8 StateFlags = IPS_NONE; + /** Pointer to the analytics manager instance for tracking events and metrics. */ UPROPERTY() class UImmutableAnalytics* Analytics = nullptr;