Getting Started

Getting Started

Prerequisites

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

• Available on all Zendesk Support or Zendesk Suite plans
• iOS 12 or later

Add the SDK dependencies

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

• Swift Package Manager
• CocoaPods
• Carthage
• Manual

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 apps. 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"

2. Run carthage update --use-xcframeworks.

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

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

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.

Manual

1. Download the following repositories:

   • https://github.com/zendesk/sdk_messaging_ios
   • https://github.com/zendesk/sdk_zendesk_ios
   • https://github.com/zendesk/sdk_conversation_kit_ios
   • https://github.com/zendesk/sdk_ui_components_ios
   • https://github.com/zendesk/sdk_core_utilities_ios
   • https://github.com/zendesk/sdk_faye_client_ios
   • https://github.com/zendesk/sdk_storage_ios
   • https://github.com/zendesk/sdk_http_client_ios
   • https://github.com/zendesk/sdk_logger_ios
   • https://github.com/zendesk/sdk_socket_client_ios
   • https://github.com/zendesk/sdk_guide_kit_ios

   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
   • ZendeskSDK.xcframework
   • ZendeskSDKConversationKit.xcframework
   • ZendeskSDKUIComponents.xcframework
   • ZendeskSDKCoreUtilities.xcframework
   • ZendeskSDKFayeClient.xcframework
   • ZendeskSDKStorage.xcframework
   • ZendeskSDKHTTPClient.xcframework
   • ZendeskSDKLogger.xcframework
   • ZendeskSDKSocketClient.xcframework
   • ZendeskSDKGuideKit.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
   import ZendeskSDK

   Objective-c

   #import <ZendeskSDKMessaging/ZendeskSDKMessaging.h>
   #import <ZendeskSDK/ZendeskSDK.h>

2. Call Zendesk.initialize(withChannelKey: ,messagingFactory: ,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 Zendesk.instance.

   Examples:

   Swift

   Zendesk.initialize(withChannelKey: "channel_key",
                      messagingFactory: DefaultMessagingFactory()) { result in
           if case let .failure(error) = result {
               print("Messaging did not initialize.\nError: \(error.localizedDescription)")
           }
       }

   Objective-C

   [Zendesk initializeWithChannelKey:@"<channel_key>"
                    messagingFactory:[[ZDKDefaultMessagingFactory alloc] init]
                   completionHandler:^(Zendesk * _Nullable zendesk, NSError * _Nullable error) {
           if (error != nil) {
               NSLog(@"Zendesk 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 = Zendesk.instance?.messaging?.messagingViewController() else { return }
   self.navigationController?.show(viewController, sender: self)

   Objective-C

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

Demo Apps

We provide our users multiple demo apps to showcase our SDK's functionalities.

Each app showcases one specific feature, including a basic implementation, JWT authentication, and more. The README file details how to configure and run each app.

You can find them in our Zendesk SDK Demo apps github.

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.

Unread Messages

When the user receives a new message, an event is triggered with the updated total number of unread messages. To subscribe to this event, add an event observer to your Zendesk SDK instance. See Events for the necessary steps to observe unread messages.

In addition, you can retrieve the current total number of unread messages by calling getUnreadMessageCount() on Messaging on your Zendesk SDK instance.

Swift

Zendesk.instance?.messaging?.getUnreadMessageCount()

Objective-C

// Get the instance of messaging
Zendesk *instance = [Zendesk instance];

// Get the unread count
NSNumber *unreadCount = @(instance.messaging.getUnreadMessageCount);

Property List Keys

Include the following plist entries to your app to support uploading images or videos taken directly from the camera:

• NSCameraUsageDescription - allows access to the device’s camera for images and videos.
• NSMicrophoneUsageDescription - allows access to the device’s microphone for use when capturing videos with the camera.
• NSPhotoLibraryUsageDescription - allows read and write access in photo library (iOS14+).
• NSPhotoLibraryAddUsageDescription - allows write access in photo library (below iOS14).

Note

• Below iOS 14, the NSPhotoLibraryAddUsageDescription key is mandatory, to have the share button displayed and save an image to the photo library.
• Between iOS 14 and iOS 15 the NSPhotoLibraryUsageDescription key is mandatory, to have the share button displayed and save an image to the photo library.
• From iOS 15, the share button is always present, however the option to share in the photo library is not present if the NSPhotoLibraryUsageDescription key is missing.

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 = true
Logger.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

Log 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.