📱 The Watson Swift SDK enables developers to quickly add Watson Cognitive Computing services to their Swift applications.
Clone or download
AnthonyOliveri ci(Travis): Fix git commands in the doc publishing script
Make sure to pull the latest commits and tags, and don't do a `git clean` because it would remove docs for newly added services
Latest commit 2a3e741 Jan 11, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update issue template Dec 5, 2018
Scripts ci(Travis): Fix git commands in the doc publishing script Jan 11, 2019
Source Release version 1.2.0 [skip ci] Jan 11, 2019
Tests Merge branch 'develop' into compare-comply Jan 10, 2019
WatsonDeveloperCloud.xcodeproj chore(CompareComplyV1): Change iOS deployment target to 10.0 Jan 11, 2019
docs Dirty merge of branch develop into v1.0 Sep 5, 2018
.bumpversion.cfg ci(CompareComplyV1): Add CompareComplyV1 to automation scripts Jan 11, 2019
.gitignore Gitignore cloud-object-storage credentials Nov 28, 2018
.releaserc ci(Deploy): Fix uploading of prebuilt frameworks to Github release Oct 19, 2018
.swift-version add a .swift-version file Oct 19, 2017
.swiftlint.yml Dirty merge of branch develop into v1.0 Sep 5, 2018
.travis.yml ci(Travis): Fix Travis build timeouts Jan 9, 2019
CHANGELOG.md chore(release): 1.2.0 [skip ci] Jan 11, 2019
Cartfile Update RestKit dependency to 2.0.0 Dec 5, 2018
Cartfile.resolved Update RestKit dependency to 2.0.0 Dec 5, 2018
Dockerfile Update dockerfile to Swift 4.1 May 18, 2018
IBMWatsonAssistantV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonAssistantV2.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonCompareComplyV1.podspec chore(CompareComplyV1): Update CompareComplyV1 podspec to the most re… Jan 11, 2019
IBMWatsonDiscoveryV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonLanguageTranslatorV3.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonNaturalLanguageClassifierV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonNaturalLanguageUnderstandingV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonPersonalityInsightsV3.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonSpeechToTextV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonTextToSpeechV1.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonToneAnalyzerV3.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
IBMWatsonVisualRecognitionV3.podspec Release version 1.2.0 [skip ci] Jan 11, 2019
LICENSE Updated with Apache 2.0 license Nov 20, 2015
Package.resolved Update RestKit dependency to 2.0.0 Dec 5, 2018
Package.swift chore(CompareComplyV1): Add Linux support Jan 10, 2019
README.md docs(README): Add CompareComplyV1 Jan 11, 2019

README.md

Watson Developer Cloud Swift SDK

Build Status Carthage Compatible Documentation CLA assistant

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.1+
  • iOS 10.0+

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', '~> 1.2.0'
    pod 'IBMWatsonAssistantV2', '~> 1.2.0'
    pod 'IBMWatsonCompareComplyV1', '~> 1.2.0'
    pod 'IBMWatsonDiscoveryV1', '~> 1.2.0'
    pod 'IBMWatsonLanguageTranslatorV3', '~> 1.2.0'
    pod 'IBMWatsonNaturalLanguageClassifierV1', '~> 1.2.0'
    pod 'IBMWatsonNaturalLanguageUnderstandingV1', '~> 1.2.0'
    pod 'IBMWatsonPersonalityInsightsV3', '~> 1.2.0'
    pod 'IBMWatsonSpeechToTextV1', '~> 1.2.0'
    pod 'IBMWatsonTextToSpeechV1', '~> 1.2.0'
    pod 'IBMWatsonToneAnalyzerV3', '~> 1.2.0'
    pod 'IBMWatsonVisualRecognitionV3', '~> 1.2.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" ~> 1.2.0

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

$ carthage update --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

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: "1.2.0")
]

Authentication

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.
  • Visual Recognition uses a form of API key only with instances created before May 23, 2018. Newer instances of Visual Recognition use IAM.

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 or click Create resource > AI and create a service instance.
  3. Click Show to view your service credentials.
  4. Copy the url and either apikey or username and password.

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(username: "your-username", password: "your-password", version: "your-version")

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(
    username: "your-username",
    password: "your-password",
    version: "yyyy-mm-dd"
)
toneAnalyzer.serviceURL = "https://gateway-fra.watsonplatform.net/tone-analyzer/api"

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.

Sample Applications

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)

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.