iOS

This page 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

This 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)

Open your Xcode project
Go to File > Add Package Dependencies...
Enter the local path: ../../ (or the full path to the SDK root)
Click Add Package
Select NLXTouchpointSDK and click Add Package

Option B: Local Package Reference

In Xcode, right-click on your project in the navigator
Select Add Files to [YourProject]
Navigate to the SDK root directory and select Package.swift
Choose "Create folder references" and click Add

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)

// 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

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()

ConversationHandler

Last updated 5 days ago