satoshirobatofujimoto / unity-sdk

:video_game: Unity SDK to use the IBM Watson services.

Watson APIs Unity SDK

Use this SDK to build Watson-powered applications in Unity.

Table of Contents

• Before you begin
• Getting the Watson SDK and adding it to Unity
  • Installing the SDK source into your Unity project
• Configuring your service credentials
• Authentication
• Watson Services
• Authentication Tokens
• Documentation
• Questions
• Open Source @ IBM
• License
• Contributing

Before you begin

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.

Getting the Watson SDK and adding it to Unity

You can get the latest SDK release by clicking here.

Installing the SDK source into your Unity project

Move the unity-sdk directory into the Assets directory of your Unity project. Optional: rename the SDK directory from unity-sdk to Watson.

Configuring your service credentials

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.

1. Determine which services to configure.
2. If you have configured the services already, complete the following steps. Otherwise, go to step 3.
   1. Log in to IBM Cloud at https://console.bluemix.net.
   2. Click the service you would like to use.
   3. Click Service credentials.
   4. Click View credentials to access your credentials.
3. If you need to configure the services that you want to use, complete the following steps.
   1. Log in to IBM Cloud at https://console.bluemix.net.
   2. Click the Create service button.
   3. Under Watson, select which service you would like to create an instance of and click that service.
   4. Give the service and credential a name. Select a plan and click the Create button on the bottom.
   5. Click Service Credentials.
   6. Click View credentials to access your credentials.
4. 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!

Watson Services

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.

• Alchemy Language Deprecated
• Conversation
• Discovery
• Document Conversion Deprecated
• Language Translator
• Natural Language Classifier
• Natural Language Understanding
• Personality Insights
• Retrieve and Rank Deprecated
• Speech to Text
• Text to Speech
• Tone Analyzer
• Tradeoff Analytics Deprecated
• Visual Recognition

Authentication

Before you can use a service, it must be authenticated with the service instance's username, password and url.

using IBM.Watson.DeveloperCloud.Services.Conversation.v1;
using IBM.Watson.DeveloperCloud.Utilities;

void Start()
{
    Credentials credentials = new Credentials(<username>, <password>, <url>);
    Conversation _conversation = new Conversation(credentials);
}

For services that authenticate using an apikey, you can instantiate the service instance using a Credential object with an apikey and url.

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);
}

Callbacks

Success and failure callbacks are required. You can specify the return type in the callback.

private void Example()
{
    //  Call with sepcific callbacks
    conversation.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
    conversation.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

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");
    conversation.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"
}

Authentication Tokens

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.Conversation.v1;
using IBM.Watson.DeveloperCloud.Utilities;

void Start()
{
    Credentials credentials = new Credentials(<service-url>)
    {
        AuthenticationToken = <authentication-token>
    };
    Conversation _conversation = new Conversation(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

Documentation can be found here. You can also access the documentation by selecting API Reference the Watson menu (Watson -> API Reference).

Questions

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.

Open Source @ IBM

Find more open source projects on the IBM Github Page.

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.

Contributing

See CONTRIBUTING.md.