The Assembled Chat SDK allows you to integrate Assembled's AI-powered chat widget directly into your iOS and Android mobile applications, providing your customers with seamless in-app support.

## Overview

The Assembled Chat SDKs provide:

- Native mobile integration for iOS and Android
- JWT-based user authentication
- Custom user data support for personalization
- Customizable widget appearance
- Full control over chat initialization and display
- Support for both SwiftUI/UIKit (iOS) and Jetpack Compose/Views (Android)

* * *

## iOS SDK Setup

### Requirements

- iOS 13.0 or later
- Swift 5.9 or later
- Xcode 14.0 or later
- Deployment Target: iOS 13.0+

### Installation

1. In Xcode, go to **File > Add Package Dependencies**  
2. Enter the repository URL: [`https://github.com/assembledhq/assembled-chat-ios-sdk.git`](https://github.com/assembledhq/assembled-chat-ios-sdk)

3. Select the latest version  
4. Click **Add Package**

Alternatively, add to your `Package.swift`:

```auto
dependencies: [\
    .package(url: "https://github.com/assembledhq/assembled-chat-ios-sdk.git", from: "1.0.0")\
]
```

Then add `AssembledChat` to your target dependencies:

```auto
.target(
    name: "YourApp",
    dependencies: ["AssembledChat"]
)
```

You can also use **CocoaPods** by adding the following to your `Podfile` and running `pod install` afterwards:

```auto
platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!

pod 'AssembledChat', '~> 1.0'
end
```

### Basic implementation

#### Import the SDK

```auto
import AssembledChat
```

#### Initialize and display the chat widget

```auto
import UIKit
import AssembledChat

class ViewController: UIViewController {
    private var chat: AssembledChat?

override func viewDidLoad() {
        super.viewDidLoad()

let config = AssembledChatConfiguration(
            companyId: "YOUR_COMPANY_ID"
        )

chat = AssembledChat(configuration: config)
        chat?.delegate = self

Task {
            try await chat?.initialize()
            chat?.open()
        }
    }
}

extension ViewController: AssembledChatDelegate {
    func assembledChatDidLoad() {
        print("Chat loaded")
    }

func assembledChatDidOpen() {
        print("Chat opened")
    }

func assembledChatDidClose() {
        print("Chat closed")
    }

func assembledChat(didReceiveError error: Error) {
        print("Error: \(error.localizedDescription)")
    }
}
```

### SwiftUI implementation

```auto
import SwiftUI
import AssembledChat

struct ContentView: View {
    @StateObject private var chatManager = AssembledChatManager(
        configuration: AssembledChatConfiguration(
            companyId: "YOUR_COMPANY_ID"
        )
    )

var body: some View {
        VStack {
            Button("Open Chat") {
                Task {
                    if !chatManager.isReady {
                        try await chatManager.initialize()
                    }
                    chatManager.open()
                }
            }

if chatManager.isOpen {
                AssembledChatSwiftUIView(
                    configuration: chatManager.chatInstance.configuration
                )
            }
        }
    }
}
```

### iOS configuration options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `companyId` | String | Yes | Your Assembled company identifier |
| `profileId` | String? | No | Target a specific chat profile |
| `activated` | Bool | No | Override activation state (default: true) |
| `disableLauncher` | Bool | No | Hide the launcher button (default: false) |
| `buttonColor` | String? | No | Custom button color in hex format |
| `debug` | Bool | No | Enable debug logging (default: false) |
| `jwtToken` | String? | No | JWT token for authenticated sessions |
| `userData` | UserData? | No | User information for personalization |

* * *

## Android SDK Setup

### Requirements

- Android API 21 (Android 5.0) or higher
- Target SDK 34
- Kotlin 1.9.20 or later
- Android Studio Arctic Fox or later
- Gradle: 7.0 or later

### Installation with Gradle

Add the SDK dependency to your app's `build.gradle.kts`:

```auto
dependencies {
    implementation("io.github.assembledhq:assembledchat:1.0.0")
}
```

Or if using Groovy (`build.gradle`):

```auto
dependencies {
    implementation("io.github.assembledhq:assembledchat:1.0.0")
}
```

The Maven Central coordinate can be found at: [https://central.sonatype.com/artifact/io.github.assembledhq/assembledchat](https://central.sonatype.com/artifact/io.github.assembledhq/assembledchat)

Ensure repositories are configured in your `settings.gradle.kts`:

```auto
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
```

### Basic implementation

#### Launch as a full-screen Activity

```auto
import com.assembled.chat.models.AssembledChatConfiguration
import com.assembled.chat.ui.AssembledChatActivity

val configuration = AssembledChatConfiguration(
    companyId = "YOUR_COMPANY_ID"
)

val intent = AssembledChatActivity.createIntent(this, configuration)
startActivity(intent)
```

#### Embed in a Fragment or View

```auto
import com.assembled.chat.AssembledChat
import com.assembled.chat.AssembledChatListener
import com.assembled.chat.models.AssembledChatConfiguration

class ChatFragment : Fragment(), AssembledChatListener {
    private lateinit var chat: AssembledChat

override fun onCreateView(
        inflater: LayoutInflater,
        container: ViewGroup?,
        savedInstanceState: Bundle?
    ): View {
        val view = inflater.inflate(R.layout.fragment_chat, container, false)
        val chatContainer = view.findViewById<FrameLayout>(R.id.chatContainer)

val config = AssembledChatConfiguration(
            companyId = "YOUR_COMPANY_ID"
        )

chat = AssembledChat(config)
        chat.listener = this
        chat.initialize(requireContext())

chat.getWebView()?.let { webView ->
            chatContainer.addView(webView)
        }

chat.open()
        return view
    }

override fun onDestroy() {
        super.onDestroy()
        chat.destroy()
    }

override fun onChatReady() {
        Log.d("Chat", "Ready")
    }

override fun onChatOpened() {
        Log.d("Chat", "Opened")
    }

override fun onChatClosed() {
        Log.d("Chat", "Closed")
    }

override fun onError(error: ChatError) {
        Log.e("Chat", "Error: $error")
    }
}
```

### Jetpack Compose implementation

```auto
import androidx.compose.runtime.Composable
import com.assembled.chat.ui.AssembledChatComposable

@Composable
fun ChatScreen() {
    AssembledChatComposable(
        companyId = "YOUR_COMPANY_ID",
        modifier = Modifier.fillMaxSize(),
        onReady = { Log.d("Chat", "Ready") },
        onOpened = { Log.d("Chat", "Opened") },
        onClosed = { Log.d("Chat", "Closed") },
        onError = { error -> Log.e("Chat", "Error: $error") }
    )
}
```

### Android configuration options

| Option | Type | Required | Description |
| --- | --- | --- | --- |
| `companyId` | String | Yes | Your Assembled company identifier |
| `profileId` | String? | No | Target a specific chat profile |
| `activated` | Boolean | No | Override activation state (default: true) |
| `disableLauncher` | Boolean | No | Hide the launcher button (default: false) |
| `buttonColor` | String? | No | Custom button color in hex format (e.g., "#007AFF") |
| `debug` | Boolean | No | Enable debug logging (default: false) |
| `jwtToken` | String? | No | JWT token for authenticated sessions |
| `userData` | UserData? | No | User information for personalization |

* * *

## User authentication

Both SDKs support user authentication to link chat interactions to user accounts and provide personalized experiences.

### User data interface

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `userId` | String | Yes | User's unique identifier |
| `email` | String | No | User's email address |
| `name` | String | No | User's display name |

### iOS authentication example

```auto
let userData = UserData(
    userId: "user123",
    email: "user@example.com",
    name: "John Doe"
)

let config = AssembledChatConfiguration(
    companyId: "YOUR_COMPANY_ID",
    jwtToken: "YOUR_JWT_TOKEN",
    userData: userData
)
```

### Android authentication example

```auto
val userData = UserData(
    userId = "user123",
    email = "user@example.com",
    name = "John Doe"
)

val config = AssembledChatConfiguration(
    companyId = "YOUR_COMPANY_ID",
    jwtToken = "YOUR_JWT_TOKEN",
    userData = userData
)
```

💡 To generate JWT tokens, retrieve your JWT secret from the Chat agent Setup tab in Assembled and create tokens on your server. See the [Quick installation guide](https://support.assembled.com/hc/en-us/articles/33739474023693) for detailed JWT token generation examples.

* * *

## Finding your company ID

1. Navigate to the [Chat agent page](https://app.assembledhq.com/automations/chat) in Assembled
2. Select the **Setup** tab
3. Your company ID will be visible in the installation code snippets

* * *

## Troubleshooting

Common issues and solutions:

### **iOS issues**

1. Chat not loading:
   - Ensure you've called `initialize()` before `open()`
   - Check that your company ID is correct
   - Verify iOS version meets minimum requirement (iOS 13.0+)
2. Build errors:
   - Verify Swift version compatibility (5.9+)
   - Check that the SDK package was added correctly

### **Android issues**

1. WebView not displaying:
   - Ensure your Activity/Fragment layout has proper dimensions
   - Check that the WebView was successfully added to the container
2. Memory leaks:
   - Always call `chat.destroy()` in `onDestroy()`
   - Remove references to the chat instance when done
3. Initialization errors:
   - Verify `companyId` is valid and not blank
   - Check console logs with `debug = true` enabled

* * *

## Support

For additional help, contact your Assembled implementation manager on Slack or reach out to the Assembled support team ( [support@assembledhq.com](mailto:support@assembledhq.com)).

**Note**: The iOS and Android SDKs are currently in Alpha. Features and APIs may change before general availability.