Customerly iOS SDK

Customerly is a customer service platform that helps businesses provide better support to their customers. The iOS SDK allows you to integrate Customerly's features directly into your iOS application, including:

• Live chat support
• Help center articles
• User profiling
• Event tracking
• Lead generation
• Surveys
• Real-time video calls

Installation

Swift Package Manager

Add the following dependency to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/customerly/CustomerlyiOSSDK.git", from: "1.2.0")
]

CocoaPods

Add the following line to your Podfile:

pod 'Customerly'

Then run:

pod install

Basic Usage

CustomerlyView

A SwiftUI view that integrates the Customerly messenger into your app. It initializes the SDK with the settings provided and attaches the SDK to the SwiftUI view hierarchy.

Important: The SDK requires two initialization steps to work properly:

1. Calling load(settings:) to initialize the SDK
2. Providing a parent view controller either via load(settings:parent:) or setParent(_:)

When using CustomerlyView, both requirements are automatically handled for you. If you're not using CustomerlyView, you must handle these requirements manually.

import SwiftUI
import CustomerlySDK

@main
struct SampleAppApp: App {
    var body: some Scene {
        WindowGroup {
            ZStack {
                // Your app content here

                CustomerlyView(settings: CustomerlySettings(app_id: "YOUR_APP_ID")).onAppear(){
                    Customerly.shared.requestNotificationPermissionIfNeeded()
                }
            }
        }
    }
}

Handling notifications

The SDK will use the UNUserNotificationCenter to present local notifications when a new message is received. We suggest you to add an AppDelegate to handle the notifications and open the messenger when a notification is tapped.

// ...
import UserNotifications

class AppDelegate: NSObject, UIApplicationDelegate, UNUserNotificationCenterDelegate {
    func application(_ application: UIApplication,
                     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
        UNUserNotificationCenter.current().delegate = self
        return true
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter,
                                willPresent notification: UNNotification,
                                withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
        completionHandler([.banner, .sound, .list])
    }

    func userNotificationCenter(_ center: UNUserNotificationCenter,
                            didReceive response: UNNotificationResponse,
                            withCompletionHandler completionHandler: @escaping () -> Void) {
        let userInfo = response.notification.request.content.userInfo
        if let conversationId = userInfo["conversationId"] as? Int {
            Customerly.shared.navigateToConversation(conversationId: conversationId)
        }
        Customerly.shared.show(withoutNavigation: true)
        completionHandler()
    }
}

@main
struct SampleAppApp: App {
    @UIApplicationDelegateAdaptor(AppDelegate.self) var appDelegate

    // ...
}

APIs

Initialization and Configuration

load

Initializes the Customerly SDK with the provided settings.

Customerly.shared.load(settings: CustomerlySettings(app_id: "YOUR_APP_ID"), parent: self)

setParent

Sets a new parent view controller for presenting the messenger.

Customerly.shared.setParent(self)

update

Updates the Customerly SDK settings.

Customerly.shared.update(settings: CustomerlySettings(app_id: "YOUR_APP_ID"))

requestNotificationPermissionIfNeeded

Requests notification permissions if not already granted.

Customerly.shared.requestNotificationPermissionIfNeeded()

Messenger Control

show

Shows the Customerly chat interface.

Customerly.shared.show(withoutNavigation: false)

hide

Hides the Customerly chat interface.

Customerly.shared.hide()

back

Navigates back in the chat interface.

Customerly.shared.back()

User Management

logout

Logs out the current user.

Customerly.shared.logout()

registerLead

Registers a new lead with the provided email and optional attributes.

Customerly.shared.registerLead(email: "test@example.com", attributes: ["name": "John Doe"])

Messaging

showNewMessage

Shows the chat interface with a pre-filled message.

Customerly.shared.showNewMessage(message: "Hello, how can I help you?")

sendNewMessage

Sends a new message and shows the chat interface.

Customerly.shared.sendNewMessage(message: "Hello, how can I help you?")

navigateToConversation

Navigates to a specific conversation.

Customerly.shared.navigateToConversation(conversationId: 123)

Help Center

showArticle

Shows a specific help center article.

Customerly.shared.showArticle(collectionSlug: "collection", articleSlug: "article")

Analytics

event

Tracks a custom event.

Customerly.shared.event(name: "event_name")

attribute

Sets a custom attribute for the current user.

Customerly.shared.attribute(name: "attribute_name", value: "attribute_value")

Message Counts

getUnreadMessagesCount

Gets the count of unread messages.

Customerly.shared.getUnreadMessagesCount(completion: { count in
    print("Unread messages count: \(count)")
})

getUnreadConversationsCount

Gets the count of unread conversations.

Customerly.shared.getUnreadConversationsCount(completion: { count in
    print("Unread conversations count: \(count)")
})

Callbacks

The SDK provides various callbacks for different events. Here are the main callback setters:

func setOnChatClosed(_ callback: @escaping () -> Void)
func setOnChatOpened(_ callback: @escaping () -> Void)
func setOnHelpCenterArticleOpened(_ callback: @escaping (HelpCenterArticle) -> Void)
func setOnLeadGenerated(_ callback: @escaping (String?) -> Void)
func setOnMessageRead(_ callback: @escaping (Int, Int) -> Void)
func setOnMessengerInitialized(_ callback: @escaping () -> Void)
func setOnNewConversation(_ callback: @escaping (String, [AttachmentPayload]) -> Void)
func setOnNewMessageReceived(_ callback: @escaping (UnreadMessage) -> Void)
func setOnNewConversationReceived(_ callback: @escaping (Int) -> Void)
func setOnProfilingQuestionAnswered(_ callback: @escaping (String, String) -> Void)
func setOnProfilingQuestionAsked(_ callback: @escaping (String) -> Void)
func setOnRealtimeVideoAnswered(_ callback: @escaping (RealtimeCall) -> Void)
func setOnRealtimeVideoCanceled(_ callback: @escaping () -> Void)
func setOnRealtimeVideoReceived(_ callback: @escaping (RealtimeCall) -> Void)
func setOnRealtimeVideoRejected(_ callback: @escaping () -> Void)
func setOnSurveyAnswered(_ callback: @escaping () -> Void)
func setOnSurveyPresented(_ callback: @escaping (Survey) -> Void)
func setOnSurveyRejected(_ callback: @escaping () -> Void)

Each callback has a corresponding remove method:

func removeOnChatClosed()
func removeOnChatOpened()
// ... and so on for all callbacks

You can also remove all callbacks at once:

func removeAllCallbacks()

Examples

The repository includes a sample project (SampleApp) that demonstrates how to integrate and use the Customerly SDK in a SwiftUI application. The example shows:

• Basic SDK initialization
• Messenger presentation
• User management
• Event tracking
• Message handling
• Notification handling
• Callback usage

To run the example:

1. Open the project in Xcode
2. Replace the app_id in SampleAppApp.swift with your Customerly app ID
3. Build and run the project

The sample app provides a complete reference implementation of all SDK features and can be used as a starting point for your integration.

Development

The version must stay in sync across three places:

• Customerly.podspec (s.version)
• README.md (the Swift Package Manager version line above)
• CustomerlySDK/Customerly.swift (Customerly.version)

To release a new version of the SDK:

1. Bump the version in all three files above.
2. Push the changes to the default branch (master).
3. Create and push a tag matching the version without a v prefix (e.g. 1.0.6); the release workflow triggers on tags of the form *.*.*.
4. The GitHub Actions workflow verifies the tag, podspec, README and Swift versions match (auto-committing a fix and re-tagging if they don't), then pushes the pod to CocoaPods trunk. SPM consumers just resolve the git tag — no publish step.

License

Copyright 2025-2026 Customerly Ltd.

This SDK is licensed under the Apache License 2.0 — you are free to use it in commercial and closed-source applications. See the LICENSE and NOTICE files for details.

Versions up to and including 1.1.1 were published under the GNU GPLv3. The Apache 2.0 license applies from the next release onwards. If you are pinned to an older version, upgrade to pick up the more permissive terms.