# 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="/files/HDYzUTwAdZ4sDAIPE37K" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/tRa4lhS57vtOe5xTIy7e" 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`  |


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nlx.ai/platform/developers/conversation-sdk/setup/ios.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.