iOS SDK integration

Introduction

This topic describes how to integrate the Mobile Feedback iOS SDK.

• Use CocoaPods to manage project dependencies.

• The latest version of the SDK supports iOS Deployment Target 7.0 and later.

• The Mobile Feedback SDK supports bitcode. Bitcode is displayed and enabled by default only in Xcode 7 and later.

• The Mobile Feedback SDK and its dependency libraries use the HTTPS protocol for encrypted transmission.

Preparations

• A project and an application have been created. For more information, see Create a project and an application.

Step 1: Integrate the SDK into your application

You can add the SDK to your application by importing dependencies with CocoaPods or by manually integrating local dependencies.

1. Import dependencies using CocoaPods

1.1 Specify the Master and Alibaba Cloud repositories

The Mobile Feedback iOS SDK and other EMAS iOS SDKs are published to the official Alibaba Cloud EMAS GitHub repository. You must include this repository address in your Podfile.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/aliyun/aliyun-specs.git'

1.2 Add dependencies

Add the following dependency to the target that requires the Mobile Feedback iOS SDK.

target 'yourProjetName' do
  # Comment the next line if you don't want to use dynamic frameworks
  use_frameworks!
  pod 'AlicloudFeedback', 'x.x.x'
end

1.3 Install dependencies

In your terminal, navigate to the directory that contains the Podfile and run the following command to install the dependencies.

pod install --repo-update

2. Manually integrate local dependencies

2.1 Download dependency files

Select and download the iOS version of Mobile Feedback from the EMAS SDK List. Unzip the package to obtain multiple framework files, as shown in the following figures.

2.2 Add the framework files to the project

In Finder, select the files, drag them to the target that requires the Mobile Feedback iOS SDK, and select Copy items if needed in the pop-up dialog box.

If you encounter a UTDID conflict, see Solutions to UTDID conflicts in Alibaba Cloud product SDKs.

2.3 Add system library dependencies

In your project, navigate to Build Phases > Link Binary With Libraries and add the following library dependencies.

libz.tbd
libresolv.tbd
libsqlite3.tbd
CoreMotion.framework
CoreTelephony.framework
SystemConfiguration.framework

The final result is shown in the following figure.

2.4 Configure Objective-C

When you integrate the SDK on iOS, you must configure the -ObjC property. Go to TARGETS > Build Settings > Linking > Other Linker Flags and add the -ObjC property, as shown in the following figure.

Step 2: Set privacy permissions

iOS 10 and later have stricter privacy permission requirements. You must add privacy descriptions to prevent your application from crashing or failing the App Store review. Set the permissions as follows:

Add the following fields to the info.plist file:

<key>NSCameraUsageDescription</key>
<string>Use camera</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Use photo library</string>
<key>NSMicrophoneUsageDescription</key>
<string>Use microphone</string>

The configuration is shown in the following figure:

Step 3: Use the SDK

1. Initialize the SDK

In the code file where you need to use Mobile Feedback, import the header files.

#import <YWFeedbackFMWK/YWFeedbackKit.h> 
#import <YWFeedbackFMWK/YWFeedbackViewController.h>

Call the initialization method. You can obtain the AppKey and AppSecret from the Application Management page in the console.

/// @brief Initialization method
/// @params anAppKey The AppKey
/// @params anAppSecret The AppSecret
/// @return A YWFeedbackKit instance
- (instancetype)initWithAppKey:(NSString *)anAppKey appSecret:(NSString *)anAppSecret;

YWFeedbackKit *feedbackKit = [[YWFeedbackKit alloc] initWithAppKey:kAppKey appSecret:kAppSecret];

2. Open the feedback interface

• Call the following API of the YWFeedbackKit instance to create the feedback interface:

/// @brief The callback block to create the feedback interface.
/// @params viewController The feedback interface.
/// @return An error is returned if the call fails.
typedef void (^YWMakeFeedbackViewControllerCompletionBlock) (YWFeedbackViewController * viewController, NSError *error);
/// @brief Creates the feedback interface. By default, error messages are not displayed in a pop-up window.
- (void)makeFeedbackViewControllerWithCompletionBlock:(YWMakeFeedbackViewControllerCompletionBlock)completionBlock;

• After the interface is created, a YWFeedbackViewController is returned. You can display it using methods such as Present, based on your application's structure.

• If you do not want to use the default system alert for error messages or if you want to localize the error messages, you can customize the notification method. To customize the method, implement this block. For more information, see the Demo.

/// @brief The callback block for the feedback interface to throw an error. If this property is not set, the default alert is used to display error messages.
/// @params viewController The feedback interface.
/// @return The error that occurred.
@property (nonatomic, copy) void (^YWFeedbackViewControllerErrorBlock) (YWFeedbackViewController *viewController, NSError *error);

3. Close the user feedback interface

After you open the feedback interface, a YWFeedbackViewController is returned. Set the closeBlock property. When a user closes the feedback interface, this block is called to dismiss or pop the view controller. For more information, see the Demo.

[viewController setCloseBlock:^(UIViewController *aParentController){
    // Dismiss or pop, and perform some related settings.
    [aParentController dismissViewControllerAnimated:YES completion:nil];
}];

4. Get the number of unread feedback messages

Call the following API to obtain the number of unread messages:

/// @brief The callback block for the number of unread feedback messages.
/// @params unreadCount The number of unread messages.
/// @return An error is returned if the call fails.
typedef void (^YWGetUnreadCountCompletionBlock) (NSInteger unreadCount, NSError *error);
/// @brief Requests the number of unread feedback messages.
- (void)getUnreadCountWithCompletionBlock:(YWGetUnreadCountCompletionBlock)completionBlock;

If the call is successful, the number of unread feedback messages is returned. If there are unread messages, you can add a badge with the unread count to the feedback entry point to notify the user.

5. Set extended feedback information and user nicknames (optional)

After you initialize the Mobile Feedback SDK, you can set extended feedback data as needed:

/// Extended feedback data. Set any fields as needed before creating the feedback interface. This data can be viewed in the extended information section of the console.
@property (nonatomic, strong, readwrite) NSDictionary *extInfo;

self.feedbackKit.extInfo = @{***:***};

After a user nickname is set, the nickname is included in the feedback message and displayed in the feedback session in the console.

This feature is available in v3.3.5 and later.

/**
 Sets the feedback username. Set this after the SDK is initialized and before the feedback interface is created.
 (This username can be viewed in the feedback session in the Mobile Feedback console to identify the user.)
 @param nickName The feedback username.
 */
- (void)setUserNick:(NSString *)nickName;

[self.feedbackKit setNickName:@"***"];

6. Customize the UI

Versions 3.1.0 and later provide APIs that you can use to customize the UI. You can customize the navigation bar font and the back button icon.

The APIs to modify the navigation bar font are as follows:

//YWFeedbackKit.h 

/// @brief If not set, the default is `[UIFont boldSystemFontOfSize:13]`
@property (nonatomic, strong) UIFont *defaultCloseButtonTitleFont;

/// @brief If not set, the default is `[UIFont boldSystemFontOfSize:13]`
@property (nonatomic, strong) UIFont *defaultRightBarButtonItemTitleFont;

The method to modify the navigation bar's back button icon is as follows:

If you integrated the SDK manually, you can directly modify the image in YWFeedbackBundle.bundle. If you integrated the SDK using CocoaPods, you must rename YWFeedbackBundle.bundle to Customized.YWFeedbackBundle.bundle, modify the image inside Customized.YWFeedbackBundle.bundle, and then drag it into your project.

SDK Demo

For a sample project that shows how to integrate the Mobile Feedback iOS SDK, see the Demo

Common error codes