Oracle Cloud Infrastructure Documentation

Oracle iOS

Using the Oracle iOS SDK for Oracle Digital Assistant, you can integrate your digital assistant with iOS apps. The SDK connects to the Oracle Chat Server, the intermediary between the Oracle iOS channel configured in Oracle Digital Assistant and the client. The chat server then passes messages to the skill for processing and delivers the skill's response to the client.

This SDK works with instances of Oracle Digital Assistant that were provisioned on Oracle Cloud Infrastructure (sometimes referred to as the Generation 2 cloud infrastructure). If your instance is provisioned on the Oracle Cloud Platform (as all version 19.4.1 instances are), you can use the legacy iOS SDK.

What Do You Need?

  • An Oracle iOS Channel. Creating the channel generates the Channel ID and the Secret Key that you need to initialize the chat app.
  • The URL of the Oracle Chat Server.
  • The Oracle iOS SDK (located under Oracle Native Client SDKs for OCI Native Environments) from Oracle Technology Network’s ODA and OMC download page. Download this ZIP and extract it to your local system. This ZIP includes a user guide that describes the SDK's functions.
  • Swift 4.2 as the Swift Language Version. Xcode 11 or higher. If you want your app to work on earlier versions, keep in mind that we haven't tested these and therefore can't guarantee their compatibility.

Create the Oracle iOS Channel

You can configure the channel to connect to the Oracle Chat Server in two modes: unauthenticated mode and authenticated mode (to protect access to the channel).
  • Unauthenticated mode – Use the unauthenticated mode when the client can't generate signed JWT tokens, when no authentication mechanism is in place, or when the client widget is already secured and visible to authenticated users.
  • Authenticated mode – Authentication is enforced using JSON Web Tokens (JWT). The backend server generates these tokens using the Secret Key generated from the Oracle iOS channel when a user authenticates with the iOS app. These tokens are then sent on every HTTP request, thus allowing the server to authenticate the user. The information contained within the token is signed by a private key which is owned by the server. When the server gets the token back from the client, it compares the signature sent by the client with the one that it will generate with its private key. The token is valid when the two signatures are identical. When the client needs to establish a web socket connection with the chat server, it first requests a JWT token from the backend server and then adds the token to the Authorization header in its call to the chat server.
    The JWT Token has the following claims: channelId, userId, and the claim names iat (issued at time), and exp (expiration time). iat signifies the time at which the token was issued. This must a number that represents the seconds that have elapsed since the UNIX epoch. exp must be a number representing the seconds that have elapsed since the UNIX epoch. We recommend setting the expiration time to at least 30 minutes after the issued at time (iat). The decoded header looks something like this:
    {
    
     "alg": "HS256",
    
     "typ": "JWT"
    
    }
    An example of the decoded body looks something like this:
    {
    
      "iat": 1569828182,
    
      "exp": 1569831782,
    
      "channelId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    
      "userId": "John"
    
    }
    Note

    The token illustrated by this example is not signed. The actual tokens are signed by channel's Secret Key.

Configure the Oracle iOS Channel

To configure the Oracle iOS channel:
  1. Choose Development, then Channels from the menu.
  2. Choose Users.
  3. Click Add Channel and then Oracle iOS as the channel type.
  4. Complete the dialog:
    • Enter the channel name.
    • For authenticated connections:
      • Switch on the Client Authentication Enabled toggle to determine whether the SDK is connecting to client authentication-enabled channel.
      • In the Max. Token Expiration (Minutes) field, set the maximum amount of time for the JWT token.
      • Set the Session expiration time.
    • For unauthenticated connections:
      • Switch off Client Authentication Enable toggle.
      • Set the Session expiration time.
    • Click Create. Oracle Digital Assistant will generate the Channel ID and the Secret Key that you need to initialize the SDK. Keep it close at hand because you'll need when configuring the HTML page to host the chat widget.
  5. Route the channel to your skill or digital assistant.
  6. Switch Channel Enabled to On.

Add the SDK to the Project

  1. Download the ODA Client SDK for iOS and extract it to your local system.
  2. Add the files to your Xcode project:
    1. Click File > Add Files to "<project name>".
    2. Choose the .framework files that you want to add depending on where you want to run the app (simulator or actual device).
    3. Make sure to that Copy items if needed (located under Destinations) is selected.
    4. Alternatively, you can drag and drop the .framework files into the project file in Xcode.
  3. Embed and sign the frameworks in the Frameworks, Libraries, and Embedded Content category in the General tab. (This may vary according to the version of Xcode that you're using.) Make sure the Targets option is selected.
  4. Add the following keys in the project's .plist file:
    • Privacy - Location Always and When In Use Usage Description or <key>NSLocationAlwaysUsageDescription</key> and the corresponding <string></string> in the source code.
    • Privacy - Location When In Use Usage Description or <key>NSLocationWhenInUseUsageDescription</key> and the corresponding <string></string> in the source code.
    • Privacy - Microphone Usage Description or <key>NSMicrophoneUsageDescription</key> and the corresponding <string></string> in the source code.
    • Privacy - Camera Usage Description or <key>NSCameraUsageDescription</key> and the corresponding <string></string> in the source code.

Initialize the SDK in Your App

You can use the following code to initialize the chat view.
// Import the SDK
import BotClientUISDK
 
// Declare a global BotsViewController variable in your app view controller class
public var chatViewController: BotsViewController?
 
// Obtain a shared instance of BotsViewController from BotsUIManager
chatViewController = BotsUIManager.shared().viewControllerInstance()
 
// Specify the color changes, if any, in a particular component. Make sure that you set all the required colors in BotsProperties before adding the chat view to the view controller.
  
// Add the chat view to your view controller
self.view.addSubview((chatViewController?.view)!)
  
// Initialize a BotsConfiguration object and set feature flags, if required.
var botsConfiguration = BotsConfiguration(url: baseUrl, userId: botID!, channelId: channelID)
  
// Initialize the configuration in botsViewController. Make sure you set all the feature flag values before passing the botsConfiguration to initConfiguration.
chatViewController?.initConfiguration(botsConfiguration: botsConfiguration)
  
// Get a custom navigation bar view from botsViewController and add it to the navigation bar of your app.
let customView:UIView = (chatViewController?.addCustomViewToNavBar())!
self.navigationController?.navigationBar.addSubview(customView)
 
// Obtain a shared instance of BotsManager
let botsManager = BotsManager.shared()
 
// If you require access to callback methods provided in BotsMessageServiceDelegate. Make sure your class conforms to BotsMessageServiceDelegate
botsManager.delegate = self
 
// If you require access to callback methods provided in BotsEventListener. Make sure your class conforms to BotsEventListener
botsManager.botsEventListener = self
 
// Initialize and establish connection to the chat server
botsManager.initialize(botsConfiguration: botsConfiguration, completionHandler: { (connectionStatus, error) in
 
})
Note

The SDK currently provides UI for portrait orientation only.

App Development

Initialize the Feature Flag Settings

Initialize BotsConfiguration object using one of its constructors.
  • clientAuthDisabled
    • BotsConfiguration(url: String, userId: String, channelId: String)
      • Parameters:
        • url - The Oracle Chat Server URL. This cannot be null.
        • userId - The unique identifier for the user. This cannot be null.
        • channelId - The Oracle iOS Channel ID. This cannot be null.
      • When the userId not provided (a randomly generated value is instead)
        • url - The Oracle Chat Server URL. This cannot be null.
        • channelId - The Oracle iOS Channel ID. This cannot be null.
  • clientAuthEnabled
    • BotsConfiguration(url: String, authToken: String)
      • Parameters:
        • url - The Oracle Chat Server URL. This cannot be null.
        • authToken - The authentication token for establishing a connection with an authentication-enabled channel. This cannot be null.
For example:
// Initialize a BotsConfiguration object
var botsConfiguration = BotsConfiguration(url: chatServerUrl, authToken: token)
 
// Set the feature flag values if the desired values are different from the default values
botsConfiguration.showConnectionStatus = true
botsConfiguration.enableBotAudioResponse = true
botsConfiguration.disablePastActions = "none"

Network Configuration

Property Name Description Required? Default Value
url The URL of the Oracle Chat Server Yes N/A
channelId The ID of the Oracle iOS channel. Yes N/A
userId The unique identifier for user. This value gets initialized by the SDK if not provided. No A randomly generated value
authToken The authentication token for establishing a connection with an authentication-enabled channel. Yes N/A

Feature Flags

Property Description Required? Default Value
botAvatar Passes the asset name of the skill avatar image. No N/A
disablePastActions A field for disabling the button clicks on the messages that a user has already interacted with. The allowed values are all, none, and postback. The behavior enabled by this property is independent of the digital assistant-level configuration for disabling the selection of past actions. You need to set the two separately. No all
enableAttachment Configures attachment sharing in the chat app. No true
enableAutoSendSpeechResponse When set to true (the default), the user's speech response is automatically sent to the chat server (and rendered as a sent message in the chat window). When set to false, the user's speech response is rendered in the message text field before it's sent to the chat server, allowing the user to modify it before sending it manually, or delete the message. No true
enableClearMessage Enables the clear message button in the chat widget header. No false
enableSpeechRecognition Enables the microphone button. No false
enableSpeechSynthesis Enables the skill responses to be read aloud. By setting this flag to true, you enable the skill's responses to be read aloud using Swift API. No false
enableTimestamp Enables the timestamp for messages. No true
initSpeechSynthesisMuted Sets the default state of BotAudioResponse as muted. No true
initUserHiddenMessage A user text message that's used to initiate a conversation. This message, which is sent when chat widget is ready, does not actually display in chat. No N/A
initUserProfile Updates the user profile before the start of a conversation. The format of the profile payload must be ["profile": […] ]. For example:
initUserProfile = ["profile": ["givenName": "First", "surname": "Last", "email": "first.last@example.com", "properties": ["lastOrderedItems": "1 medium pepperoni"]]]
This function updates the user context before the initial "hidden" message is sent by initUserHiddenMessage to start the conversation. As a result, the user profile can be reflected in the first response message to the user. For example, the skill can greet the user with a message like "Welcome back, John Smith! Your last order was a medium pepperoni pizza."
No N/A
personAvatar Passes the asset name of the person avatar image. No N/A
showConnectionStatus Enables the connection status to display in the chat widget header. No false
showTypingStatus Enables the display of the Responding… text indicator when waiting for a response from the skill. No true
speechSynthesisVoicePreferences Matches the provided preferences based on both the language-locale and voice name. If no match is found, then the default voice for the given language-locale is used. In the latter case, the Apple API finds best match with the given language-locale. No N/A
title Sets the title of the app, which is displayed in the app bar. No N/A
typingStatusTimeout Sets the timeout, in seconds, to hide the typing status indicator when no response has been received from the chat server. No 20 seconds

Strings

Configure strings by adding the following key = value pairs in the app's <language-code>.iproj/Localizable.strings file.
Key Description Default Value
odais_title The title of the app that's displayed on the app bar. Ask
odais_connected The status text that displays when the connection between chat widget and the Oracle chat server has been established. Connected
odais_connecting The status text that displays while the chat widget connects to the Oracle chat server. Connecting
odais_disconnected The status text that displays when the connection between the chat view and the Oracle chat server has closed. Disconnected
odais_typing_status The status text that displays while the user waits for the skill's response. Responding...
odais_speech_error The alert message that's displayed when the audio cannot be recorded. Error in voice recognition. Please try again later.
odais_speechrecognition_error The alert message that's displayed when there is a speech recognition error from the speech server. Speech Recognition Error
odais_speech_send The button label text on the speech popup for sending the recorded audio to the speech server. SEND
odais_speech_cancel The button label text on the speech popup for cancelling the sending of recorded audio to the speech server. CANCEL
odais_speech_start The text displayed on the speech popup indicating that the user can now start speaking. Listening...
odais_speech_permission_denied The error message displayed when microphone usage is not allowed. Permission_Denied
odais_file_not_supported The alert message displayed when the user selects file type that's not supported for attachments. File type not supported
odais_file_size_warning The alert message displayed when the file chosen for attachment exceeds 25MB. You can only attach files of size upto 25MB
odais_gallery_permission_denied The alert message displayed when permission to the gallery has not been granted. You don't have permission to access gallery.
odais_photo The action text that appears on the attachment popup for choosing a file from phone's gallery. Photo & Video Library
odais_files The action text that appears on the attachment popup for choosing a file from storage. Files
odais_cancel The action text that for closing the attachment popup. Cancel
odais_notification_title The title displayed on the notifications bar. OracleChatBot
odais_warning The title of the alert message that displays when permission to access the gallery has not been granted. Warning
odais_alert The title of the alert message displayed for speech and file-related errors. Alert
odais_check_url The error message displayed for a broken link. Please check the url!
odais_fail_to_load The error message displayed when page is not able to load in the chat view. Failed to load the page
odais_error Title of the error and alert messages in the chat view. Error
odais_ok The label text for the button that closes alert and error messages. Ok
odais_done The label text for the button that closes the chat view. Done
odais_write_a_message The placeholder text in the user message input field. Write a message
odais_camera The action text that appears on the attachment popup for using the device's camera. Camera

Colors

You can modify the colors for the following components by using BotsProperties.<component name> = <UIColor type>. As described in Initialize the SDK in Your App, you must set all of the colors in BotsProperties before adding the chat view to the view controller.

Component Description Default Color
ActionButtonColor The color for an action button #0077C2
ActionLabelTextColor The text color for an action label UIColor.white
BotMessageColor The background color for text, attachment, and location messages sent by the skill #BBDEFB
BotTextColor The color for the text in a text message sent by the skill UIColor.black
CardBackgroundColor The background color for a card #BBDEFB
CardDescriptionTextColor The text color for a card description UIColor.black
CardTitleTextColor The text color for a card title UIColor.black
ChatBackgroundColor The color for the chat view background #FAFAFA
FooterIconsColor The color of the attachment, send, and mic icons located in the footer. #004C8C
HeaderIconsColor The color for the clear message, volume, and mute header icons. UIColor.white
HeaderTextColor The text color for the connection status, typing status, and chat title header items UIColor.white
TimestampColor The color for the message timestamp UIColor.lightGray
UserMessageColor The background color for a user message #E0E0E0
UserTextColor The color for the text in a text user sent by the user UIColor.black

Oracle iOS Channel Extensions

For Oracle iOS channels, you can extend the functionality of System.CommonResponse components with capabilities that are specific to the Oracle iOS SDK.

You access the extensions by using the channelCustomProperties element in the System.CommonResponse component and setting the appropriate properties. The code has the following format:

...
            channelCustomProperties:
            - channel: "ios"
              properties:
                PROPERTY_NAME: "PROPERTY_VALUE"
...

Here are the available custom properties for Oracle iOS channels:

Name Allowed Values Applies To... Description
mediaType
  • A valid media type
  • Response items with the following attributes:
    • type: "attachment"
    • attachmentType: "file"or attachmentType: "image"
  • Cards with imageUrl specified
The media type of the attachment. For example, image/jpeg. If not specified, the media type will be resolved from the attachment URL.

For more general information on channelCustomProperties, see Channel-Specific Extensions.