Platform Development
The simpleAR Pro Platform Development Guide is designed for simpleAR Pro Developers to start using platform features to add User Authentication / Identity Management, Analytics Tracking, Custom Roles and Cloud-Distributed Modules to their simpleAR Pro Applications.
Introduction to the App Manager
The simpleAR Pro App Manager provides simpleAR Pro Developers with CMS and LMS capabilities directly within Unity.
Prerequisites
- simpleAR Pro Development experience (Not covered in this guide)
Launch the App Manager
- Open your Unity Project with simpleAR Pro Installed (> v2.1.x)
- Select the menu item on the top toolbar SimpleARPro > App Manager
- Login with your simpleAR Pro User credentials
Registering the Application
In order for a simpleAR Pro Application to be linked to the simpleAR Pro Platform back-end, the Application needs to be registered with the service.
- Select the App Setup menu item from the App Manager Window
- Verify the correctness of the App Name and App ID
Info
If you'd like to change the App Name and App Id before registering, do so from the File > Build Settings > Player Settings menu
- Select the Create button to complete the registration
Setting Up Identity Management
Configuring Identity Management within the simpleAR Pro App Manager enables Application access for Users in your Organization.
Info
Users must first be added to your Organization by an IT admin, or they can be added via the simpleAR Identity option in the App Manager.
- Select the simpleAR Identity menu item from the App Manager Window to start configuring access
Creating New Users
- To create a new user in your Organization with Application Access, select the Add New button
- Input a Username, Password, First Name, Last Name and Email
- If Custom App Roles are setup for the Application, assign an applicable Role for the User
Info
Users created through the App Manager are automatically granted access to the Application
Adding Users to the Application
- To add a user in your Application click on the + button
The User will now be allowed to authenticate with your simpleAR Pro Application.
Removing Users from the Application
- To remove a user from your Application click on the x button
The User will no longer be allowed to authenticate with your simpleAR Pro Application.
Using Identity Management Directives in simpleAR Pro
There are multiple simpleAR Pro Directives used to Authenticate users with the simpleAR Pro Identity Service. The following Directives can be used:
| Type | Directive | Function |
|---|---|---|
Action |
Login with simpleAR ID | This action authenticates a User with the simpleAR Pro Identity Service |
Action |
Login with Last simpleAR User | This action signs a user out from the simpleAR Pro Identity Service |
Action |
Logout simpleAR User | This action signs a user out from the simpleAR Pro Identity Service |
Action |
Get simpleAR User Info | This action gets the user details (username, first or fullname) of the currently signed in user. |
Initiator |
Login Succeeded | This initiator is callled when a simpleAR Pro User authenticates successfully |
Initiator |
Login Failed | This initiator is called when a simpleAR Pro user fails to sign-in or is logged out |
Creating Custom App Roles
Custom App Roles enable Developers to provide different experiences to different User types. Custom Roles are defined at the Application level, so Users can have differing Roles depending on the simpleAR Pro Application they're accessing.
- Select the simpleAR Roles menu item from the App Manager Window to start managing Custom Roles for the App
- Click on the Add New button to start creating a new Custom Role
- Input a Custom Role Name and Description and click Create
Custom Role Use Cases
| Use Case |
|---|
| Users with a Custom Role A should see content module A |
| Users with Role B should see content module B |
Assigning Custom App Roles
- Go to the App Manager Home menu
- Click on the simpleAR Idenity menu item
- Select the edit icon to update an existing User's role
- Select the Add Role button to assign the desired simpleAR Custom Role to the User
Creating Custom Events
What is an Event?
An Event is something that the Author of a simpleAR Pro Application wants to track and attribute to specific Users of the Application.
- Go to the App Manager Home menu
- Click on the Events menu item
- Click on the Add New button
- Input the Event info for Name, Description, Benchmark and Type
Benchmarks
Event benchmarks allow Organizations to compare a cohort or group of User's performance against a standardized value for an Event. Benchmarks are visualized in the analytics portal when comparing User performance for a selected Event.
Examples of an Event are
- Time it takes to complete a specific task for a user
- Whether a user correctly or incorrectly answered a question or completed a task
An Event is composed of the following information:
| Parameter | Description |
|---|---|
| Event Name | A descriptive name for the event that's being tracked |
| Event Description | Additional textual context for the evenn that's being tracked |
| Event Type | The type of event that's being tracked, e.g. Numeric or Boolean |
| Event Benchmark | A standardized value used to benchmark event instances against |
Types of Events
The current types of Events supported in simpleAR Pro currently include:
| Event Type | Description | Example |
|---|---|---|
String |
A simple text-based event | Track an Error in the app with specific textual information |
Boolean |
A true or false event | Track if a user completed a task succeessfully |
Number |
A numeric event with an integer or floating point value | Track the distance a user moved an object |
Time in Seconds |
A numeric event represented as seconds | The time it took a user to complete a task in seconds |
Using Event Directives in simpleAR Pro
To trigger an Event in simpleAR Pro, there's a single action Directive that be called to record an Event in the Application. The Event that's triggered will be associated with the currently logged in user.
| Type | Directive | Function |
|---|---|---|
Action |
Track simpleAR Event | Record an event instance for the currently authenticated User. Sends a Value for the event based on the specified Event Type |
Creating simpleAR Pro Modules
Modules allow Developers of simpleAR Pro Applications to host content in the cloud versus the App itself. This enables downloadable content in the Application with remote update capabilities without requiring submission of new content to the store.
Addressables
Modules were developed on top of Unity's Addressable asset system. No prior knowledge of Addressables is required since simpleAR Pro automates the creation of Addressable content and hosting in the cloud.
What is a simpleAR Pro Module?
simpleAR Modules are Unity Scene files that are hosted remotely and loaded in the Application at runtime.
In contrast to normal Scene files, Modules are not included the final Application build and can be updated / modified even after an Application is live.
Module Update Limitations
There are limitions to what can be updated / modified in Modules, these same limitations apply to any assets using Addressables system. Here's what can be updated in your modules without requiring rebuilding the Application:
| Asset Type | Can be Updated |
|---|---|
| Images / Textures / Materials | |
| Models / Animations | |
| Audio / Sounds | |
| Scene Content (GameObjects) | |
| simpleAR Sequences / Directives | |
| Custom Code / Monobehaviours |
Managing Modules in your App
- Go to the App Manager Home menu
- Click on the simpleAR Modules menu item
- Select the Manage Modules button
Adding Modules
- Select the Add New button
- Input the desired Module Name, Description and select the Scene to Modularize
Info
The Scene to Modularize must be a valid Unity Scene. Once the Module is created, it will be treated as Addressable by the Unity Addressable Asset System.
Editing and Removing Modules
- To Edit a Module, click the edit icon
Info
Only the Module Name and Description can be edited once it's created.
- To Remove a Module, click the x icon
Info
Removing a Module will not delete the associated Scene, it will just deference it as Addressable and remove it from the Modules manifest.
Using Module Directives in simpleAR Pro
A single Directive is used to interact with the Modules system to load simpleAR Modules at runtime.
| Type | Directive | Function |
|---|---|---|
Action |
Load simpleAR Module | This action loads the selected simpleAR Module when called |
Uploading and Syncing Modules to Cloud
There are two Environments for simpleAR Pro Developers to utilize when working with Modules.
| Environment | Use Case |
|---|---|
TEST |
Testing the application either locally or via the build |
PRODUCTION |
Production / LIVE application with active users |
Changing Environments
When changing Environments, creating a new Player Build is required to correctly reference the toggled Module's Environment in the Application
- Click on the simpleAR Modules menu item
- Select the Upload Modules button
Info
Modules are uploaded to the Environment currently set as active