Add the HelpCrunch iOS SDK to your app

You can add the HelpCrunch SDK to your iOS application manually as well as with CocoaPods or Carthage.
Written by Andrew
Updated 9 months ago


CocoaPods is a dependency manager for Swift and Objective-C Cocoa projects. It has over 43 thousand libraries and is used by over 3 million apps. CocoaPods can help you scale your projects elegantly. If you haven’t used it before, please start here.

To integrate HelpCrunch into your Xcode project with the help of CocoaPods, specify it in your Podfile (the text file in your Xcode project directory named Podfile):

source ''
platform :ios, '11.0'
target 'ProjectTargetName' do
  pod 'HelpCrunchSDK', '~> 4.0'

Now, you can install the dependencies in your project:

$ pod install

Make sure to always open the Xcode workspace instead of the project file when building your project:

$ open App.xcworkspace


Carthage is another way to add frameworks to your Cocoa application. It builds your dependencies and provides you with binary frameworks, but you keep full control over your project's structure and setup. Carthage does not automatically modify your project files or your build settings.

If you haven’t installed it yet, please check the Installation Quick Start.

1. Create a Cartfile in the same directory where your .xcodeproj or .xcworkspace is.

2. Open the Cartfile and add the following:

github "helpcrunch/helpcrunchsdk-ios" ~> 4.0

3. ...then run the following:

$ carthage update --no-build

If you see some errors, try run following command:

rm -rf ~/Library/Caches/org.carthage.CarthageKit

4. Open General settings.

5. Drag the built HelpcrunchSDK.xcframework binary from Carthage/Checkouts/helpcrunchsdk-ios into the Embedded Binaries section. Don’t forget to select the 'Copy items' option if needed.

Swift Package Manager

SPM is a modern way to add libs to your project. It's built-in Xcode, so you don't need to install additional tools.

You can add HelpCrunchSDK as a Swift Package Repository in Xcode. You can do it by clicking on

File -> Swift Packages -> Add Package Dependency... 


Project -> YOUR_PROJECT_NAME -> Swift Packages -> +.

And add this url:

And then just follow the onscreen instructions

Manual installation

Manual installation will require several extra steps to install our SDK.

1. Download the HelpcrunchSDK.xcframework from GitHub and copy it into the Embedded Binaries section. Don’t forget to select the 'Copy items' option if needed.

Setup code

Note: if you're using Swift UI, please check this article before continue

1. Add the following import to the top of the AppDelegate.m or AppDelegate.swift:


@import HelpCrunchSDK;


import HelpCrunchSDK

2. Initialize the Helpcrunch SDK Configuration:


HCSConfiguration *configuration =
[HCSConfiguration configurationForOrganization:@"YOUR_HELPCRUNCH_SUBDOMAIN"


let configuration =
HCSConfiguration(forOrganization: "YOUR_HELPCRUNCH_SUBDOMAIN",
applicationId: "YOUR_APP_ID",
applicationSecret: "YOUR_APP_SECRET")

3. Initialize the SDK with configuration.


[HelpCrunch initWithConfiguration:configuration
completion:^(NSError * _Nullable error) {
// Do something on SDK init completion


HelpCrunch.initWith(configuration, user: nil) { (error) in
// Do something on SDK init completion

You can copy this code from the apps list in your HelpCrunch account.

4. You can always check the state enum to get a current SDK state. It could be Idle, Loading, Error, UserIsBlocked, Hidden ("Widget is shown" state of widget) or Ok, so you can show or disable your 'Contact Us' button appropriately. Also there is the HCSStateChangedNotification notification event to keep you up to date.


[HelpCrunch state]



5. To show the HelpCrunch UI, simply call the showFromController helper method on HelpCrunch:


[HelpCrunch showFromController:viewController completion:^(NSError * _Nullable error) {
// If you need to do something on completion of SDK view controller presenting

Swift: viewController) { (error) in
// If you need to do something on completion of SDK view controller presenting

viewController is required for the controller to be presented from.

6. You can check if your chat is currently displayed using:


[HelpCrunch isVisible]



7. After you have called the showFromController method, your chat widget will look like this:

8. If needed, you can close the HelpCrunch chat automatically simply by calling closeChatWithCompletion method

Update Info.plist

In order to send files and photos, you need to have the NSCameraUsageDescription, NSPhotoLibraryAddUsageDescription and NSPhotoLibraryUsageDescription entries in your Info.plist. These entries are required by Apple.

Users will see the corresponding text that you provide and will be prompted to their Camera/Photo Library permissions when they try to use their camera or open/save images to the Photo Library.

  • NSCameraUsageDescription – When users try to use their Camera.
  • NSPhotoLibraryUsageDescription – When users try to open their Photo Library.
  • NSPhotoLibraryAddUsageDescription – When users try to save images to their Photo Library.

Did this answer your question?