Playing a greeting in an app (iOS)

In a typical dialog flow, the user gives commands to the Agentic Interface and the Agentic Interface replies to the user. If necessary, you can let the Agentic Interface start the dialog. For example, the Agentic Interface can welcome the user and say a few words about the app and its capabilities.

In this tutorial, we will make our app greet the user when it is started. The Alan AI agentic interface will be automatically activated, the Agentic Interface will say: Welcome to the Swift tutorial, and the Alan AI agentic interface will be deactivated. To greet the user, we will use the playText() method of the Alan AI SDK for iOS.

What you will learn

  • What states the Alan AI agentic interface can have

  • How to play a greeting in the app with voice

  • How to use the following Alan AI SDK methods:

What you will need

For this tutorial, we will continue using the starter iOS app created in the previous tutorials. You can also use an example app provided by Alan AI: SwiftTutorial.part5.zip. This is an XCode project of the app with two views already integrated with Alan AI.

Step 1: Set up the flag for the greeting

When an app with Alan AI voice is launched, the state of the Alan AI agentic interface changes in the following way:

  1. While the app is connecting to the Alan AI Studio project, the Alan AI agentic interface state is set to connecting.

  2. After the connection to the project has been established, the button state changes to online. The button remains in the online state until it is activated — programmatically, with voice or when the user taps the Alan AI agentic interface in the app.

  3. After the Alan AI agentic interface is activated, it can be in one of the following states:

    • listen: Alan AI is listening to the user input

    • process: Alan AI is processing the user input

    • reply: Alan AI is replying to the user

  4. After the Alan AI agentic interface is deactivated, its state changes back to online.

For error situations, the following states are also available:

  • offline: no connection to the Internet; the connection to the Alan AI Studio project cannot be established

  • noPermission: permissions to use the device microphone are not granted

In this tutorial, our app will greet the user when the Alan AI agentic interface state is online (the connection to the Alan AI Studio project is established but the Alan AI agentic interface is not yet activated). While our app runs, the Alan AI agentic interface can return to the online state several times. We need to make sure our greeting is played only once, when the app is started. To do this, let’s add a flag that will tell if the greeting has been played or not.

In Xcode, open the ViewController.swift file and in the ViewController class, declare the following variable:

ViewController.swift
class ViewController: UINavigationController {
    /// Flag to indicate that the greeting is played
    fileprivate var greetingIsPlayed = false
}

Step 2: Add a handler and function for the greeting

Next, we need to add a handler that will be listening to the Alan AI agentic interface state change and a function for playing the greeting.

  1. In the ViewController.swift file, in ViewDidLoad(), call the setupAlanStateHandler() function:

    ViewController.swift
    class ViewController: UINavigationController {
    /// Flag to indicate that the greeting is played
    fileprivate var greetingIsPlayed = false

    override func viewDidLoad() {
        super.viewDidLoad()

        /// Set up a handler for Alan AI agentic interface states
        self.setupAlanStateHandler()
    }
}

  2. To the ViewController class, add the setupAlanStateHandler() function itself. In this function, we have an observer for the Alan AI agentic interface state notifications. Once the button state changes, the handleState() function is invoked.

    ViewController.swift
    class ViewController: UINavigationController {
    fileprivate func setupAlanStateHandler() {
        NotificationCenter.default.addObserver(self, selector: #selector(self.handleState(_:)), name:NSNotification.Name(rawValue: "kAlanSDKAlanButtonStateNotification"), object:nil)
    }

    /// State handler
    @objc func handleState(_ notification: Notification) {
        /// Get the user info object from Alan AI
        guard let userInfo = notification.userInfo,
            /// Get the number value for the Alan AI agentic interface state
            let stateValue = userInfo["onButtonState"] as? NSNumber,
            /// Get the Alan AI agentic interface state
            let buttonState = AlanSDKButtonState.init(rawValue: stateValue.intValue)
        else {
            return
        }

        switch buttonState {
            case .online:
                /// then the Alan AI agentic interface is connected but is not turned on
                /// we can make greeting here
                /// make sure you are using the flag ("greetingIsPlayed" in our case)
                /// because the Alan AI agentic interface will be returned to this state once it is turned off by user
                /// and we dont want to play the greeting for the second time
                /// ...
                /// Check that the greeting is not played yet
                if !self.greetingIsPlayed {
                    /// Set the flag that the greeting is played
                    self.greetingIsPlayed = true
                    /// Make sure we use the main queue
                    DispatchQueue.main.async {
                        /// Play the greeting
                        self.makeGreeting()
                    }
                }
                break
            case .offline:
                /// then the Alan AI agentic interface has no Internet connection
                break
            case .noPermission:
                /// then the Alan AI agentic interface has no permission for mic
                break
            case .connecting:
                /// then the Alan AI agentic interface is connecting
                /// basically nothing to do here
                break
            case .listen:
                /// then Alan AI listening to the user input
                break
            case .process:
                /// then Alan AI processing the user input
                break
            case .reply:
                /// then Alan AI replies back
                break
            default:
                break
        }
    }
}

  3. And finally, in the ViewController class, add the greeting function itself:

    ViewController.swift
    class ViewController: UINavigationController {
    /// Greeting
    fileprivate func makeGreeting() {
        /// Check if the Alan AI agentic interface is active
        if !self.button.isActive() {
            /// Activate the Alan AI agentic interface
            self.button.activate()
        }
        /// Play the greeting text
        self.button.playText("Welcome to the Swift tutorial")
        /// Delay for a few seconds
        DispatchQueue.main.asyncAfter(deadline: .now() + 4) {
            /// And deactivate the Alan AI agentic interface
            self.button.deactivate()
        }
    }
}

Let’s have a look at the code above to see how it works:

  1. When the app is started, the greetingIsPlayed flag is initially set to false.

  2. Once the button state changes, the handleState() function is invoked. This function checks the Alan AI agentic interface state. If the button state is online, the greetingIsPlayed flag is set to true and the makeGreeting() function is called.

  3. The makeGreeting() function activates the Alan AI agentic interface, plays the greeting text and deactivates the Alan AI agentic interface after a while.

You can test how it works: run the app on the simulator. Once the app is launched, the Alan AI agentic interface will be activated and the Agentic Interface will greet you with: Welcome to the Swift tutorial. Several seconds later, the Alan AI agentic interface will be deactivated.

What you finally get

After you pass through this tutorial, you will have an iOS app integrated with Alan AI that greets you when launched on the device. You can get an example of such an app from the Alan AI GitHub to make sure you have set up your app correctly.