Use this SDK to build Watson-powered applications in Unity.
Table of Contents
Ensure that you have the following prerequisites:
- An IBM Cloud account. If you don't have one, sign up.
- Unity. You can use the free Personal edition.
- Change the build settings in Unity (File > Build Settings) to any platform except for web player/Web GL. The Watson Developer Cloud Unity SDK does not support Unity Web Player.
You can get the latest SDK release by clicking here.
Move the unity-sdk directory into the Assets directory of your Unity project. Optional: rename the SDK directory from unity-sdk to Watson.
To create instances of Watson services and their credentials, follow the steps below.
Note: Service credentials are different from your IBM Cloud account username and password.
- Determine which services to configure.
- If you have configured the services already, complete the following steps. Otherwise, go to step 3.
- Log in to IBM Cloud at https://console.bluemix.net.
- Click the service you would like to use.
- Click Service credentials.
- Click View credentials to access your credentials.
- If you need to configure the services that you want to use, complete the following steps.
- Log in to IBM Cloud at https://console.bluemix.net.
- Click the Create service button.
- Under Watson, select which service you would like to create an instance of and click that service.
- Give the service and credential a name. Select a plan and click the Create button on the bottom.
- Click Service Credentials.
- Click View credentials to access your credentials.
- Your service credentials can be used to instantiate Watson Services within your application. Most services also support tokens which you can instantiate the service with as well.
The credentials for each service contain either a username, password and endpoint url or an apikey and endpoint url.
WARNING: You are responsible for securing your own credentials. Any user with your service credentials can access your service instances!
To get started with the Watson Services in Unity, click on each service below to read through each of their README.md's and their codes.
- Assistant
- Conversation
- Discovery
- Language Translator V2
- Language Translator V3
- Natural Language Classifier
- Natural Language Understanding
- Personality Insights
- Speech to Text
- Text to Speech
- Tone Analyzer
- Visual Recognition
Before you can use a service, it must be authenticated with the service instance's username, password and url.
using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
using IBM.Watson.DeveloperCloud.Utilities;
void Start()
{
Credentials credentials = new Credentials(<username>, <password>, <url>);
Assistant _assistant = new Assistant(credentials);
}For services that authenticate using an apikey, you can instantiate the service instance using a Credential object with an apikey and url.
Important: Instantiation with apikey works only with Visual Recognition service instances created before May 23, 2018. Visual Recognition instances created after May 22 use IAM.
using IBM.Watson.DeveloperCloud.Services.VisualRecognition.v3;
using IBM.Watson.DeveloperCloud.Utilities;
void Start()
{
Credentials credentials = new Credentials(<apikey>, <url>);
VisualRecognition _visualRecognition = new VisualRecognition(credentials);
}You can also authenticate a service using IAM authentication. You can either supply a valid access token in the iamTokenOptions or get an access token using an apikey.
void IEnumerator TokenExample()
{
// Create IAM token options and supply the apikey.
// Alternatively you can supply an access token.
TokenOptions iamTokenOptions = new TokenOptions()
{
IamApiKey = "<iam-api-key>",
IamAccessToken = "<iam-access-token>",
IamUrl = "<service-url>"
};
// Create credentials using the IAM token options
_credentials = new Credentials(iamTokenOptions, "<service-url");
while (!_credentials.HasIamTokenData())
yield return null;
_assistant = new Assistant(_credentials);
_assistant.VersionDate = "2018-02-16";
_assistant.ListWorkspaces(OnListWorkspaces, OnFail);
}
private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
{
Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
}
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
{
Log.Debug("OnFail()", "Failed: {0}", error.ToString());
}Success and failure callbacks are required. You can specify the return type in the callback.
private void Example()
{
// Call with sepcific callbacks
assistant.Message(OnMessage, OnGetEnvironmentsFail, _workspaceId, "");
discovery.GetEnvironments(OnGetEnvironments, OnFail);
}
// OnMessage callback
private void OnMessage(object resp, Dictionary<string, object> customData)
{
Log.Debug("ExampleCallback.OnMessage()", "Response received: {0}", customData["json"].ToString());
}
// OnGetEnvironments callback
private void OnGetEnvironments(GetEnvironmentsResponse resp, Dictionary<string, object> customData)
{
Log.Debug("ExampleCallback.OnGetEnvironments()", "Response received: {0}", customData["json"].ToString());
}
// OnMessageFail callback
private void OnMessageFail(RESTConnector.Error error, Dictionary<string, object> customData)
{
Log.Error("ExampleCallback.OnMessageFail()", "Error received: {0}", error.ToString());
}
// OnGetEnvironmentsFail callback
private void OnGetEnvironmentsFail(RESTConnector.Error error, Dictionary<string, object> customData)
{
Log.Error("ExampleCallback.OnGetEnvironmentsFail()", "Error received: {0}", error.ToString());
}Since the success callback signature is generic and the failure callback always has the same signature, you can use a single set of callbacks to handle multiple calls.
private void Example()
{
// Call with generic callbacks
assistant.Message(OnSuccess, OnMessageFail, "<workspace-id>", "");
discovery.GetEnvironments(OnSuccess, OnFail);
}
// Generic success callback
private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
{
Log.Debug("ExampleCallback.OnSuccess()", "Response received: {0}", customData["json"].ToString());
}
// Generic fail callback
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
{
Log.Error("ExampleCallback.OnFail()", "Error received: {0}", error.ToString());
}Custom data can be passed through a Dictionary<string, object> customData in each call. In most cases, the raw json response is returned in the customData under "json" entry. In cases where there is no returned json, the entry will contain the success and http response code of the call.
void Example()
{
Dictionary<string, object> customData = new Dictionary<string, object>();
customData.Add("foo", "bar");
assistant.Message(OnSuccess, OnFail, "<workspace-id>", "", customData);
}
// Generic success callback
private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
{
Log.Debug("ExampleCustomData.OnSuccess()", "Custom Data: {0}", customData["foo"].ToString()); // returns "bar"
}
// Generic fail callback
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
{
Log.Error("ExampleCustomData.OnFail()", "Error received: {0}", error.ToString()); // returns error string
Log.Debug("ExampleCustomData.OnFail()", "Custom Data: {0}", customData["foo"].ToString()); // returns "bar"
}You can send custom request headers by adding them to the customData object.
void Example()
{
// Create customData object
Dictionary<string, object> customData = new Dictionary<string, object>();
// Create a dictionary of custom headers
Dictionary<string, string> customHeaders = new Dictionary<string, string>();
// Add to the header dictionary
customHeaders.Add("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
// Add the header dictionary to the custom data object
customData.Add(Constants.String.CUSTOM_REQUEST_HEADERS, customHeaders);
assistant.Message(OnSuccess, OnFail, "<workspace-id>", customData: customData);
}You can get responseheaders in the customData object in the callback.
void Example()
{
assistant.Message(OnMessage, OnFail, "<workspace-id>");
}
private void OnMessage(object resp, Dictionary<string, object> customData)
{
// List all headers in the response headers object
if (customData.ContainsKey(Constants.String.RESPONSE_HEADERS))
{
foreach (KeyValuePair<string, string> kvp in customData[Constants.String.RESPONSE_HEADERS] as Dictionary<string, string>)
{
Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
}
}
}You use tokens to write applications that make authenticated requests to IBM Watson™ services without embedding service credentials in every call.
You can write an authentication proxy in IBM Cloud that obtains and returns a token to your client application, which can then use the token to call the service directly. This proxy eliminates the need to channel all service requests through an intermediate server-side application, which is otherwise necessary to avoid exposing your service credentials from your client application.
using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
using IBM.Watson.DeveloperCloud.Utilities;
void Start()
{
Credentials credentials = new Credentials(<service-url>)
{
AuthenticationToken = <authentication-token>
};
Assistant _assistant = new Assistant(credentials);
}There is a helper class included to obtain tokens from within your Unity application.
using IBM.Watson.DeveloperCloud.Utilities;
AuthenticationToken _authenticationToken;
void Start()
{
if (!Utility.GetToken(OnGetToken, <service-url>, <service-username>, <service-password>))
Log.Debug("ExampleGetToken.Start()", "Failed to get token.");
}
private void OnGetToken(AuthenticationToken authenticationToken, string customData)
{
_authenticationToken = authenticationToken;
Log.Debug("ExampleGetToken.OnGetToken()", "created: {0} | time to expiration: {1} minutes | token: {2}", _authenticationToken.Created, _authenticationToken.TimeUntilExpiration, _authenticationToken.Token);
}Documentation can be found here. You can also access the documentation by selecting API Reference the Watson menu (Watson -> API Reference).
If you are having difficulties using the APIs or have a question about the IBM Watson Services, please ask a question on dW Answers or Stack Overflow.
Find more open source projects on the IBM Github Page.
This library is licensed under Apache 2.0. Full license text is available in LICENSE.
See CONTRIBUTING.md.