iOS SDK

This guide covers adding the Smooch iOS SDK to your app as well as the configuration and customization options available.

Reference

Adding Smooch to your app

The Smooch iOS SDK supports installation through both CocoaPods and Carthage. Read on and follow your preferred way of adding the SDK to your project.

CocoaPods

First, install CocoaPods if it isn’t already:

$ sudo gem install cocoapods

Next, add the Smooch dependency to your Podfile:

pod 'Smooch'

Finally, install the pod:

$ pod install

That’s it! You’re now ready to initialize Smooch in your app.

Carthage

First, follow the steps to install Carthage on your system if it isn’t already:

$ brew install carthage

Next, add the Smooch framework to your Cartfile:

github "smooch/smooch-ios"

And finally, follow the installation steps for iOS projects to link the Smooch dependency to your application.

That’s it! You’re now ready to initialize Smooch in your app.

Manual Installation

Import the Smooch header file

Import the Smooch file into the your app delegate’s .m file and any other places you plan to use it.

Objective-C:

#import <Smooch/Smooch.h>

Swift:

import Smooch

Add Required Keys in your app’s Info.plist

The Smooch SDK may need to ask users permission to use certain features. Depending on the feature, you must provide a description in your app’s Info.plist to explain why access is required. These descriptions will be displayed the moment we prompt the user for permission.

Images

The Smooch SDK allows users to send images to you. To support this feature, you need to provide a description for the following keys:

  • NSCameraUsageDescription: describes the reason your app access the camera (ex: Camera permission is required to send images to ${PRODUCT_NAME}). More information available here.
  • NSPhotoLibraryUsageDescription: describes the reason your app needs read access to the photo library (ex: Photo library permission is required to send images to ${PRODUCT_NAME}). More information available here.
  • NSPhotoLibraryAddUsageDescription: describes the reason your app needs write access to the photo library (ex: Photo library permission is required to send images to ${PRODUCT_NAME}). More information available here.

Location

The Smooch SDK also allows users to send their current location. To support this feature, you must provide a description for any of the following keys depending on your app’s use of location services. Smooch will ask the user for the location depending on the key you provide:

  • NSLocationWhenInUseUsageDescription: describes the reason for your app to access the user’s location information while your app is in use (ex: Location services is required to send your current location to ${PRODUCT_NAME}). This permission is recommended if your app does not use location services and Smooch will default to it if both keys are included. More information available here.
  • NSLocationAlwaysUsageDescription: describes the reason for your app to access the user’s location information at all times (ex: Location services is required to send your current location to ${PRODUCT_NAME}). More information available here.

Initialize Smooch in your app

After following the steps above, your app is setup for working with the Smooch SDK. Before your code can invoke its functionality, you’ll have to initialize the library using your app id. You can find it by logging into Smooch and copying it from the settings page as shown below.

App Id on Overview Page

To initialize Smooch, add the following line of code to your applicationDidFinishLaunchingWithOptions: method:

Objective-C:
[Smooch initWithSettings:[SKTSettings settingsWithAppId:@"YOUR_APP_ID"] completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
    // Your code after init is complete
}];
Swift:
Smooch.initWith(SKTSettings(appId: "YOUR_APP_ID")) { (error: Error?, userInfo: [AnyHashable : Any]?) in
    // Your code after init is complete
}

Make sure to replace YOUR_APP_ID with your app id.

Displaying the Smooch User Interface

Once you’ve initialized Smooch, you’re ready to try it out.

Find a suitable place in your app’s interface to invoke Smooch and use the code below to display the Smooch user interface. You can bring up Smooch whenever you think that your user will need access to help or a communication channel to contact you.

Objective-C:
[Smooch show];
Swift:
Smooch.show()

Region configuration

The iOS SDK is supported in the following regions:

Region Region identifier
United States Leave unspecified
European Union eu-1

To target the EU region for example, set the region identifier in the SKTSettings object:

Objective-C:
SKTSettings settings = [SKTSettings settingsWithAppId:@"YOUR_APP_ID"];
settings.region = @"eu-1";
[Smooch initWithSettings:settings completionHandler:^(NSError * _Nullable error, NSDictionary * _Nullable userInfo) {
    // Your code after init is complete
}];
Swift:
let settings = SKTSettings(appId: "YOUR_APP_ID")
settings.region = "eu-1"
Smooch.initWith(settings) { (error: Error?, userInfo: [AnyHashable : Any]?) in
    // Your code after init is complete
}

Login with userId and JWT

After Smooch has initialized, your user can start sending messages right away. These messages will show up on the business side under a new Smooch appUser. However, these appUsers will not yet be associated to any user record you might have in an existing user directory.

If your application has a login flow, or if a user needs to access the same conversation from multiple devices, this is where the login method comes into play. You can associate Smooch users with your own user directory by assigning them a userId. You will then issue each user a jwt credential during the login flow. You can read more about this in the Authenticating users section.

Updating Smooch

CocoaPods

To update via cocoapods, simply execute this:

$ pod update

Carthage

To update Carthage dependencies, you can simply run:

$ carthage update

Configuring push notifications

Push notifications are a great, unobtrusive way to let your users know that a reply to their message has arrived.

Step 1. Enable Push Notifications and Generate the .p12 Certificate

  1. Log into the Identifiers section of the Apple Developer Member Center, and select your app. You can get there by visiting this link.

  2. Click ‘Edit’, enable ‘Push Notifications’, and then click ‘Create Certificate…“.

  3. Follow the instructions to generate a certificate signing request using Keychain Access.

  4. Once the certificate is ready, download it to your computer and double-click it to open it in Keychain Access.

  5. Right click on the certificate you created, and select ‘Export “Apple Development IOS Push Services:…”‘.

  6. Save the .p12 file to your computer.

Step 2. Upload the .p12 file to Smooch

  1. Go to the iOS integration page.

  2. Click on the Connect or Configure button.

  3. Upload the .p12 file.

Step 3. Re-create your Provisioning Profile

Now that you have enabled push notifications for your app, you MUST re-create your Provisioning Profile. You can not use the one you’ve used in the past.

  1. Go to Provisioning Profiles in the Apple Developer Member Center by clicking here.

  2. Click the ’+’ button to add a new provisioning profile and follow the on-screen instructions.

  3. Notice that once you created the new provisioning profile, it shows that “Push Notifications” is an enabled service. Download the new profile.

  4. Double click it to install it. It should now be selectable in Xcode for your app.

  5. Build your app.

Step 4. Test it out!

  1. Kill and restart your app.

  2. Launch Smooch.

  3. Send a message. Important! You must resend a message after uploading the p12 file.

  4. Reply to the message from the Business System integration of your choice

You’ll receive a notification if you’re in the app, or outside the app!

Step 5. Repeat for Production mode

Take note that there are “Development” and “Production” certificates and profiles. Make sure that you upload the “Production” .p12 file to Smooch when you’re ready to release your build through ad-hoc, enterprise or app store distribution.

Rich Notifications

On iOS 10 and above, it’s now possible to display a custom user interface when the user interacts with your application’s remote and local notifications. Smooch provides the ability to display the user’s conversation history when viewing a notification:

iOS Rich Notifications

To enable this behaviour, sample code and configuration instructions can be found in the smooch-ios-rich-notifications repository.

Message type support

The iOS SDK supports a wide variety of message types as seen in the channel capabilities grid.

Carousels are rendered natively with full functionality in the iOS SDK. See our API documentation for instructions on how to send one.

Carousel iOS

Carousels support up to a maximum of 10 message items. Each message item must include a title and at least one supported action. Optionally, an image and description can be included as well. Images can be displayed in two different aspect ratios, “square” and “horizontal” (see screenshots below). For more information, see our API documentation.

Carousel items with “horizontal” images (default):

Carousel iOS horizontal

Carousel items with “square” images:

Carousel iOS square

Supported actions

The iOS SDK supports the following action types in a carousel message item:

  • Link
  • Postback
  • Buy
  • Webview

List message fallback

If the iOS SDK receives a list type message, it will display a carousel instead.

Files

The iOS SDK has full native support for sending and receiving files. See our API documentation for instructions on how to send one.

Localization

Every string you see in Smooch can be customized and localized. Smooch provides a few languages out of the box, but adding new languages is easy to do. When localizing strings, Smooch looks for SmoochLocalizable.strings in your app bundle first then in the Smooch bundle, enabling you to customize any strings and add support for other languages.

Enabling Localization in your app

For Smooch to display a language other than English, your app needs to first enable support for that language. You can enable a second language in your Xcode project settings:

Enable Localization

Once you have this, Smooch will display itself in the device language for the supported language.

These languages are included with the iOS SDK: Arabic, English, Finnish, French, German, Italian, Japanese, Korean, Mandarin Chinese (traditional and simplified), Persian, Portuguese (Brazil and Portugal), Russian, Slovenian, Spanish, and Swedish.

See how to support more languages in Adding more languages.

Adding more languages

To enable other languages beside the provided ones, first copy the english SmoochLocalizable.strings file from the Smooch bundle to the corresponding .lproj folder for that language. Then, translate the values to match that language.

Customization

Strings customization

Smooch lets you customize any strings it displays via Apple’s localization mechanism. To override one or more strings, add an empty string file named SmoochLocalizable.strings in your Xcode project and specify new values for the keys you would like to override. For example, to change the “Messages” header and the “Done” button, create a file with these contents:

"Messages" = "My Messages";

"Done" = "I'm Done";

The full set of keys is listed below. To enable string customization across languages, make sure you “Localize” your SmoochLocalizable.strings file in Xcode.

Localize SmoochLocalizable.strings

/* Nav bar button, action sheet cancel button */
"Cancel" = "...";

/* Conversation title */
"Messages" = "...";

/* Conversation header. Uses CFBundleDisplayName */
"This is the start of your conversation with the %@ team. We'll stay in touch to help you get the most out of your app.\nFeel free to leave us a message about anything that’s on your mind. We’ll get back to your questions, suggestions or anything else as soon as we can." = "...";

/* Conversation header when there are previous messages */
"Show more..." = "...";

/* Conversation header when fetching previous messages */
"Retrieving history..." = "...";

/* Error message shown in conversation view */
"No Internet connection" = "...";

/* Error message shown in conversation view */
"Could not connect to server" = "...";

/* Error message shown in conversation view */
"An error occurred while processing your action. Please try again." = "...";

/* Error message shown in conversation view */
"Reconnecting..." = "...";

/* Error message shown in conversation view */
"Invalid file" = "...";

/* Error message shown in conversation view */
"A virus was detected in your file and it has been rejected" = "...";

/* Error message shown in conversation view. Parameter represents the max file size formatted by NSByteCountFormatter */
"Max file size limit exceeded %@." = "...";

/* Fallback used by the in app notification when no message author name is found */
"%@ Team" = "...";

/* Conversation send button */
"Send" = "...";

/* Conversation text input place holder */
"Type a message..." = "...";

/* Conversation nav bar left button */
"Done" = "...";

/* Failure text for chat messages that fail to upload */
"Message not delivered. Tap to retry." = "...";

/* Status text for chat messages */
"Sending..." = "...";

/* Status text for sent chat messages */
"Delivered" = "...";

/* Status text for chat messages seen by the appMaker */
"Seen" = "...";

/* Timestamp text for recent messages */
"Just now" = "...";

/* Timestamp text for messages in the last hour */
"%.0fm ago" = "...";

/* Timestamp text for messages in the last day */
"%.0fh ago" = "...";

/* Timestamp text for messages in the last week */
"%.0fd ago" = "...";

/* Action sheet button label */
"Take Photo" = "...";

/* Action sheet button label */
"Photo & Video Library" = "...";

/* Action sheet button label */
"Use Last Photo Taken" = "...";

/* Action sheet button label */
"Share Location" = "...";

/* Photo confirmation alert title */
"Confirm Photo" = "...";

/* Action sheet button label */
"Resend" = "...";

/* Action sheet button label */
"View Image" = "...";

/* Error displayed in message bubble if image failed to download */
"Tap to reload image" = "...";

/* Error displayed as message if location sending fails */
"Could not send location" = "...";

/* Error title when user selects "use latest photo", but no photos exist */
"No Photos Found" = "...";

/* Error description when user selects "use latest photo", but no photos exist */
"Your photo library seems to be empty." = "...";

/* Error title when user attempts to upload a photo but Photos access is denied */
"Can't Access Photos" = "...";

/* Error description when user attempts to upload a photo but Photos access is denied */
"Make sure to allow photos access for this app in your privacy settings." = "...";

/* Error title when user attempts to take a photo but camera access is denied */
"Can't Access Camera" = "...";

/* Error description when user attempts to take a photo but camera access is denied */
"Make sure to allow camera access for this app in your privacy settings." = "...";

/* Generic error title when user attempts to upload an image and it fails for an unknown reason */
"Can't Retrieve Photo" = "...";

/* Generic error description when user attempts to upload an image and it fails for an unknown reason */
"Please try again or select a new photo." = "...";

/* Error title when user attempts to send the current location but location access is denied */
"Can't Access Location" = "...";

/* Error description when user attempts to send the current location but location access is denied */
"Make sure to allow location access for this app in your privacy settings." = "...";

/* UIAlertView button title to link to Settings app */
"Settings" = "...";

/* UIAlertView button title to dismiss */
"Dismiss" = "...";

/* Title for payment button */
"Pay Now" = "...";

/* Title for message action when payment completed */
"Payment Completed" = "...";

/*
 Instructions for entering credit card info. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
*/
"Enter your credit card to send $%@ %@ securely to %@" = "...";

/* Error text when payment fails */
"An error occurred while processing the card. Please try again or use a different card." = "...";

/* Button label for saved credit card view */
"Change Credit Card" = "...";

/*
 Information label for saved credit card view. Parameters are as follows:
 1. Amount (e.g. 50.45)
 2. Currency (e.g. USD)
 3. App name (Uses CFBundleDisplayName)
 */
"You're about to send $%@ %@ securely to %@" = "...";

/* Title for user notification action */
"Reply" = "...";

/* Date format used for message grouping headers on the conversation screen */
"MMMM d, h:mm a" = "MMMM d, h:mm a";

/* Date format used for message timestamps on the conversation screen */
"hh:mm a" = "hh:mm a";

/* Error message when the content of a webview fails to load */
"Failed to open the page" = "...";

Styling the Conversation Interface

The style of the conversation user interface can be controlled through two techniques:

  • Using the UIAppearance proxy of UINavigationBar to style the navigation bar’s color and appearance.
  • The SKTSettings class provides access to the status bar and the color of the message bubbles.

Suppose you wanted the conversation UI to have a black navigation bar and red message bubbles. First, you’d use UINavigationBar’s appearance proxy to set up the navigation bar. Then, you’d use SKTSettings to finish styling the UI:

Objective-C:

SKTSettings* settings = [SKTSettings settingsWithAppId:@"YOUR_APP_ID"];
settings.conversationAccentColor = [UIColor redColor];
settings.conversationStatusBarStyle = UIStatusBarStyleLightContent;

[[UINavigationBar appearance] setBarTintColor:[UIColor blackColor]];
[[UINavigationBar appearance] setTintColor:[UIColor redColor]];
[[UINavigationBar appearance] setTitleTextAttributes:@{ NSForegroundColorAttributeName : [UIColor redColor] }];

Swift:

var settings = SKTSettings(appId: "YOUR_APP_ID")
settings.conversationAccentColor = UIColor.redColor();
settings.conversationStatusBarStyle = UIStatusBarStyle.LightContent;

UINavigationBar.appearance().barTintColor = UIColor.blackColor()
UINavigationBar.appearance().tintColor = UIColor.redColor()
UINavigationBar.appearance().titleTextAttributes = [ NSForegroundColorAttributeName : UIColor.redColor()]

The iOS SDK features a tappable menu icon that allows the user to send various message types. The types displayed in this menu can be customized, or the menu can be hidden altogether.

If you want to control this menu, override the allowedMenuItems array in SKTSettings to add the values of your choice:

SKTSettings *settings = [SKTSettings settingsWithAppId:@"your_app_id"];
settings.allowedMenuItems = @[
                              SKTMenuItemCamera,
                              SKTMenuItemGallery,
                              SKTMenuItemDocument,
                              SKTMenuItemLocation
                              ];

Menu Options

To hide the menu completely, set the allowedMenuItems array to nil:

SKTSettings *settings = [SKTSettings settingsWithAppId:@"your_app_id"];
settings.allowedMenuItems = nil;

Menu Options

Implementing your own User Interface

If you need more customization options than the ones supported natively by Smooch, you can implement a complete custom UI by leveraging events and APIs exposed by the SDK, which will continue to facilitate the connection with the Smooch platform.

Our sample custom UI project covers the first steps you need to follow to get started.