Skip to content

Commit f12d235

Browse files
mediumTajmediumTaj
committed
docs: Update Readme
1 parent cae3174 commit f12d235

File tree

1 file changed

+30
-135
lines changed

1 file changed

+30
-135
lines changed

‎README.md

Lines changed: 30 additions & 135 deletions
Original file line numberDiff line numberDiff line change
@@ -32,13 +32,14 @@ Ensure that you have the following prerequisites:
3232

3333
## Configuring Unity
3434
* 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.
35-
* 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.
35+
* If using Unity 2018.2 or later you'll need to set Scripting Runtime Version and Api Compatibility Level in Build Settings to .NET 4.x equivalent. We need to access security options to enable TLS 1.2.
3636

3737
## Getting the Watson SDK and adding it to Unity
3838
You can get the latest SDK release by clicking [here][latest_release].
3939

4040
### Installing the SDK source into your Unity project
41-
Move the **`unity-sdk`** directory into the **`Assets`** directory of your Unity project. _Optional: rename the SDK directory from `unity-sdk` to `Watson`_.
41+
1. Move the **`unity-sdk`** directory into the **`Assets`** directory of your Unity project. _Optional: rename the SDK directory from `unity-sdk` to `Watson`_.
42+
2. Using the command line, from the sdk directory run `git submodule init` and `git submodule update` to get the correct commit of the SDK core.
4243

4344
## Configuring your service credentials
4445
To create instances of Watson services and their credentials, follow the steps below.
@@ -124,17 +125,12 @@ IEnumerator TokenExample()
124125

125126
_assistant = new Assistant(_credentials);
126127
_assistant.VersionDate = "2018-02-16";
127-
_assistant.ListWorkspaces(OnListWorkspaces, OnFail);
128+
_assistant.ListWorkspaces(OnListWorkspaces);
128129
}
129130

130-
private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
131+
private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
131132
{
132-
Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
133-
}
134-
135-
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
136-
{
137-
Log.Debug("OnFail()", "Failed: {0}", error.ToString());
133+
Log.Debug("OnListWorkspaces()", "Response: {0}", response.Response);
138134
}
139135
```
140136

@@ -153,23 +149,18 @@ void TokenExample()
153149

154150
_assistant = new Assistant(_credentials);
155151
_assistant.VersionDate = "2018-02-16";
156-
_assistant.ListWorkspaces(OnListWorkspaces, OnFail);
157-
}
158-
159-
private void OnListWorkspaces(WorkspaceCollection response, Dictionary<string, object> customData)
160-
{
161-
Log.Debug("OnListWorkspaces()", "Response: {0}", customData["json"].ToString());
152+
_assistant.ListWorkspaces(OnListWorkspaces);
162153
}
163154

164-
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
155+
private void OnListWorkspaces(DetailedResponse<WorkspaceCollection> response, IBMError error)
165156
{
166-
Log.Debug("OnFail()", "Failed: {0}", error.ToString());
157+
Log.Debug("OnListWorkspaces()", "Response: {0}", response.Response);
167158
}
168159
```
169160

170161
### Username and password
171162
```cs
172-
using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
163+
using IBM.Watson.Assistant.v1;
173164
using IBM.Watson.DeveloperCloud.Utilities;
174165

175166
void Start()
@@ -180,37 +171,25 @@ void Start()
180171
```
181172

182173
## Callbacks
183-
Success and failure callbacks are required. You can specify the return type in the callback.
174+
Success callbacks are required. You can specify the return type in the callback.
184175
```cs
185176
private void Example()
186177
{
187178
// Call with sepcific callbacks
188-
assistant.Message(OnMessage, OnGetEnvironmentsFail, _workspaceId, "");
189-
discovery.GetEnvironments(OnGetEnvironments, OnFail);
179+
assistant.Message(OnMessage, _workspaceId);
180+
discovery.GetEnvironments(OnGetEnvironments);
190181
}
191182

192183
// OnMessage callback
193-
private void OnMessage(object resp, Dictionary<string, object> customData)
184+
private void OnMessage(DetailedResponse<JObject> resp, IBMError error)
194185
{
195-
Log.Debug("ExampleCallback.OnMessage()", "Response received: {0}", customData["json"].ToString());
186+
Log.Debug("ExampleCallback.OnMessage()", "Response received: {0}", resp.Response);
196187
}
197188

198189
// OnGetEnvironments callback
199-
private void OnGetEnvironments(GetEnvironmentsResponse resp, Dictionary<string, object> customData)
190+
private void OnGetEnvironments(DetailedResponse<GetEnvironmentsResponse> resp, IBMError error)
200191
{
201-
Log.Debug("ExampleCallback.OnGetEnvironments()", "Response received: {0}", customData["json"].ToString());
202-
}
203-
204-
// OnMessageFail callback
205-
private void OnMessageFail(RESTConnector.Error error, Dictionary<string, object> customData)
206-
{
207-
Log.Error("ExampleCallback.OnMessageFail()", "Error received: {0}", error.ToString());
208-
}
209-
210-
// OnGetEnvironmentsFail callback
211-
private void OnGetEnvironmentsFail(RESTConnector.Error error, Dictionary<string, object> customData)
212-
{
213-
Log.Error("ExampleCallback.OnGetEnvironmentsFail()", "Error received: {0}", error.ToString());
192+
Log.Debug("ExampleCallback.OnGetEnvironments()", "Response received: {0}", resp.Response);
214193
}
215194
```
216195

@@ -219,131 +198,47 @@ Since the success callback signature is generic and the failure callback always
219198
private void Example()
220199
{
221200
// Call with generic callbacks
222-
assistant.Message(OnSuccess, OnMessageFail, "<workspace-id>", "");
223-
discovery.GetEnvironments(OnSuccess, OnFail);
201+
assistant.Message(OnSuccess, "<workspace-id>", "");
202+
discovery.GetEnvironments(OnSuccess);
224203
}
225204

226205
// Generic success callback
227-
private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
228-
{
229-
Log.Debug("ExampleCallback.OnSuccess()", "Response received: {0}", customData["json"].ToString());
230-
}
231-
232-
// Generic fail callback
233-
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
234-
{
235-
Log.Error("ExampleCallback.OnFail()", "Error received: {0}", error.ToString());
236-
}
237-
```
238-
239-
## Custom data
240-
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.
241-
242-
```cs
243-
void Example()
244-
{
245-
Dictionary<string, object> customData = new Dictionary<string, object>();
246-
customData.Add("foo", "bar");
247-
assistant.Message(OnSuccess, OnFail, "<workspace-id>", "", customData);
248-
}
249-
250-
// Generic success callback
251-
private void OnSuccess<T>(T resp, Dictionary<string, object> customData)
252-
{
253-
Log.Debug("ExampleCustomData.OnSuccess()", "Custom Data: {0}", customData["foo"].ToString()); // returns "bar"
254-
}
255-
256-
// Generic fail callback
257-
private void OnFail(RESTConnector.Error error, Dictionary<string, object> customData)
206+
private void OnSuccess<T>(DetailedResponse<T> resp, IBMError error)
258207
{
259-
Log.Error("ExampleCustomData.OnFail()", "Error received: {0}", error.ToString()); // returns error string
260-
Log.Debug("ExampleCustomData.OnFail()", "Custom Data: {0}", customData["foo"].ToString()); // returns "bar"
208+
Log.Debug("ExampleCallback.OnSuccess()", "Response received: {0}", resp.Response);
261209
}
262210
```
263211

264212
## Custom Request Headers
265-
You can send custom request headers by adding them to the `customData` object.
213+
You can send custom request headers by adding them to the service.
266214

267215
```cs
268216
void Example()
269217
{
270-
// Create customData object
271-
Dictionary<string, object> customData = new Dictionary<string, object>();
272-
// Create a dictionary of custom headers
273-
Dictionary<string, string> customHeaders = new Dictionary<string, string>();
274-
// Add to the header dictionary
275-
customHeaders.Add("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
276-
// Add the header dictionary to the custom data object
277-
customData.Add(Constants.String.CUSTOM_REQUEST_HEADERS, customHeaders);
278-
279-
assistant.Message(OnSuccess, OnFail, "<workspace-id>", customData: customData);
218+
assistant.AddHeader("X-Watson-Metadata", "customer_id=some-assistant-customer-id");
219+
assistant.Message(OnSuccess, "<workspace-id>");
280220
}
281221
```
282222

283223
## Response Headers
284-
You can get responseheaders in the `customData` object in the callback.
224+
You can get response headers in the `headers` object in the DetailedResponse.
285225

286226
```cs
287227
void Example()
288228
{
289-
assistant.Message(OnMessage, OnFail, "<workspace-id>");
229+
assistant.Message(OnMessage, "<workspace-id>");
290230
}
291231

292-
private void OnMessage(object resp, Dictionary<string, object> customData)
232+
private void OnMessage(DetailedResponse<JOBject> resp, IBMError error)
293233
{
294234
// List all headers in the response headers object
295-
if (customData.ContainsKey(Constants.String.RESPONSE_HEADERS))
235+
foreach (KeyValuePair<string, string> kvp in resp.Headers)
296236
{
297-
foreach (KeyValuePair<string, string> kvp in customData[Constants.String.RESPONSE_HEADERS] as Dictionary<string, string>)
298-
{
299-
Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
300-
}
237+
Log.Debug("ExampleCustomHeader.OnMessage()", "{0}: {1}", kvp.Key, kvp.Value);
301238
}
302239
}
303240
```
304241

305-
## Authentication Tokens
306-
307-
**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](https://console.bluemix.net/docs/services/watson/getting-started-iam.html#iam) or the [README](#IAM) in the IBM Watson SDK you use.**
308-
309-
You use tokens to write applications that make authenticated requests to IBM Watson™ services without embedding service credentials in every call.
310-
311-
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.
312-
313-
```cs
314-
using IBM.Watson.DeveloperCloud.Services.Assistant.v1;
315-
using IBM.Watson.DeveloperCloud.Utilities;
316-
317-
void Start()
318-
{
319-
Credentials credentials = new Credentials(<service-url>)
320-
{
321-
AuthenticationToken = <authentication-token>
322-
};
323-
Assistant _assistant = new Assistant(credentials);
324-
}
325-
```
326-
327-
There is a helper class included to obtain tokens from within your Unity application.
328-
329-
```cs
330-
using IBM.Watson.DeveloperCloud.Utilities;
331-
332-
AuthenticationToken _authenticationToken;
333-
334-
void Start()
335-
{
336-
if (!Utility.GetToken(OnGetToken, <service-url>, <service-username>, <service-password>))
337-
Log.Debug("ExampleGetToken.Start()", "Failed to get token.");
338-
}
339-
340-
private void OnGetToken(AuthenticationToken authenticationToken, string customData)
341-
{
342-
_authenticationToken = authenticationToken;
343-
Log.Debug("ExampleGetToken.OnGetToken()", "created: {0} | time to expiration: {1} minutes | token: {2}", _authenticationToken.Created, _authenticationToken.TimeUntilExpiration, _authenticationToken.Token);
344-
}
345-
```
346-
347242
## Streaming outside of US South region
348243
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.
349244

@@ -366,7 +261,7 @@ The Watson Unity SDK does not support IBM Cloud Private because connection via p
366261
Documentation can be found [here][documentation]. You can also access the documentation by selecting API Reference the Watson menu (**Watson -> API Reference**).
367262

368263
## Getting started videos
369-
You can view Getting Started videos for the IBM Watson SDK for Unity on [YouTube](https://www.youtube.com/watch?v=Sa5hmukwHV8&list=PLZDyxLlNKRY8MdgiUq45cZztn_f0EVz6c).
264+
You can view Getting Started videos for the IBM Watson SDK for Unity on [YouTube](https://www.youtube.com/watch?v=sNPsdUWSi34&list=PLZDyxLlNKRY9b2vurEhkSoNWZN5c5l4Nr).
370265

371266
## Questions
372267

0 commit comments

Comments
 (0)