# iOS

{% hint style="info" %}
This is an enterprise only package available under NDA.
{% endhint %}

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.

<pre class="language-objc"><code class="lang-objc"><strong>// Configure the SDK
</strong>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
        ]...
</code></pre>

&#x20;The Application URL and API Key are located in the API Delivery Channel setup.

<figure><img src="https://3978076094-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2VnkvXtkrR2qhkVBmB1l%2Fuploads%2Fgl5zjWcycOSXc75z8lVa%2Fimage.png?alt=media&#x26;token=e58b07fd-ef5e-4a50-ae68-0f0b9e5cc78f" alt=""><figcaption></figcaption></figure>

Click *Setup instructions* to view Application URL and API Key.

<figure><img src="https://3978076094-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F2VnkvXtkrR2qhkVBmB1l%2Fuploads%2FKzZWOhRKmg4rUxn3NqtZ%2Fimage.png?alt=media&#x26;token=07f8f509-2b37-4e55-9b07-14e900b35484" alt=""><figcaption></figcaption></figure>

### Quick Start

{% stepper %}
{% step %}

### Configure the SDK

In your `AppDelegate` or `SceneDelegate`:

```swift
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)
```

{% endstep %}

{% step %}

### Add the floating widget

```swift
// 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)
])
```

{% endstep %}

{% step %}

### Handle bidirectional interactions

```swift
// 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)")
}
```

{% endstep %}

{% step %}

### Configure permissions

Add the following to your `Info.plist`:

```xml
<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>
```

{% endstep %}
{% endstepper %}

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

<table data-view="cards"><thead><tr><th></th><th></th></tr></thead><tbody><tr><td><h4>Voice conversation</h4></td><td><ul><li>Real-time voice interaction using NLX</li><li>Automatic microphone permission handling</li><li>Audio controls (mic, speaker, close)</li><li>Visual feedback for speaking states</li></ul></td></tr><tr><td><h4>Floating widget</h4></td><td><ul><li>Draggable interface that snaps to screen edges</li><li>Multiple states: idle, connecting, active, error</li><li>Customizable positioning and appearance</li><li>Native iOS accessibility support</li></ul></td></tr><tr><td><h4>Bidirectional form interaction</h4></td><td><ul><li>Automatic context analysis of current screen</li><li>Voice commands can fill form fields</li><li>Support for common UIKit controls (UITextField, UIButton, etc.)</li><li>Custom form handling callbacks</li></ul></td></tr></tbody></table>

### 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`  |