> ## Documentation Index
> Fetch the complete documentation index at: https://www.cometchat.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# UI Kit Builder Integration

> Step-by-step guide to integrating CometChat's UI Kit Builder into your iOS application using UI Kit Builder configuration.

This guide demonstrates how to integrate the **CometChat UI Kit Builder** configuration system into your iOS application. The configuration can be loaded into your app using a local JSON file.

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/fMPnzFAmFCFD5fSa/images/preview-builder-ios.png?fit=max&auto=format&n=fMPnzFAmFCFD5fSa&q=85&s=62ce11b3640065bf7859392a6b205a8c" width="3022" height="1716" data-path="images/preview-builder-ios.png" />
</Frame>

***

## Prerequisites

Before running this project on iOS, make sure you have:

* **Xcode** (latest version recommended)
* **macOS device** with macOS 12.0 or above
* **iOS Device or Simulator** with iOS 13.0 or above
* **CocoaPods** (latest version installed)
* **Internet connection** (required for CometChat services)

***

## Complete Integration Workflow

1. **Download the Project** - Download the project zip from the CometChat Dashboard and extract it.
2. **Install Dependencies** - Install CocoaPods dependencies.
3. **Configure Settings** - Load UI Kit Builder settings from JSON file.
4. **Build & Run** - Build and run the project in Xcode.

***

## Launch the UI Kit Builder

1. Log in to your [CometChat Dashboard](https://app.cometchat.com).
2. Select your application from the list.
3. Navigate to **Chat & Messaging** → **Get Started**.
4. Navigate to **Integrate** → **iOS** → **Launch UI Kit Builder**.

***

## Integration Options

Choose one of the following integration methods based on your needs:

| Option                                   | Best For                                                       | Complexity |
| ---------------------------------------- | -------------------------------------------------------------- | ---------- |
| **Run Sample App**                       | Quick preview and testing of Builder configurations            | Easy       |
| **Integrate Config Store** (Recommended) | Production apps where you want full control over customization | Medium     |

***

## Option 1: Run the Sample App

### Setup

### Step 1: Download and Extract Project

Download the project zip from the CometChat Dashboard and extract it.

### Step 2: Navigate to Project Folder

```bash theme={null}
cd <project-folder>
```

### Step 3: Open Xcode Project

Open the `.xcodeproj` file once to let Xcode configure the project.

### Step 4: Install Dependencies

Install dependencies using CocoaPods:

```bash theme={null}
pod install
```

### Step 5: Open Workspace

Open the `.xcworkspace` file instead of `.xcodeproj` from now on:

```bash theme={null}
open <ProjectName>.xcworkspace
```

### Step 6: Build & Run

Build and run the project in Xcode.

***

## Option 2: Integrate Builder Configuration into Your iOS App

This method gives you full control over customization and is recommended for production apps.

### Installation (CometChatBuilder)

### CocoaPods

Add to your `Podfile`:

```ruby theme={null}
pod 'CometChatBuilder'
```

Then run:

```bash theme={null}
pod install
```

### Swift Package Manager (SPM)

1. Open your Xcode project.
2. Go to **File → Add Packages**.
3. Enter the URL of your Git repository (or local path) where `CometChatBuilder` code is hosted.
4. Select the `CometChatBuilder` package and add it to your app target.

***

## Load Settings from JSON

Use this method if you are shipping a `.json` configuration file with your app.

### Step 1: Add Your JSON File

Place your `cometchat-builder-settings.json` inside your app target and make sure:

* It's added to your target membership.

### Step 2: Load Settings at Launch

```swift theme={null}
import CometChatBuilder

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    // This automatically loads JSON config
    CometChatBuilderSettings.loadFromJSON()

    CometChatTheme.primaryColor = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.brandColor)
    )
    
    CometChatTheme.textColorPrimary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.primaryTextDark)
    )
    
    CometChatTheme.textColorSecondary = UIColor.dynamicColor(
        lightModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextLight),
        darkModeColor: UIColor(hex: CometChatBuilderSettings.shared.style.color.secondaryTextDark)
    )
    
    CometChatTypography.customFontFamilyName = CometChatBuilderSettings.shared.style.typography.font

    return true
}
```

***

## Important Guidelines for Changes

<Note>
  **Functional Changes:**
  For enabling or disabling features and adjusting configurations, update the `cometchat-builder-settings.json` file. This controls all feature flags and configuration constants.
</Note>

<Note>
  **UI and Theme-related Changes:**
  For any updates related to UI, such as colors, fonts, and styles, modify the `CometChatTheme` and `CometChatTypography` properties in your AppDelegate.
</Note>

***

## Enable Features in CometChat Dashboard

If your app needs any of these features, enable them from your [Dashboard](https://app.cometchat.com):

* Stickers
* Polls
* Collaborative whiteboard
* Collaborative document
* Message translation
* AI User Copilot: Conversation starter, Conversation summary, Smart reply

**How to enable:**

<Frame>
  <img src="https://mintcdn.com/cometchat-22654f5b/HFXOvmhiLRb5ClID/images/91e1727b-dashboard_features-5d33b046f945728c1521aee216f3555a.png?fit=max&auto=format&n=HFXOvmhiLRb5ClID&q=85&s=72a2f5f7071f3104feab01df7dd851bd" width="3016" height="1594" data-path="images/91e1727b-dashboard_features-5d33b046f945728c1521aee216f3555a.png" />
</Frame>

1. Log in to the Dashboard.
2. Select your app.
3. Navigate to **Chat → Features**.
4. Toggle ON the required features and Save.

***

## What You Can Configure

Toggle these features on or off directly in the UI Kit Builder. For a full reference of each setting, see [UI Kit Builder Settings](/chat-builder/ios/builder-settings).

### Chat Features

| Category                        | Includes                                                                                                                                               |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Core Messaging Experience       | Typing indicators, threads, media sharing (photos, video, audio, files), edit & delete messages, read receipts, search, quoted replies, mark as unread |
| Deeper User Engagement          | Mentions, @all mentions, reactions, message translation, polls, collaborative whiteboard & document, voice notes, emojis, stickers, user & group info  |
| AI User Copilot                 | Conversation starters, conversation summaries, smart replies                                                                                           |
| User Management                 | Friends-only mode                                                                                                                                      |
| Group Management                | Create groups, add members, join/leave, delete groups, view members                                                                                    |
| Moderation                      | Content moderation, report messages, kick/ban users, promote/demote members                                                                            |
| Private Messaging Within Groups | Direct messages between group members                                                                                                                  |
| In-App Sounds                   | Incoming & outgoing message sounds                                                                                                                     |

### Call Features

| Category              | Includes                                                                             |
| --------------------- | ------------------------------------------------------------------------------------ |
| Voice & Video Calling | 1:1 voice calling, 1:1 video calling, group voice conference, group video conference |

### Layout

| Category | Includes                                |
| -------- | --------------------------------------- |
| Sidebar  | With Sidebar or Without Sidebar mode    |
| Tabs     | Conversations, Call Logs, Users, Groups |

### Theming

| Category   | Includes                                                    |
| ---------- | ----------------------------------------------------------- |
| Theme      | System, Light, or Dark mode                                 |
| Colors     | Brand color, primary & secondary text colors (light & dark) |
| Typography | Font family, text sizing (default, compact, comfortable)    |

***

## Troubleshooting

### JSON File Not Found

* Ensure your `cometchat-builder-settings.json` is added to the app bundle.
* Confirm the file is included in your app target's Target Membership.

### Network Errors

* Network errors will fallback to user alerts.
* Ensure you have an active internet connection.

### SPM Resource Issues

* For SPM: make sure resources (images) are in `CometChatBuilder.bundle`.
* Confirm package resources are available to your target.

### QR Code Issues

* Ensure your QR code is valid and generated from the official builder.
* Confirm active network connectivity.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Builder Settings" href="/chat-builder/ios/builder-settings">
    Understand the settings file and feature toggles.
  </Card>

  <Card title="Customizations" href="/chat-builder/ios/builder-customisations">
    Adjust component props, behavior, and UI elements.
  </Card>

  <Card title="Directory Structure" href="/chat-builder/ios/builder-dir-structure">
    See how the exported code is organized.
  </Card>

  <Card title="UI Kit Theme" href="/ui-kit/ios/theme-introduction">
    Customize colors, typography, and styling to match your brand.
  </Card>
</CardGroup>