Swiftpack.co - Package - watson-developer-cloud/swift-sdk

Watson Developer Cloud Swift SDK

Build Status Carthage Compatible Documentation CLA assistant wdc-community.slack.com

Overview

The Watson Developer Cloud Swift SDK makes it easy for mobile developers to build Watson-powered applications. With the Swift SDK you can leverage the power of Watson's advanced artificial intelligence, machine learning, and deep learning techniques to understand unstructured data and engage with mobile users in new ways.

There are many resources to help you build your first cognitive application with the Swift SDK:

Contents

General

Services

This SDK provides classes and methods to access the following Watson services.

Before you begin

Requirements

  • Xcode 9.3+
  • Swift 4.2+
  • iOS 10.0+

3.0.0 Preview

We have made a preview of the upcoming 3.0.0 release of the SDK available to use! Version 3.0.0 introduces a new authentication scheme for all services, as well as breaking changes to the API response models returned by the Swift SDK.

Install the 3.0.0 preview

Carthage

See the Carthage section of the Installation guide.

To build your project using the 3.0.0 preview, modify the Watson entries in your Cartfile like so:

github "watson-developer-cloud/swift-sdk" "preview-3.0.0-rc1"
github "watson-developer-cloud/restkit" "preview-4.0.0-rc1"

Then run carthage update to rebuild your dependencies.

Swift Package Manager

See the Swift Package Manager section of the Installation guide.

To build your project using the 3.0.0 preview, modify the depedencies section in your Package.swift like so:

dependencies: [
    .package(url: "https://github.com/watson-developer-cloud/restkit.git", .branch: "preview/4.0.0-rc1"),
    .package(url: "https://github.com/watson-developer-cloud/swift-sdk.git", .branch: "preview/3.0.0-rc1")
],

Then rebuild your project to get the latest SDK

Cocoapods

We currently have not released a preview binary for Cocoapods. If you would like the preview release to be available via Cocoapods, please let us know in an issue!

Migrating to version 3.0.0

Version 3.0.0 introduced breaking changes that affect all frameworks of the Swift SDK. Please refer to the migration guide for information on how to get up and running with the new version.

Installation

The IBM Watson Swift SDK can be installed with Cocoapods, Carthage, or Swift Package Manager.

Cocoapods

You can install Cocoapods with RubyGems:

$ sudo gem install cocoapods

If your project does not yet have a Podfile, use the pod init command in the root directory of your project. To install the Swift SDK using Cocoapods, add the services you will be using to your Podfile as demonstrated below (substituting MyApp with the name of your app). The example below shows all of the currently available services; your Podfile should only include the services that your app will use.

use_frameworks!

target 'MyApp' do
    pod 'IBMWatsonAssistantV1', '~> 3.0.0'
    pod 'IBMWatsonAssistantV2', '~> 3.0.0'
    pod 'IBMWatsonCompareComplyV1', '~> 3.0.0'
    pod 'IBMWatsonDiscoveryV1', '~> 3.0.0'
    pod 'IBMWatsonLanguageTranslatorV3', '~> 3.0.0'
    pod 'IBMWatsonNaturalLanguageClassifierV1', '~> 3.0.0'
    pod 'IBMWatsonNaturalLanguageUnderstandingV1', '~> 3.0.0'
    pod 'IBMWatsonPersonalityInsightsV3', '~> 3.0.0'
    pod 'IBMWatsonSpeechToTextV1', '~> 3.0.0'
    pod 'IBMWatsonTextToSpeechV1', '~> 3.0.0'
    pod 'IBMWatsonToneAnalyzerV3', '~> 3.0.0'
    pod 'IBMWatsonVisualRecognitionV3', '~> 3.0.0'
end

Run the pod install command, and open the generated .xcworkspace file. To update to newer releases, use pod update.

When importing the frameworks in source files, exclude the IBMWatson prefix and the version suffix. For example, after installing IBMWatsonAssistantV1, import it in your source files as import Assistant.

For more information on using Cocoapods, refer to the Cocoapods Guides.

Carthage

You can install Carthage with Homebrew:

$ brew update
$ brew install carthage

If your project does not have a Cartfile yet, use the touch Cartfile command in the root directory of your project. To install the IBM Watson Swift SDK using Carthage, add the following to your Cartfile.

github "watson-developer-cloud/swift-sdk" ~> 3.0.0

Then run the following command to build the dependencies and frameworks:

$ carthage bootstrap --platform iOS

Follow the remaining Carthage installation instructions here. Note that the above command will download and build all of the services in the IBM Watson Swift SDK. Make sure to drag-and-drop the built frameworks (only for the services your app requires) into your Xcode project and import them in the source files that require them. The following frameworks need to be added to your app:

  1. RestKit.framework
  2. Whichever services your app will be using (AssistantV1.framework, DiscoveryV1.framework, etc.)
  3. (Speech to Text only) Starscream.framework

If your app fails to build because it is built with a different version of Swift than the downloaded SDK, then re-run the carthage update command with the --no-use-binaries flag added.

Swift Package Manager

Add the following to your Package.swift file to identify the IBM Watson Swift SDK as a dependency. The package manager will clone the Swift SDK when you build your project with swift build.

dependencies: [
    .package(url: "https://github.com/watson-developer-cloud/swift-sdk", from: "3.0.0")
]

Authentication

The Identity and Access Management (IAM) service of the IBM Cloud is the primary method of authentication to IBM Cloud services. Some service instances may use an alternate form of authentication, such as basic authentication (username and password).

Getting credentials

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:

  1. Go to the IBM Cloud Dashboard page.
  2. Either click an existing Watson service instance in your resource list or click Create resource > AI and create a service instance.
  3. Click on the Manage item in the left nav bar of your service instance.

On this page, you will see your credentials to use in the SDK to access your service instance.

Supplying credentials

The SDK provides separate init methods for each form of authentication that may be used by instances of the service.

  • For service instances that use IAM authentication, the SDK provides two init methods -- one that accepts an apikey and another that accepts an access token created from an apikey. If you use the init method that supplies the apikey, the SDK will obtain an access token and refresh it when needed. If you initialize the SDK with the method that supplies an access token, you will need to periodically refresh the token as they expire after a short time. Learn more about IAM.

  • For service instances that use basic authentication (username and password), use the init method that specifies the username and password.

Credentials in the environment or a local credentials file

The SDK can extract service credentails from the environment, e.g. the VCAP_SERVICES environment variable, or a local credentials file.

To use credentials stored in a local file, go to the Manage tab of your service instance on IBM Cloud, and click on the button to download the credentials. The file will be called ibm-credentials.env. Add this file to a location that is accessible from your project. For iOS apps, make sure to add it to the application target.

let discovery = Discovery(version: "your-version")

If your project is using multiple Watson services, you can merge the contents of the ibm-credentials.env files into a single file. Lines in the file can be added, deleted, or reordered, but the content of each line must not be changed.

Copy-Pasting Credentials

Copy the credentials from IBM Cloud and store them within your project. Then pass those values to the service initializer that accepts the type of credentials you have.

IAM

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, override your stored IAM credentials with an IAM API key.
Supplying the IAM API key
let discovery = Discovery(version: "your-version", apiKey: "your-apikey")

If you are supplying an API key for IBM Cloud Private (ICP), use basic authentication instead, with "apikey" for the username and the api key (prefixed with icp-) for the password. See the Username and Password section.

Supplying the accessToken
let discovery = Discovery(version: "your-version", accessToken: "your-accessToken")
Updating the accessToken
discovery.accessToken("new-accessToken")
Username and Password
let discovery = Discovery(version: "your-version", username: "your-username", password: "your-password")

Custom Service URLs

You can set a custom service URL by modifying the serviceURL property. A custom service URL may be required when running an instance in a particular region or connecting through a proxy.

For example, here is how to connect to a Tone Analyzer instance that is hosted in Germany:

let toneAnalyzer = ToneAnalyzer(
    version: "yyyy-mm-dd",
    username: "your-username",
    password: "your-password"
)
toneAnalyzer.serviceURL = "https://gateway-fra.watsonplatform.net/tone-analyzer/api"

Disable SSL certificate verification

For ICP(IBM Cloud Private), you can disable the SSL certificate verification by:

service.disableSSLVerification()

Note: disableSSLVerification() is currently not supported on Linux.

Custom Headers

There are different headers that can be sent to the Watson services. For example, Watson services log requests and their results for the purpose of improving the services, but you can include the X-Watson-Learning-Opt-Out header to opt out of this.

We have exposed a defaultHeaders public property in each class to allow users to easily customize their headers:

let naturalLanguageClassifier = NaturalLanguageClassifier(username: username, password: password)
naturalLanguageClassifier.defaultHeaders = ["X-Watson-Learning-Opt-Out": "true"]

Each service method also accepts an optional headers parameter which is a dictionary of request headers to be sent with the request.

Featured Projects

We love to highlight cool open-source projects that use this SDK! If you'd like to get your project added to the list, feel free to make an issue linking us to it.

Synchronous Execution

By default, the SDK executes all networking operations asynchronously. If your application requires synchronous execution, you can use a DispatchGroup. For example:

let dispatchGroup = DispatchGroup()
dispatchGroup.enter()
assistant.message(workspaceID: workspaceID) { response, error in
	if let error = error {
        print(error)
    }
    if let message = response?.result else {
        print(message.output.text)
    }
    dispatchGroup.leave()
}
dispatchGroup.wait(timeout: .distantFuture)

Handling PNG and CgBI Files in XCode

When working with iOS projects, you may need to add PNG images to your XCode resource bundle. By default, XCode converts PNG files to Apple's CgBI file format as an optimization step.

Watson services that accept PNG images as input files (Visual Recognition, Compare and Comply) are not able to process CgBI files. In some cases passing PNGs that have been encoded as CgBI will result in HTTP errors, and in other cases (Visual Recognition) will result in a 200 Success with no results.

How to bypass CgBI Encoding for Resource Files

In order to bypass CgBI encoding and keep the PNG files in a format that will operate well with Watson services, select the PNG file in XCode, and modify the Type attribute to Data in the File Inspector.

Ex:
File inspector example

Future plans for handling CgBI

In the future, we will explore our options to handle conversion between CgBI and PNG within the Swift SDK, but this is currently not available.

Objective-C Compatibility

Please see this tutorial for more information about consuming the Watson Developer Cloud Swift SDK in an Objective-C application.

Linux Compatibility

To use the Watson SDK in your Linux project, please follow the Swift Package Manager instructions.. Note that Speech to Text and Text to Speech are not supported because they rely on frameworks that are unavailable on Linux.

Contributing

We would love any and all help! If you would like to contribute, please read our CONTRIBUTING documentation with information on getting started.

License

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

This SDK is intended for use with an Apple iOS product and intended to be used in conjunction with officially licensed Apple development tools.

Github

link
Stars: 869
Help us keep the lights on

Dependencies

Releases

3.1.0 - Nov 27, 2019

3.0.0 - Oct 4, 2019

3.0.0 (2019-10-04)

Bug Fixes

  • hand edit: parse "collectionIDs" and "features" into csv data (7054591)
  • hand edit: vR V4 model hand edits (27d17b2)
  • linux tests: fix syntax errors in linux tests (bfb2b62)

Build System

  • core: update dependencies to use new core (dbfdb19)

Code Refactoring

  • remove utility methods: remove authentication type methods (81ab28e)

Features

  • environment auth: make environment authenticator a throwable (8689481)
  • environment auth: make environment authenticator a throwable (e9df576)
  • generated code: add generated code based on updated api definitions (e9a8eeb)
  • generated code: update based on api reference changes (de24497)
  • generated code: update generated code based on api definitions (e090f9d)
  • hand edit: make VR V4 environment init throwable (52788bc)
  • vis rec v4: add Visual Recognition V4 (96e6dab)
  • websockets: accept authenticator in websocket client init (db90f26)

BREAKING CHANGES

  • core: uses new core framework
  • generated code: new authentication scheme
  • environment auth: Previously, this was an init? but now it will be an init -> throws
  • websocketURL is now a String?

refactor(core import): use IBMSwiftSDKCore instead of RestKit

feat(vis rec ui): remove faces method

  • faces method is no longer available

build(xcode): update dependency settings

test(vr): update test values

fix(hand edit): convert classifierIDs and owners to csv data

  • environment auth: Previously, this was an init? but now it will be an init -> throws
  • hand edit: turns the init? into an init -> throws
  • faces method is no longer available

build(xcode): update dependency settings

  • generated code: removed models and breaking api changes
  • websockets: new init parameters and removal of convience inits
  • remove utility methods: public methods removed
  • websocketURL is now a String?

refactor(core import): use IBMSwiftSDKCore instead of RestKit

feat(vis rec ui): remove faces method

2.3.0 - Aug 27, 2019

2.3.0 (2019-08-27)

Features

  • comparecomply: update based on latest api definition (a8be492)

2.2.0 - Jul 31, 2019

2.2.0 (2019-07-31)

Features

  • AssistantV2 add support for Assistant Search Skill (ca7e3b0)

Bug fixes

  • Integration Tests various bug fixes

2.1.1 - Jun 28, 2019

2.1.1 (2019-06-28)

Bug Fixes

  • SpeechToTextV1: Add configureSession parameter to RecognizeMicrophone. (87f5aed)