High level tour of the unity sdk
Understanding the Appearition SDK’s structure#
The SDK has been built in a way that it matches the same structure as the EMS. To understand this easily, you can head over to the EMS Portal, then API Access, and Swagger.
You will notice that each set of functionalities are stored as modules, eg ArTargetImageAndMedia.
Those same modules can be found in the SDK’s module folder, like so.
As shown above, each folder has several folders:
An API folder, containing each of the APIs currently implemented in the SDK (eg Asset/List).
Data, containing the storage classes for the EMS data for those specific APIs (eg Asset, MediaFile, etc)
Handler, which contains the main class that should be used to communicate with that specific module on the EMS.
More information about the APIs can be found in our API documentation on the developer website, available here.
Some examples of handlers are:
Account And Authentication -> AccountHandler, which contains Login, Logout and Profile features.
ArTarget Image And Media -> ArTargetHandler, which contains the CRUD functionality of the EMS Portal, allowing to manage the EMS’s content via the application.
Channel Management -> ChannelHandler, which contains utilities regarding channels, their settings and content.
Location -> LocationHandler, which contains access to the location data and Points Of Interest.
Additionally, there is a main manager called AppearitionGate, which is the core of the Appearition SDK. The Appearition Gate handles the following feature:
User Profile, containing the tokens and information being used to access the EMS.
Media utilities, to download, store and load Media and Media content easier.
EMS Ping, internet checks and other neutral communications with the EMS.
Contains all the processes currently running as coroutines.
Example of a login implementation using the Appearition SDK#
To begin with, it’s important to explain why and when it is required to login.
The Anonymous Token you entered in the Appearition Gate allows the user to access any feature which requires the lowest level of authentication (e.g. read a simplified format of a channel’s content). In order to modify the Channel’s content, a Session Token might be necessary.
The required authentication level of each feature is included in the comments of each method in each handler, like so:
Once understood, here is how to simply Login and Logout.
In order to do so, you will need to start with ensuring that the Application’s Bundle Identifier matches the one entered in the EMS Portal for the Anonymous Token you have entered. This information can be found under File > Build Settings > Player Settings > Other Settings > Bundle Identifier.
If you are working on a WebGL application, this field may not be accessible. If that’s the case, a field will appear in the AppearitionGate instead.
Once this step is complete, you can simply login using the AccountHandler.Login(username, password).
Do note that it is recommended but not mandatory to prompt your users to logout once their session is over.
Lastly, it is important to notice that each method in each handler contains several callbacks, each with their advantages and uses:
OnSuccess will only be called if the request has successfully ended. It may carry the information the user is trying to fetch as a parameter (e.g. a list of assets).
OnFailure is only called if the request has failed, due to any reasons. Its parameter contains information as for why it failed and possibly a message from the EMS when applicable.
OnComplete will be called either way, and contains a bool as a parameter to inform whether the request has successfully completed or not.
From here onwards, you should be able to explore the SDK’s Demo scenes content to have an overview of how to implement more complex features, as well as creating your own application!