Forethought - Solve iOS SDK

This repository contains the framework and instructions for the Forethought iOS SDK.

A valid API key is needed in order to use the Forethought Solve SDK. In additon to the documentation below, sample apps have been written in Objective-C & Swift, as well as a SwiftUI implementation

Installation

Swift Package Manager

1. In Xcode, File > Add Packages.

2. Enter the Forethought iOS GitHub repo URL (https://github.com/Forethought-Technologies/solve-ios)

3. Tap Add Package. Follow the remaining prompts and Xcode will automatically download the framework

Cocoapods

1. Forethought is also available through CocoaPods.

2. In the Podfile, add the following line:

   pod 'Forethought'

3. Run the following command:

   $ pod install
   

4. Make sure to use the .xcworkspace file and NOT the .xcodeproj from now on.

Basic Usage

1. In AppDelegate.swift file, replace __YOUR_KEY_HERE__ with a valid Forethought API key:

   ForethoughtSDK.start(apiKey: "__YOUR_KEY_HERE__")

2. Open the Forethought widget:

   import 'Forethought'
   
   ForethoughtSDK.show()

Other ways to open widget

SwiftUI View

Returns a SwiftUI view

ForethoughtSDK.forethoughtView

Use of a Navigation Controller Directly

Attach the Forethought SDK directly onto a navigation stack:

@IBAction func contactSupportTapped() {
    ForethoughtSDK.show(fromNavigationController: self.navigationController)
}

Optional Additions

Workflow Context Variables

Pass in Workflow Context Variables that have been defined via the Forethought Dashboard. (Note: you do not need to prefix with data-ft)

ForethoughtSDK.dataParameters = ["language": "EN", "user-email": "[email protected]", "workflow-context-variable": "value"]

Widget Configuration Parameters

Current configuration parameters are all the config-ft prefixed parameters under Additional Attributes. (Note: you do not need to prefix with config-ft)

ForethoughtSDK.configParameters = ["theme-color": "#7b33fb"]

Additional Parameters

Pass in non data-ft / config-ft using ForethoughtSDK.additionalParameters. A comprehensive list of parameters can be found here.

ForethoughtSDK.additionalParameters = ["initial-intent-id": "79fc012c-cce3-4574-9b75-7b272310d854"]

Other customizations

ForethoughtSDK.modalPresentationStyle

Default style is UIModalPresentationStyle.popover (Note this does not apply when using fromNavigationController).

ForethoughtSDK.modalPresentationStyle = UIModalPresentationStyle.fullScreen

Forethought Delegate

Forethought delegate is used to respond to events during the widget conversation that may need additional implementation. All methods in the ForethoughtDelegate are optional as well.

@objc public protocol ForethoughtDelegate: AnyObject {
    // Customer requested a handoff. Implement your own handoff from Forethought to another SDK (e.g. Zendesk or Salesforce)
    @objc optional func startChatRequested(handoffData: ForethoughtHandoffData)
    // Customer clicked the close widget button. Make sure to call ForethoughtSDK.hide if you choose to implement this
    @objc optional func widgetClosed()
    // Widget experienced an error causing it not be able to render
    @objc optional func widgetError(errorData: ForethoughtErrorData)
}

To setup the delegate

1. Set a delegate to the Forethought SDK. Do this before presenting the screen:

   ForethoughtSDK.delegate = self

2. Make sure the object conforms to the ForethoughtDelegate protocol

   class ViewController: UIViewController, ForethoughtDelegate {

3. Add any of the optional delegate methods you want to handle

startChatRequested Example

func startChatRequested(handoffData: ForethoughtHandoffData) {
    print("Chat Requested: \(handoffData)")

    // close forethought widget
    ForethoughtSDK.hide(animated: false) {
        // start a Kustomer chat
        Kustomer.startNewConversation(initialMessage: KUSInitialMessage(body: handoffData.question, direction: .user))
        ForethoughtSDK.sendHandoffResponse(success: true)
    }

    // if handoff was unsuccessful
    ForethoughtSDK.show()
    ForethoughtSDK.sendHandoffResponse(success: false)
}

widgetClosed Example

func widgetClosed() {
    // add any additional logic here

    ForethoughtSDK.hide(animated: true) {
        print("forethought - widgetClosed")
    }
}

widgetError Example

func widgetError(errorData: ForethoughtErrorData) {
    // add any additional logic here

    ForethoughtSDK.hide(animated: true) {
        print("forethought - \(errorData.error)")
    }
}

Plugins

⛔️ Plugins are deprecated in starting in version 2.0.0 ⛔️

Documentation

Documentation has been provided as a .doccarchive to enable full documentation directly inside Xcode. To use, simply double-click on Forethought.doccarchive, and Xcode will handle the rest.