Authentication

Login

Authentication with Apex is as simple as calling the Login function. If you read the Apex API documentation you can get a better understanding of what is happening under the hood, but the SDK automates nearly everything and makes authentication a breeze.

To authenticate, you can either bundle a username and password into a LoginData object or pass a username and password to ApexSystem::Login(). You can also bundle a One-Time Code, generated on the PixoVR Platform, as the username and call ApexSystem::Login() with an empty password string.

Features of ApexSystem::Login() function are that it:

• Sends the users information to the Apex Server to login. Return TRUE.
• Returns FALSE if the password or login are of zero length.

Parameters

The ApexSystem::Login() function has 1 required parameter and 1 optional parameter:

• username:string - The email or username of the user logging in. This parameter is also used for the Assisted Login code generated on the PixoVR Platform.
• password:string - The password of the user logging in. This parameter can be left empty when using an Assisted Login code.

Authentication Responses

The Apex SDK provides a way to receive the data from the API calls. The approach in the Unity Apex SDK is done through individual event Delegates.

For Authentication, we have a success and failed delegate:

ApexSystem::OnLoginSuccess is called when the users information is valid and has access to the module.

• loginResponse:LoginResponseContent - contains information about the user that has logged in.

ApexSystem::OnLoginFailed is called when the users information is not valid, does not have access to the module or when the server is not able to be reached.

• response:FailureResponse contains the error code and error message from why the login failed.

In the Example Code section you'll see C# examples on how to bind to the event delegates.

Accessing the Authentication call in Unity

The ApexSystem is a Singleton, but also contains Static functions to access functionality like Login.

ApexSystem.Login(username, password);

Authenticated Launches

When a user launches your application from the PixoVR Hub App, a authentication token is passed. This token must be checked against the PixoVR Platform in place of a traditional Login. There are two steps you must do to accomplish this.

First, you must get the authentication token.

The property to get this is ApexSystem::PassedLoginToken. It returns an empty string or null value when there is no token available, but returns a valid string when a token is available.

If you receive a valid string from the first step, ApexSystem::LoginWithToken() allows you to login with this token.

ApexSystem::LoginWithToken() takes 1 required parameter and returns a bool.

• token:string - The authentication token that represents a currently logged in user.
• Returns TRUE on success.

If the login is a success, it will follow the above Login flow.

Example Code

Calling Login

ApexSystem.Login("pixo@pixovr.com", "123abc");

Binding to API Response Delegates

void Start()
{
  ApexSystem.Instance.OnLoginSuccess.AddListener(OnLoginSuccess);
  ApexSystem.Instance.OnLoginFailed.AddListener(OnLoginFailed);
}
 
void OnLoginFailed(FailureResponse response)
{
  // Handle failed login here...
}
 
void OnLoginSuccess(LoginResponseContent loginResponse)
{
  // Handle successful login here...
}

Q&A On Authentication

We've decided to provide some notes on questions we've been asked about authentication.

Q. Is the users information encrypted?
A. Yes, but not by anything internal to the Apex SDK or API calls. Instead, we use TLS over HTTPS.

Q. Does the Login call do anything besides log-in the user?
A. Yes, Login goes beyond and checks the user against the module to see if they have access to module. During this, we also pass back some module and user specific information which will be seen a successful login response.