This article will guide the integration of Twins into applications developed with the Unity3D game engine.
The SDK is in the early stages of development, the features supported for now are:
- Opening and closing sessions with a Twin
- Communication with the Twin, even in different languages
- Receiving links and media from the Twins
- Setting context variables
Downloading the example project
To test the functionality of the SDK we provide an example scene of a Whatsapp-style chat, through which a session can be opened and a Twin can be communicated with.
The project is available at the following link https://github.com/memori-ai/Aisuru-SDK, requires Unity version 2021.3. It has not yet been tested with newer versions.
Test the communication with a Twin
Once you have opened the Unity project, open the SDKTest_GUI scene. Press play to start communication with an already configured Twin, as in the following screenshot:
Before starting, the user can set the language in the Language field and the initial question in the Question field, within the SDKTest component.
Press play in Unity to begin. To talk to a Twin there needs to be an open session, then press the Open button in the upper right corner to open a new session. When the session opens, an initial introductory question is tied to it, which in the SDK can be changed by changing the Question field set earlier.
A text field will appear at the bottom allowing questions to be asked to the Twin; the Send button confirms the question. The Twin will respond and the conversation will be shown in the center of the screen with the user's questions on the right and the Twin's answers on the left.
If a response from the Twin contains a media attachment or a link, an Open Media button will appear below the response message. Clicking it will open the attachment in the web browser.
At the end of the conversation press Close to close the session, all attachment URLs sent in the conversation will be invalidated.
Setting up a new Twin
To change the Twin you want to start the conversation with, you need to configure 2 scriptable objects: ServerData and Memori
ServerData contains, among others, the data of the user who owns the Twin. The instance of ServerData is one and is located in the ScriptableObject folder of the project.
To get the needed user data to be set in ServerData, go to the web page https://www.aisuru.com/ and select the Manage button in the widget of the Twin you want to configure. An entry in the sidebar will appear on the left with the name of the selected Twin; to access the info you need, expand the Twin's entry, click on Settings , and then on the Twin ID and Password tab at the top. Now expand Other References and copy the Owner User ID field, leave the web page open since we will need it later.
Now paste the data into the Owner ID field of the scriptable object ServerData and enter your username into the User Name field. The user name can also be obtained from the URL of the opened Web page, just after the https://www.aisuru.com/ part.
You can proceed by adding a Scriptable Object for the new Twin. Duplicate the instance present in the Scriptable Object/Memori folder and modify 2 fields with data taken from the web page left open earlier.
- The Memori (Twin) ID field you need to copy and paste it into the Memori Engine ID field in Unity.
- The Memori (Twin) ID secondary field you have to copy and paste it into Memori ID in Unity
- Set Memori Name with the full name of the Twin, including spaces
To configure the chat scene with the new Twin you have to drag the scriptable object you just created and configured into the Twin Desc field of the SDKTest component
The new Twin is now available for conversation, and when the play button is pressed, it will answer the user's questions, as in the previous paragraph.
Integrating the SDK into a Unity project.
The SDK includes an Aisuru package that contains the classes needed to communicate with Memori servers for the main features. The package is in the Packages folder of the project, and you need to copy it to the project where you want to integrate the SDK. Along with the package, also copy the contents of the Assets folder, which contains the example scenes, scripts and scriptable objects that allow easy integration with the Twins.
The implemented features are all included in the SDKTest component, in detail:
- OpenSession opens a new session and allows to indicate an initial question and a dictionary with the initial context.
- SendRequest sends a question to the Twin with the open session and takes as parameter the question to be asked to the Twin itself.
- CloseCurrentSession closes the current session.
OpenSession and SendRequest automatically handle the translation of questions and answers from the user's language to the Twin's language and vice versa.
SDKTest also contains a set of callbacks to handle responses from the server:
- OnSessionOpened when a session with a Twin is successfully opened
- OnResponseGiven when the Twin responds
- OnMediaReceived called for each attachment to the Twin's response
- OnSessionClosed when the session is closed
An example of how to use methods and callbacks to integrate communication with Twins is the code in the SDKTestUI class, which implements all Whatsapp-style chat functionality using SDKTest features.
To integrate the SDK into an existing Unity scene perform these steps:
- Copy and paste the GameObject API and SDK from the example scene.
- Configure the scriptable objects ServerData and Memori for communication with your own Twin
- Call methods and register callbacks to the SDKTest class to integrate communication with the Twin