Class UserSystem

Inheritance Relationships

Base Type

Class Documentation

class UserSystem : public csp::systems::SystemBase

Public facing system that allows interfacing with Magnopus Cloud Services’ user service.

Offers methods for creating accounts, authenticating, and retrieving user profiles.

Public Types

typedef std::function<void(const csp::common::AccessControlChangedNetworkEventData&)> UserPermissionsChangedCallbackHandler

Public Functions

const csp::common::LoginState &GetLoginState() const

Get the current login state.

Returns

LoginState : Current login state

void SetNewLoginTokenReceivedCallback(LoginTokenInfoResultCallback Callback)

Sets a callback that will get fired when the login token has changed as a result of logging in with credentials or with a token or after the Connected Spaces Platform internal system has refreshed the session.

In the callback result the token and it’s expiration time will be provided. The expiration time is in OSI format {Year}-{Month}-{Date}T{Hour}:{Min}:{Sec} For C#: register a callback to the OnNewLoginTokenReceived event

Parameters

Callback – LoginTokenInfoResultCallback : callback that gets called as described above

void Login(const csp::common::String &Email, const csp::common::String &Password, bool CreateMultiplayerConnection, const csp::common::Optional<bool> &UserHasVerifiedAge, const csp::common::Optional<TokenOptions> &TokenOptions, LoginStateResultCallback Callback)

Log in to Magnopus Cloud Services services using an email-password combination.

Parameters

  • Email – csp::common::String

  • Password – csp::common::String

  • CreateMultiplayerConnection – bool : Whether to create a multiplayer connection. If false, this session will not establish a SignalR connection to backend services, and thus be unable to receive messages or events. This session will also be unable to enter online spaces via a csp::multiplayer::OnlineRealtimeEngine. If true, this session will receive events, and may enter both online and offline spaces.

  • UserHasVerifiedAge – csp::common::Optional<bool> : An optional bool to specify whether or not the user has verified that they are over 18

  • TokenOptions – csp::common::Optional<TokenOptions> : Optional override for default token options. The default token expiry length is configured by MCS and defaults to 30 minutes. Value must be less than the default expiry length, or it will be ignored.

  • Callback – LoginStateResultCallback : callback to call when a response is received

Pre

Email must not be empty.

Pre

Password must not be empty.

void LoginWithRefreshToken(const csp::common::String &UserId, const csp::common::String &RefreshToken, bool CreateMultiplayerConnection, const csp::common::Optional<TokenOptions> &TokenOptions, LoginStateResultCallback Callback)

Resume a previous session for the associated user ID using a refresh token The refresh token can be obtained after registering a callback with SetNewLoginTokenReceivedCallback and logging in regularly.

Parameters

  • UserId – csp::common::String : User ID for the previous session

  • RefreshToken – csp::common::String : Refresh token to be used for refreshing the authentication token

  • CreateMultiplayerConnection – bool : Whether to create a multiplayer connection. If false, this session will not establish a SignalR connection to backend services, and thus be unable to receive messages or events. This session will also be unable to enter online spaces via a csp::multiplayer::OnlineRealtimeEngine. If true, this session will receive events, and may enter both online and offline spaces.

  • TokenOptions – csp::common::Optional<TokenOptions> : Optional override for default token options. The default token expiry length is configured by MCS and defaults to 30 minutes. Value must be less than the default expiry length, or it will be ignored.

  • Callback – LoginStateResultCallback : Callback when asynchronous task finishes

Pre

UserId must not be empty.

void LoginAsGuest(bool CreateMultiplayerConnection, const csp::common::Optional<bool> &UserHasVerifiedAge, const csp::common::Optional<TokenOptions> &TokenOptions, LoginStateResultCallback Callback)

Log in to Magnopus Cloud Services as a guest.

Parameters

  • CreateMultiplayerConnection – bool : Whether to create a multiplayer connection. If false, this session will not establish a SignalR connection to backend services, and thus be unable to receive messages or events. This session will also be unable to enter online spaces via a csp::multiplayer::OnlineRealtimeEngine. If true, this session will receive events, and may enter both online and offline spaces.

  • UserHasVerifiedAge – csp::common::Optional<bool> : An optional bool to specify whether or not the user has verified that they are over 18

  • TokenOptions – csp::common::Optional<TokenOptions> : Optional override for default token options. The default token expiry length is configured by MCS and defaults to 30 minutes. Value must be less than the default expiry length, or it will be ignored.

  • Callback – LoginStateResultCallback : callback to call when a response is received

void LoginAsGuestWithDeferredProfileCreation(const csp::common::Optional<bool> &UserHasVerifiedAge, LoginStateResultCallback Callback)

Log in to Magnopus Cloud Services as a guest, allowing the backend to defer profile creation and perform other optimizations.

This login method is intended only for use with offline realtime engines, and as such does not start a multiplayer connection.

Warning

Unless you have a good reason, you should prefer the regular LoginAsGuest function. This method is designed for specific non-multiplayer cases where the backend services are expecting a huge amount of anonymous profiles and wish to be allowed to buffer profile creation. For this reason, there is an undefined delay after calling this function until the session can be thought to be conceptually “logged

in”. Beware if you are calling user system methods after having logged in using this method. If you find yourself doing that, you may wish to use the regular LoginAsGuest method instead.

Parameters
csp::common::Array<EThirdPartyAuthenticationProviders> GetSupportedThirdPartyAuthenticationProviders() const

API to retrieve the Connected Spaces Platform supported 3rd party authentication providers.

Returns

Array of Connected Spaces Platform supported 3rd party authentication providers

void GetThirdPartyProviderAuthorizeURL(EThirdPartyAuthenticationProviders AuthProvider, const csp::common::String &RedirectURL, const csp::common::Optional<EThirdPartyPlatform> &ClientType, StringResultCallback Callback)

Part one of the 3rd party authentication flow Note: The steps are as follows:

  1. This step. Call this method to retrieve the Authorization URL which is required for step 2.

  2. The caller should navigate to the Authorize URL retrieved in step 1, where they will authenticate with the 3rd party provider and retrieve an auth token and state Id.

  3. Call UserSystem::LoginToThirdPartyAuthenticationProvider() with the auth token and state Id retrieved in step 2.

Calling this method will not impact your current login state.

Parameters

  • AuthProvider – : The Authentication Provider you want to be authenticated with (e.g. Google, Apple, Discord).

  • RedirectURL – : the RedirectURL you want to be used for this authentication flow.

  • ClientType – : An optional parameter that allows the client to specify their platform for the third party authentication flow. This is used for some providers to determine the format of the Authorize URL.

  • Callback – : callback that contains the Authorize URL that the Client should be navigating to for step 2.

void LoginToThirdPartyAuthenticationProvider(const csp::common::String &ThirdPartyToken, const csp::common::String &ThirdPartyStateId, bool CreateMultiplayerConnection, const csp::common::Optional<bool> &UserHasVerifiedAge, const csp::common::Optional<TokenOptions> &TokenOptions, LoginStateResultCallback Callback)

Part two of the 3rd party authentication flow Note: The steps are as follows:

  1. Call UserSystem::GetThirdPartyProviderAuthorizeURL() to retrieve the Authorize URL required for step 2.

  2. The caller should navigate to the Authorize URL retrieved in step 1, where they will authenticate with the 3rd party provider and retrieve an auth token and state Id.

  3. This step. Call this method with the auth token and state Id retrieved in step 2.

Parameters

  • ThirdPartyToken – : The authentication token returned by the Provider in step 2.

  • ThirdPartyStateId – : The state Id returned by the Provider in step 2.

  • CreateMultiplayerConnection – : Whether to create a multiplayer connection. If false, this session will not establish a SignalR connection to backend services, and thus be unable to receive messages or events. This session will also be unable to enter online spaces via a csp::multiplayer::OnlineRealtimeEngine. If true, this session will receive events, and may enter both online and offline spaces.

  • UserHasVerifiedAge – : An optional bool to specify whether or not the user has verified that they are over 18.

  • TokenOptions – : Optional override for default token options. The default token expiry length is configured by MCS and defaults to 30 minutes. The value must be less than the default expiry length, or it will be ignored.

  • Callback – : callback that contains the result of the 3rd party authentication operation.

void Logout(NullResultCallback Callback)

Logout from Magnopus Cloud Services.

Parameters

Callback – NullResultCallback : callback to call when a response is received

void CreateUser(const csp::common::Optional<csp::common::String> &DisplayName, const csp::common::String &Email, const csp::common::String &Password, bool ReceiveNewsletter, bool UserHasVerifiedAge, const csp::common::Optional<csp::common::String> &RedirectUrl, const csp::common::Optional<csp::common::String> &InviteToken, ProfileResultCallback Callback)

Creates a new user profile.

Parameters
void UpgradeGuestAccount(const csp::common::String &DisplayName, const csp::common::String &Email, const csp::common::String &Password, ProfileResultCallback Callback)

Upgrade guest user to full user profile.

Parameters
void ConfirmUserEmail(NullResultCallback Callback)

Send a confirmation email.

Parameters

Callback – NullResultCallback : callback to call when a response is received

void ResetUserPassword(const csp::common::String &Token, const csp::common::String &UserId, const csp::common::String &NewPassword, NullResultCallback Callback)

Reset the users password.

Parameters
void UpdateUserDisplayName(const csp::common::String &UserId, const csp::common::String &NewUserDisplayName, NullResultCallback Callback)

Updates the user display name information.

Parameters
void DeleteUser(const csp::common::String &UserId, NullResultCallback Callback)

Delete the user.

Note that you need permission to be able to delete the user (You can delete the user you are logged in as).

Parameters
void ForgotPassword(const csp::common::String &Email, const csp::common::Optional<csp::common::String> &RedirectUrl, const csp::common::Optional<csp::common::String> &EmailLinkUrl, bool UseTokenChangePasswordUrl, NullResultCallback Callback)

Allow a user to reset their password if forgotten by providing an email address.

Parameters
void GetProfileByUserId(const csp::common::String &InUserId, ProfileResultCallback Callback)

Get a user profile by user ID.

Parameters
void GetProfilesByUserId(const csp::common::Array<csp::common::String> &InUserIds, BasicProfilesResultCallback Callback)
void GetBasicProfilesByUserId(const csp::common::Array<csp::common::String> &InUserIds, BasicProfilesResultCallback Callback)

Get a list of minimal profiles (avatarId, personalityType, and platform) by user IDs.

Parameters
void Ping(NullResultCallback Callback)

Ping Magnopus Cloud Services.

Parameters

Callback – NullResultCallback : callback to call when a response is received

void ResendVerificationEmail(const csp::common::String &InEmail, const csp::common::Optional<csp::common::String> &InRedirectUrl, NullResultCallback Callback)

Re-send user verification email.

Parameters
void GetCustomerPortalUrl(const csp::common::String &UserId, StringResultCallback Callback)

Get the Customer Portal Url for a user from Stripe.

Parameters
void GetCheckoutSessionUrl(TierNames Tier, StringResultCallback Callback)

Get the checkout session Url for a user from Stripe.

Parameters
void SetUserPermissionsChangedCallback(UserPermissionsChangedCallbackHandler Callback)

Sets a callback for an access control changed event.

Occurs when a user’s permissions are altered, impacting their ability to interact with specific spaces. Clients can use this event to reflect access levels in real time.

Parameters

Callback – UserPermissionsChangedCallbackHandler: Callback to receive data for the user permissions that has been changed.

virtual void RegisterSystemCallback() override

Registers the system to listen for the named event.

void OnAccessControlChangedEvent(const csp::common::NetworkEventData &NetworkEventData)

Deserialises the event values of the system.

Parameters

EventValues – std::vector<signalr::value> : event values to deserialise

csp::common::IAuthContext &GetAuthContext()

The IAuthContext object is owned by the UserSystem, and will be destroyed when the UserSystem is destroyed.