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 &UserName, 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 a username-password or email-password combination.

Parameters

  • UserName – csp::common::String

  • 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

One of either UserName or 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

As a Connected Spaces Platform user the 3rd party authentication flow consists of two steps, first calling GetThirdPartyProviderAuthoriseURL followed by LoginToThirdPartyAuthenticationProvider You can see a Sequence Diagram with all the parties involved including what a Client should be calling and when here https://miro.com/app/board/uXjVPflpu98=/.

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

Returns

Array of Connected Spaces Platform supported 3rd party authentication providers

void GetThirdPartyProviderAuthoriseURL(EThirdPartyAuthenticationProviders AuthProvider, const csp::common::String &RedirectURL, StringResultCallback Callback)

First step of the 3rd party authentication flow If you call this API but for some reason you’d like to call this again, this is supported, the params you pass second time will replace the ones you’ve passed initially.

Parameters

  • AuthProvider – EThirdPartyAuthenticationProviders : one of the supported Authentication Providers

  • RedirectURL – csp::common::String : the RedirectURL you want to be used for this authentication flow

  • Callback – StringResultCallback : callback that contains the Authorise URL that the Client should be navigating next before moving to the second Connected Spaces Platform Authentication step

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)

Second step of the 3rd party authentication flow Note: The Authentication Provider and the Redirect URL you’ve passed in the first step will be used now.

Parameters

  • ThirdPartyToken – csp::common::String : The authentication token returned by the Provider

  • ThirdPartyStateId – csp::common::String : The state Id returned by the Provider

  • 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 that contains the result of the Magnopus Cloud Services 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> &UserName, 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 &UserName, 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, userName, 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 GetAgoraUserToken(const AgoraUserTokenParams &Params, StringResultCallback Callback)

Retrieve User token from Agora.

Parameters
void PostServiceProxy(const TokenInfoParams &Params, StringResultCallback Callback)

Post Service Proxy to perform specified operation of specified service.

Parameters

  • Params – const TokenInfoParams& : Params to specify service, operation, set help and parameters

  • Callback – StringResultCallback : 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.

virtual void DeregisterSystemCallback() override

Deregisters the system from listening 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.