Use this SDK to build Watson-powered applications in Unity.
Table of Contents
Ensure that you have the following prerequisites:
- Change the build settings in Unity (File > Build Settings) to any platform except for web player/Web GL. The IBM Watson SDK for Unity does not support Unity Web Player.
- If using Unity 2018.2 or later you'll need to set Scripting Runtime Version in Build Settings to .NET 4.x equivalent. We need to access security options to enable TLS 1.2.
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 V1
- Assistant V2 (private beta)
- Compare Comply V1
- Conversation (deprecated - Use Assistant V1 or Assistant V2)
- Discovery
- Language Translator V3
- Natural Language Classifier
- Natural Language Understanding
- Personality Insights
- Speech to Text
- Text to Speech
- Tone Analyzer
- Visual Recognition
Watson services are migrating to token-based Identity and Access Management (IAM) authentication.
- With some service instances, you authenticate to the API by using IAM.
- In other instances, you authenticate by providing the username and password for the service instance.
To find out which authentication to use, view the service credentials. You find the service credentials for authentication the same way for all Watson services:
- Go to the IBM Cloud Dashboard page.
- Either click an existing Watson service instance or click Create.
- Click Show to view your service credentials.
- Copy the
urland eitherapikeyorusernameandpassword.
In your code, you can use these values in the service constructor or with a method call after instantiating your service.
Some services use token-based Identity and Access Management (IAM) authentication. IAM authentication uses a service API key to get an access token that is passed with the call. Access tokens are valid for approximately one hour and must be regenerated.
You supply either an IAM service API key or an access token:
- Use the API key to have the SDK manage the lifecycle of the access token. The SDK requests an access token, ensures that the access token is valid, and refreshes it if necessary.
- Use the access token if you want to manage the lifecycle yourself. For details, see Authenticating with IAM tokens. If you want to switch to API key, in a coroutine, override your stored IAM credentials with an IAM API key and yield until the credentials object
HasIamTokenData()returnstrue.
IEnumerator TokenExample()
{
// Create IAM token options and supply the apikey. IamUrl is the URL used to get the
// authorization token using the IamApiKey. It defaults to https://iam.bluemix.net/identity/token
TokenOptions iamTokenOptions = new TokenOptions()
{
IamApiKey = "<iam-api-key>",
IamUrl = "<iam-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());
}void TokenExample()
{
// Create IAM token options and supply the access token.
TokenOptions iamTokenOptions = new TokenOptions()
{
IamAccessToken = "<iam-access-token>"
};
// Create credentials using the IAM token options
_credentials = new Credentials(iamTokenOptions, "<service-url");
_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());
}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);
}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);
}
}
}Authenticating with the X-Watson-Authorization-Token header is deprecated. The token continues to work with Cloud Foundry services, but is not supported for services that use Identity and Access Management (IAM) authentication. For details see Authenticating with IAM tokens or the README in the IBM Watson SDK you use.
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);
}Watson services have upgraded their hosts to TLS 1.2. The US South region has a TLS 1.0 endpoint that will work for streaming but if you are streaming in other regions you will need to use Unity 2018.2 and set Scripting Runtime Version in Build Settings to .NET 4.x equivalent. In lower versions of Unity you will need to create the Speech to Text instance in US South.
You can disable SSL verifciation when making a service call.
// Create credential and instantiate service
Credentials credentials = new Credentials(<username>, <password>, <service-url>);
credentials.DisableSslVerification = true;
_service = new Assistant(credentials);
_service.VersionDate = <version-date>;
_service.DisableSslVerification = true;The Watson Unity SDK does not support IBM Cloud Private because connection via proxy is not supported in UnityWebRequest.
Documentation can be found here. You can also access the documentation by selecting API Reference the Watson menu (Watson -> API Reference).
You can view Getting Started videos for the IBM Watson SDK for Unity on YouTube.
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.