iOS

Documents the Touchpoint iOS package, serving as the guide for the Touchpoint SDK for iOS applications.

This is an enterprise only package available under NDA.

A native iOS SDK that provides a customizable conversational interface that you can embed in your iOS applications. Touchpoint allows users to interact with your NLX applications through natural language and provides a seamless conversational experience.

Overview

The SDK provides:

• Voice conversations: Real-time voice interactions

• Floating widget: A draggable floating interface for easy access

• Bidirectional form interaction: Voice commands can fill out and interact with your app's forms

• Native iOS integration: Built with SwiftUI and UIKit

Requirements

• iOS 15.0+

• Xcode 15.0+

• Swift 5.7+

Installation

Add the SDK to your Xcode project

There are two ways to add the NLX Touchpoint SDK to your project:

Option A: Swift package manager (recommended)

1. Open your Xcode project

2. Go to File > Add Package Dependencies...

3. Enter the local path: ../../ (or the full path to the SDK root)

4. Click Add Package

5. Select NLXTouchpointSDK and click Add Package

Option B: Local package reference

1. In Xcode, right-click on your project in the navigator

2. Select Add Files to [YourProject]

3. Navigate to the SDK root directory and select Package.swift

4. Choose "Create folder references" and click Add

Authentication

NLX uses API Keys to authenticate requests. Touchpoint requires an Application URL and an API Key to be included in the config object.

// Configure the SDK
let config = NLXConfiguration(
    config: CoreConfig(
        applicationUrl: "https://your-nlx-app.com", // Your NLX application URL
        headers: [
            "nlx-api-key": "your-api-key-here" // Required: Your NLX API key
        ]...

The Application URL and API Key are located in the API Delivery Channel setup.

Click Setup instructions to view Application URL and API Key.

Quick Start

1

Configure the SDK

In your AppDelegate or SceneDelegate:

import NLXTouchpointSDK

// Generate user/conversation IDs
let userId = UserDefaults.standard.string(forKey: "nlxUserId") ?? UUID().uuidString
let conversationId = UUID().uuidString
UserDefaults.standard.set(userId, forKey: "nlxUserId")

// Configure the SDK
let config = NLXConfiguration(
    config: CoreConfig(
        applicationUrl: "https://your-nlx-app.com", // Your NLX application URL
        headers: [
            "nlx-api-key": "your-api-key-here" // Required: Your NLX API key
        ],
        conversationId: conversationId,
        userId: userId,
        languageCode: "en-US", // Required
        bidirectional: true // Enable bidirectional communication
    ),
    input: .voiceMini, // Enable voice input with compact UI
    bidirectional: .automatic(AutomaticBidirectionalConfig(
        navigation: handleNavigation,
        input: handleFormInput,
        custom: handleCustomCommand
    ))
)

NLXTouchpointSDK.configure(with: config)

2

Add the floating widget

// Create and add the floating widget to your window
let widget = NLXTouchpointSDK.createWidget()
window?.addSubview(widget)

// Set up constraints for full-screen overlay
widget.translatesAutoresizingMaskIntoConstraints = false
NSLayoutConstraint.activate([
    widget.topAnchor.constraint(equalTo: window!.safeAreaLayoutGuide.topAnchor),
    widget.leadingAnchor.constraint(equalTo: window!.leadingAnchor),
    widget.trailingAnchor.constraint(equalTo: window!.trailingAnchor),
    widget.bottomAnchor.constraint(equalTo: window!.bottomAnchor)
])

3

Handle bidirectional interactions

// Navigation handler
private func handleNavigation(action: NavigationAction, destination: String?, destinations: [String: String]) {
    switch action {
    case .pageNext:
        // Handle forward navigation
        break
    case .pagePrevious:
        // Handle back navigation
        break
    case .pageCustom:
        if let destination = destination, let url = destinations[destination] {
            // Navigate to specific page
        }
        break
    case .pageUnknown:
        // Handle unknown navigation
        break
    }
}

// Form input handler
private func handleFormInput(fields: [FormInput], pageFields: [String: UIView]) {
    for field in fields {
        if let uiElement = pageFields[field.id] {
            if let textField = uiElement as? UITextField {
                textField.text = field.value
                textField.sendActions(for: .editingChanged)
            }
        }
    }
}

// Custom command handler
private func handleCustomCommand(action: String, payload: Any) {
    print("Custom command: \\(action) with payload: \\(payload)")
}

4

Configure permissions

Add the following to your Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone for voice conversations with the NLX assistant.</string>

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Architecture

The SDK is built with three main modules:

• NLXCore: Core conversation handling and networking (ported from @nlxai/core)

• NLXVoice: Voice capabilities with NLX integration

• NLXTouchpointSDK: Main SDK interface and floating widget UI

Features

Voice conversation

• Real-time voice interaction using NLX

• Automatic microphone permission handling

• Audio controls (mic, speaker, close)

• Visual feedback for speaking states

Floating widget

• Draggable interface that snaps to screen edges

• Multiple states: idle, connecting, active, error

• Customizable positioning and appearance

• Native iOS accessibility support

Bidirectional form interaction

• Automatic context analysis of current screen

• Voice commands can fill form fields

• Support for common UIKit controls (UITextField, UIButton, etc.)

• Custom form handling callbacks

Example project

See the Examples/NLXExample directory for a complete implementation example showing:

• SDK configuration

• Floating widget integration

• Form interaction with voice commands

• Permission handling

API reference

NLXTouchpointSDK

The main SDK class providing static methods for configuration and widget creation.

Methods

• configure(with:) - Configure the SDK with your API credentials

• createWidget() - Create a floating widget for your app

• setVisibility(for:visible:) - Control widget visibility on specific screens

Configuration types

NLXConfiguration

Main configuration object containing:

• config: CoreConfig - Core API configuration

• input: InputType - Input method (.voiceMini recommended)

• bidirectional: BidirectionalConfig - Bidirectional interaction settings

• theme: NLXTheme? - Optional theme customization

CoreConfig

Core API configuration:

• applicationUrl: String - Your NLX application URL

• headers: [String: String] - Must include "nlx-api-key"

• languageCode: String - Language code (required)

• bidirectional: Bool? - Enable bidirectional features

Migration from Web SDK

This iOS SDK maintains API compatibility with the JavaScript @nlxai/touchpoint-ui SDK:

JavaScript	iOS Swift
TouchpointConfiguration	NLXConfiguration
Config	CoreConfig
createConversation()	createConversation()
ConversationHandler	ConversationHandler