Skip to content

docs: add documentation to passport methods #142

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

docs: add documentation to passport methods #142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 21 additions & 1 deletion Source/Immutable/Public/Immutable/ImmutableDataTypes.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
};

Expand Down Expand Up @@ -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;
};

Expand Down
160 changes: 152 additions & 8 deletions Source/Immutable/Public/Immutable/ImmutablePassport.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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);

/**
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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:
Expand Down
Loading