This guide covers how to install and get started with the Kustomer Chat iOS SDK. The current version is <<iOS_SDK_Version>>.
## Prerequisites
See [Requirements](🔗).
## Install the Kustomer Chat iOS SDK
Install the Chat iOS SDK files with one of the following methods:
Swift Package Manager
CocoaPods
Manual installation (Xcode framework)
Starting with iOS version 2.6.0, the PubNub library is downloaded as a dependency if installing the SDK using the Swift Package Manager or Cocoapods.
### Swift Package Manger installation
You can install the Kustomer Chat iOS files as a package dependency for your app. To learn more, see [Adding Package Dependencies to Your App](🔗) in the Apple Developer portal.
To install with the [Swift Package Manager](🔗):
Open or create your project in Xcode.
With your project open in Xcode, go to **File > Swift Packages > Add Package Dependency**.
For the URL, enter `
https://github.com/kustomer/kustomer-ios
`.Under **Rules**, select **Up to next Major**. Set the version to span **2.0.0 < 3.0.0**, select **Next**.
### CocoaPods installation
You can install the Kustomer Chat iOS files with the CocoaPods Swift dependency manager. To learn more, see the [CocoaPods developer documentation](🔗).
To install with [CocoaPods](🔗):
To your Podfile, add the following pod:
`
pod 'KustomerChat'
`Run `
pod install
` or `pod update
` on your project.To learn more, see [`
pod install
` vs. `pod update
`](🔗) in the CocoaPods developer documentation.
### Manual installation
You can install the Kustomer Chat iOS file manually in Xcode as an Xcode framework.
To install manually in Xcode:
In Xcode add `
KustomerChat.xcframework
` and to your project in the **Framesworks, Libraries, and Embedded Content** section. You can find the framework [here](🔗).After you add the framework to your project, check that it has the **Embed & Sign** attribute under **Embed**.
Add PubNub using your preferred method. You can find details in their documentation [here](🔗).
If you add PubNub as a git submodule, you must install the PubNub version required by our podspec/package.swift.
## Allow file uploads over chat
To allow customers to upload files through chat, in Xcode add privacy descriptions to your `Info.plist
` file for the user's camera roll, media library, and local documents:
## Quick start
Import `KustomerChat
` to your AppDelegate and call `Kustomer.configure()
` to initiate chat.
Call `Kustomer.configure()
` with or without options. Initialize chat with options to override settingsin the SDK.
### Initialize the Chat iOS SDK
To initialize the Chat iOS SDK:
Add `
import KustomerChat
` to your AppDelegate.In the `
application(_:didFinishLaunchingWithOptions:)
` method of your AppDelegate, call `Kustomer.configure()
`.
We've included a code sample below.
Note
To use the code sample for your app, replace `
api key
` with an API key with the `org.tracking
` role for your Kustomer organization.
### Initialize the Chat iOS SDK with options
You can also use `Kustomer.configure()
` to initialize the Chat iOS SDK with options to override settings in the SDK. For more information, see the [KustomerOptions Class Reference](🔗).
We've include a code sample below.
Note
To use the code sample for your app, replace `
api key
` with an API key with the `org.tracking
` role for your Kustomer organization.
#### `KustomerOptions
` class reference
`
KustomerOptions
` API attributesFor additional configuration options for initialization, see the full list of all available [`
KustomerOptions
` API attributes](🔗).
Parameter | Description |
`activeAssistant ` | The chat assistant ID. If available, Chat always uses this chat assistant ID as the assistant when a new conversation is created with a button in the chat. Does not affect the Core SDK.<br /><br />**Options:**<br />`none `: Chat does not use an assistant. <br />`orgDefault `: Chat uses the default assistant set for the brand under [Chat Management settings](🔗). `.withId(String) `: Chat uses the provided string as the assistant ID. Format example: `options.activeAssistant = .withId("1234") ` |
`showInAppNotifications ` | Boolean that determines if in-app notifications should be shown. Default is `true ` |
`language ` | The language for displaying volume control content, automated messages, snippets, and Knowledge Base articles. If blank, Kustomer Chat uses the device language as the default language.<br /><br />See [Localization](🔗) for supported language locales and instructions to change the default language or to add a new localization. |
`enableUI ` | Boolean that determines if the SDK will use the default Kustomer Chat UI.<br /><br />Default is `true `. Set to `false ` if you [Build your own UI](🔗). |
`pushBundleId ` | Sets the topic for push notifications, usually your app's bundle ID. Default is the bundle ID of your application. |
`pushEnvironment ` | Tells the push notification service to use either the `development ` or `production ` environment. Default is `production `. |
`hideNewConversationButtonInClosedChat ` | Boolean that determines if a "New Conversation" button should appear at the bottom of closed chats. Default is `false `. Set as `true ` to stop customers from starting new chats from an ended chat screen. |
`hostDomain ` | Set this option to use a custom host domain. You do not have to do this unless instructed by a Kustomer representative or developer. Default is the default Kustomer API domain. |
`businessScheduleId ` | Set this to use a business schedule ID for a custom [Business Schedule](🔗) created in Kustomer. Default is the default business schedule for your org. |
`knowledgeBaseId ` <br/><br/> _Deprecated for Chat 2.0_ | Overrides the Knowledge Base id. <br/> <br/> _This method has been deprecated. Use `brandId ` instead to fetch brand-specific chat settings, including a brand-specific Knowledge Base_. |
`brandId ` | Provides a Brand ID to fetch brand-specific chat settings. Default is the default brand ID for your org. |
`logLevels ` | The type of error logs available. To learn more, see [KustomerLogType](🔗).<br /><br />Defaults to `[.debug, .info, .error, .warning] ` .<br /><br />Set to `[] ` to disable logging. <br /><br />`multithreadingWarning ` will only be logged if you are building your own UI |
`messageAttachmentLocalCacheMaximumSizeInBytes ` | Max size of local cache for message attachments. Defaults to 25MB. Minimum of 10MB, maximum of `Int.max `. Files attached to support chats are saved to the documents folder. Once this local cache exceeds this value, the cache is cleared the next time the customer downloads a new message attachment. |
`showAnimationFor5StarCSATRatings ` | Controls the chat animation displayed to customers for 5-star CSAT ratings. Defaults to `false `. Set to `true ` to turn on the CSAT animation. |
To learn how to build on Kustomer Chat further with the iOS SDK, see [Overview: iOS SDK](🔗).
### Open Kustomer Chat
The Kustomer Chat iOS SDK provides a modern interface for chat support and native knowledge base access through chat.
Use `Kustomer.show()
` to open the Kustomer Chat interface from any part of your app.
Build your own chat UI 🛠
You can override the Kustomer Chat UI and use the iOS Chat SDK with your own custom view controllers and interface. Use the `
ChatProvider
`and `ChatListener
` classes to interact with the Kustomer API directly.To learn more, see [Build your own UI](🔗).
### Customize Kustomer Chat
Admins in your Kustomer organization can configure basic chat settings directly in Kustomer. To learn more, see [Introduction to Kustomer Chat](🔗) in the Kustomer Help Center.
See [Overview: iOS SDK](🔗) for a collection of guides on how to build on Kustomer Chat with the Chat SDK.