Getting Started

Prerequisites

Before starting the integration of the Zendesk SDK, please ensure that the following prerequisites are fulfilled.

Ensure you meet the minimum supported iOS version

The minimum operating system version required for the Zendesk SDK is iOS 10.

Obtain a channel key from Zendesk's Admin Center

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Add the SDK dependencies

You can add the iOS SDK to your project using one of the following methods:

See Release Notes for the latest available versions.

Swift Package Manager

Swift Package Manager is a dependency manager for managing and distributing Swift code. It's integrated with the Swift build system. As of Xcode 11, you can use it inside Xcode.

  1. In Xcode, select File > Swift Packages > Add Package Dependency.

  2. Add the repository https://github.com/zendesk/sdk_messaging_ios/ and follow Xcode's instructions to add ZendeskMessagingSDK as a dependency. Swift Package Manager will resolve any required dependencies and download them as needed.

CocoaPods

CocoaPods is a dependency manager that lets you add third-party frameworks and libraries to projects. For installation instructions, see Install CocoaPods.

  1. In your Podfile, add the following:

    pod 'ZendeskSDKMessaging'
  2. Run the pod install command.

Carthage

Carthage is a dependency manager for iOS applications. For installation and usage instructions, see Installing Carthage in the Carthage readme on Github.

  1. Add the following dependency to your Cartfile.

    github "zendesk/sdk_messaging_ios" ~> 1.2.1
  2. Run carthage update --use-xcframeworks --use-binaries.

    Carthage will check out and download all necessary dependencies to the Carthage/Checkouts directory in your project and build the binaries to Carthage/Build/iOS.

  3. Your targets FRAMEWORK_SEARCH_PATHS should be updated to point to Carthage/Build/iOS.

  4. On your targets General tab, drag each of the downloaded frameworks to the Frameworks, Libraries and Embedded Content section and embed the frameworks by selecting the Embed & Sign option.

  5. Create a new "Run Scripts Phase" in your target's "Build Phases".

    This script should be the last step in your project's "Build Phases". Paste the following snippet into the script text field:

    ${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/ZendeskSDKMessaging.framework/strip-frameworks.sh

    This step is required to work around an App store submission bug when archiving universal binaries. Please ensure your project's VALID_ARCHS build setting does not contain "i386" or "x86_64" for release configuration.

  6. Xcode 12.3 (and above) Integrators In your targets "Build Settings" set VALIDATE_WORKSPACE=NO. Without this, you may see a build error Building for iOS Simulator, but the linked and embedded framework <name>.framework was built for iOS + iOS Simulator. This is a temporary fix until Carthage releases XCFramework support.

Manual

  1. Download the following repositories:

    Each repository contains a .xcframework file that you import into your project.

  2. In Xcode, select your project in Project navigator:

  3. In Finder, navigate to where you extracted each of the SDKs.

  4. Ensure a Frameworks directory exists in the top level of your project directory. Create this directory if it doesn't exist.

  5. Copy the following items into the Frameworks folder in your project:

    • ZendeskSDKMessaging.xcframework
    • ZendeskSDKConversationKit.xcframework
    • ZendeskSDKUIComponents.xcframework
    • ZendeskSDKFayeClient.xcframework
    • ZendeskSDKStorage.xcframework
    • ZendeskSDKHTTPClient.xcframework
    • ZendeskSDKLogger.xcframework
    • ZendeskSDKSocketClient.xcframework
  6. Drag the frameworks into the Frameworks, Libraries and Embedded Content section of your project and embed the frameworks by selecting Embed & Sign option.

  7. In Build Settings, set the CLANG_ENABLE_MODULES field to YES.

Obtain the channel key

Before you initialize your SDK, you'll need to obtain a channel key. The channel key is a unique identifier that the SDK requires to initialize correctly. You can obtain it from the Zendesk Admin Center. For instructions, see Working with messaging in the Zendesk SDKs for Android and iOS. If you're not a Zendesk admin on your account, ask one to get it for you.

Initialize the SDK

  1. Add the following import to your project:

    Swift

    import ZendeskSDKMessaging

    Objective-c

    #import <ZendeskSDKMessaging/ZendeskSDKMessaging.h>
  2. Call Messaging.initialize(channelKey:completionHandler:).

    If successful, an instance of messaging is returned. You don't have to keep a reference to the returned instance because you can access it anytime by using Messaging.instance.

    Examples:

    Swift

    Messaging.initialize(channelKey: <#"Channel Key"#>) { result in            // Tracking the error from initialization failures in your            // crash reporting dashboard will help to triage any unexpected failures in production           if case let .failure(error) = result {               print("Messaging did not initialize.\nError: \(error.errorDescription ?? "")")           }       }

    Objective-C

    [ZDKMessaging initializeWithChannelKey:<#"Channel Key"#>                        completionHandler:^(ZDKMessaging * _Nullable messaging, NSError * _Nullable error) {        // Tracking the error from initialization failures in your crash        // reporting dashboard will help to triage any unexpected failures in production       if (error != nil) {           NSLog(@"Messaging did not initialize.\nError: %@", error.localizedDescription);       }   }];

Show the conversation

  1. Call the messagingViewController() method as part of the messaging reference returned during initialization.

    Swift

    guard let viewController = Messaging.instance?.messagingViewController() else { return }self.navigationController?.show(viewController, sender: self)

    Objective-C

    UIViewController *viewController = [ZDKMessaging.instance messagingViewController];if (viewController != NULL) {    [self.navigationController showViewController:viewController sender:self];}

Next Steps

If you have completed the steps above, you are now in good shape to explore the SDK and understand how messaging will work for your business and your end users.

Push Notifications

To ensure a good end-user experience, we also recommend setting up push notifications to work correctly with your app. The steps required to set it up are outlined in Push notifications.

Advanced Integration

To explore more advanced integration options, see Advanced integration.

Troubleshooting

We recommend tracking the cause of any initialization failures in your crash reporting dashboard. This will help in troubleshooting your integration once deployed in production.

If you have any difficulty getting starting, or wish to see more detailed information from the SDK, you can enable logging. This can be set in your AppDelegate in application(didFinishLaunchingWithOptions).

Swift

import ZendeskSDKLogger
Logger.enabled = trueLogger.level = .default
// Possible levels:// .default// .info// .debug// .error// .fault

Objective-C

#import <ZendeskSDKLogger/ZendeskSDKLogger.h>
ZDKLogger.enabled = YES;ZDKLogger.level = ZDKLogLevelDefault;
// Possible levels:// ZDKLogLevelDefault// ZDKLogLevelInfo// ZDKLogLevelDebug// ZDKLogLevelError// ZDKLogLevelFault

Levels

Default: A default level which is a general logging level. It's better to be specific by using other log levels.

Info: Contains information that may be helpful, but not essential, while troubleshooting problems.

Debug: Contains information useful during development while actively debugging.

Error: Contains information about errors and failures.

Fault: Contains information about serious problems.