Getting Started iOS

You're 3 steps away from adding great in-app support to your Unity game.

Guide to integrating the Unity plugin for the Helpshift SDK which you can call from your C# and Javascript game scripts.

Download Helpshift Unity SDK for iOS

Download SDK v2.8.1

The .unitypackage file contains:

Helpshift/
C# scripts which expose the Helpshift API to the Unity scripts
Plugins/Android/helpshift
Folder containing the Android library project for Helpshift.

Add Helpshift to your Unity project

Import the helpshift-plugin-unity-version.unitypackage unitypackage file into your Unity game.

If you are using Xcode 7 or above, please deselect the libHelpshift-xcode6 file during importing of the asset package.

After importing the Helpshift unitypackage file, you may see errors like: Assets/Helpshift/Plugins/iOS/HsUIResourceBundle.bundle/*.png: File could not be read. These errors are shown by Unity because Apple converts traditional PNG images to a optimised CgBI format using a proprietary version of the public domain pngcrush tool making the file different from the PNG standards. This optimisation reduces the size of PNG image by almost half, making our asset folder very small in size. Unity is not able to read these images hence throws error like File could not be read.

Please ignore the import errors as they will be seen only once while importing and will not cause any run time issues.

If you are upgrading the unity SDK to the newer one and if you want to save the old config, you will have to deselect the HelpshiftConfig.assets file during importing of the assets package.

If you are using unity 5.4.x and above, please select iOS as target for HsUIResourcesBundle and HsLocalization bundle in the file inspector. For more information

If you are using unity 4.7.2 for xcode6 lib, you will have to manually integrate the plugin for iOS. For this, please drag iOS folder from ../Assets/Helpshift/Plugins/ and drop it in the project.

If you are using unity 5.5.x, the call back for remote notifications will be recieved in the application(_:didReceiveRemoteNotification:fetchCompletionHandler:) method.

Using Helpshift with Xcode 6

If you want to run your Unity iOS project using Xcode 6, please follow the below instructions.

  1. Deselect the libHelpshift.a file when importing the Helpshift unity package.
  2. Select the libHelpshift-xcode6.a file.
  3. Once import is complete, rename the libHelpshift-xcode6.a to libHelpshift.a.
  4. Open the Helpshift/Plugins/iOS/HsUnityAppController.mm file and remove the nonnull and nullable compiler directives which are unavailable in the Xcode 6 compiler.
  5. Also, before starting the build, remove the below line from the HSPostprocessBuildPlayer which can be found in the Helpshift/Editor folder.

    project.add_file_if_doesnt_exist('System/Library/Frameworks/CoreSpotlight.framework', tree='SDKROOT', parent=framework_group)
    

Using Helpshift with Bitcode support

If you want to compile your Unity iOS project with bitcode enabled, please follow the below instructions.

  1. Deselect the libHelpshift.a file when importing the Helpshift unity package.
  2. Select the libHelpshift-bitcode.a file.
  3. Once import is complete, rename the libHelpshift-bitcode.a to libHelpshift.a.

Issues with iOS 8 and CoreSpotlight

If you are facing crash issues with the new Unity plugin on iOS 8 devices due to the missing CoreSpotlight framework, please mark the framework as Optional by doing the following.

Open Helpshift/Editor/HSPostprocessBuildPlayerfile and replace the line

    project.add_file_if_doesnt_exist('System/Library/Frameworks/CoreSpotlight.framework', tree='SDKROOT', parent=framework_group)

with

    project.add_file_if_doesnt_exist('System/Library/Frameworks/CoreSpotlight.framework', tree='SDKROOT', parent=framework_group, weak=True)

Initializing Helpshift in your app

From Unity version 2.3.0, all variants of install calls of HelpshiftSDK class in CSharp script are deprecated and it is mandatory to install Helpshift via ObjC. The install call for iOS should happen via HsUnityAppController.mm file. Please follow the installation step as explained below in Install Helpshift via ObjC section.

Helpshift's namespace

To use Helpshift's APIs, please import the Helpshift's namespace for iOS like below

using Helpshift;

Helpshift can be used to support all the apps you publish. We uniquely identify each app that is registered with Helpshift using the combination of:

API Key
This is your unique developer API Key
Domain Name
This is your helpshift instance domain name without any http: or forward slashes
App ID
This is the unique ID assigned to your app

To get the API Key, Domain Name and the App ID, navigate to Settings>SDK (for Developers) in your agent dashboard and scroll down to "Initializing Helpshift" section. show me

Select your App from the dropdown and copy the three tokens to be passed when initializing Helpshift.

Install Helpshift via ObjC

From Unity version 2.3.0 it is mandatory to integrate HsUnityAppcontroller.mm file into your Xcode project. This file contains a helper class HelpshiftUnityInstaller that provides a way to make install call by reading Api Key, Domain Name, App ID and other install configurations directly from GUI inspector.

You can set the required keys and install configurations in the GUI configuration editor, override application:didFinishLaunchingWithOptions in HsUnityAppcontroller and call the installDefault function as shown below.

#import "HelpshiftCore.h"
#import "HelpshiftSupport.h"
#import "HelpshiftAll.h"
#import "Helpshift.h"
.
.
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    BOOL defaultConfigInstall = [HelpshiftUnityInstaller installDefault];
    if (defaultConfigInstall == NO) {
        // Default config is not set correctly. If you intend to use default configuration, please check api key, app id and
        // domain name are set correctly in the default config.
    }

    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

Alternatively, if you don't use GUI configuration editor, you can specify Api Key, Domain Name, App ID and other install configurations in the Objective-C code. To do this you need to override application:didFinishLaunchingWithOptions in HsUnityAppcontroller as shown below.

#import "HelpshiftCore.h"
#import "HelpshiftSupport.h"
#import "HelpshiftAll.h"
#import "Helpshift.h"
.
.
- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Set install configurations
    NSDictionary *installConfig = @{@"unityGameObject":@"background_image", @"enableInAppNotification":@"yes"};

    // Make install call
    [HelpshiftCore initializeWithProvider:[HelpshiftAll sharedInstance]];
    [HelpshiftCore installForApiKey:@"<your_api_key>" domainName:@"<your_domain_name>.helpshift.com" appID:@"<your_app_id>" withOptions:installConfig];

    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

In order to receive callbacks from Helpshift, you must pass a valid game object for unityGameObject key in the install configuration.

Install Helpshift via CSharp

Installing Helpshift in CSharp scripts is deprecated.

If you have not integrated the HsUnityAppController in your application, you can use the CSharp API for installing the Helpshift SDK.

using Helpshift;
.
.
.
private HelpshiftSdk help;

help = HelpshiftSdk.getInstance();
help.install("<API_KEY>", "<DOMAIN_NAME>", "<APP_ID>");

Required UIApplicationDelegate functions

For its internal functioning, Helpshift needs to override below mentioned functions of UIApplicationDelegate protocol. The class HsUnityAppController overrides these functions as required. These methods are called by external iOS services and expect the application to call completionHandler(). By default, UnityAppController class does not implement these functions. If you require any of these functions of other features of your app, you must override these functions, comment out or remove default completionHandler() call and provide your own implementation as per your requirements.

- (void) application:(UIApplication *)application handleEventsForBackgroundURLSession:(NSString *)identifier completionHandler:(void (^)())completionHandler {
    if (![HelpshiftCore handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler]) {
        // Handle events for background url session. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleEventsForBackgroundURLSession:identifier completionHandler:completionHandler];
        completionHandler();
    }
}

- (void) application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forRemoteNotification:(NSDictionary *)userInfo completionHandler:(void (^)())completionHandler {

    if (![HelpshiftCore handleInteractiveRemoteNotification:userInfo forAction:identifier completionHandler:completionHandler]) {

        // Handle action with identifier. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleActionWithIdentifier:identifier forRemoteNotification:userInfo completionHandler:completionHandler];
        completionHandler();
    }
}

- (void) application:(UIApplication *)application handleActionWithIdentifier:(NSString *)identifier forLocalNotification:(UILocalNotification *)notification completionHandler:(void (^)())completionHandler {
    if(![HelpshiftCore handleInteractiveLocalNotification:notification forAction:identifier completionHandler:completionHandler]) {
        // Handle action with identifier. Once you have implemented this function in UnityAppController, uncomment
        // the code below and comment the call completionHandler();

        //[super application:application handleActionWithIdentifier:identifier forLocalNotification:notification completionHandler:completionHandler];
        completionHandler();
    }
}

Start using Helpshift

Helpshift is now integrated in your app. You should now use the support APIs to present FAQ or conversation screens inside your app.

Run your app, and try starting a test conversation using the showConversation API call. Then goto your Helpshift agent dashboard and reply to experience the in-app messaging.

Sample usage for FAQs and conversation APIs:

public class MyGameControl : MonoBehaviour
{
    private HelpshiftSdk help;

    void Start () {
        this.help = HelpshiftSdk.getInstance();
    }

    void onGUI () {
        ...
        Dictionary<string, object> configMap = new Dictionary<string, object>();

        // Presenting FAQs to your customers
        if (MenuButton (helpButton))
        {
            help.showFAQs(configMap);
        }

        // Starting a conversation with your customers
        if (MenuButton (contactButton))
        {
            help.showConversation(configMap);
        }
    }
}

Since the Helpshift plugin is meant for mobile devices only, you should put all Helpshift calls inside checks to make sure they are only called when running on a device. / #run-on-device /

Configuring the Helpshift SDK

We have now added a Helpshift Configurator for Unity which can help app developers configure the various flags which are generally passed via the config option in all Helpshift APIs. Once you import the helpshift unitypackage, you will see a Helpshift menu in the Unity Editor

Everytime you update the config via the GUI inspector, please make sure to click on Save Config before starting the next build.

If you use default install call, please make sure the api key, app Id and domain name are set correctly in the config editor otherwise SDK throws an exception.

Helpshift Menu

From the Helpshift menu, you can launch the Configurator by click on Edit Config. This will open up a GUI inspector which will contain all the available flag options.

GUI Inspector

Install keys

You can supply the ApiKey, DomainName and AppId through the Configurator. ApiKeys and DomainName remain the same for Android and iOS apps. AppIds are different for different platforms If you want to use the values supplied through the configurator, please use [HelpshiftUnityInstaller installDefault] as explained above in Install Helpshift via ObjC or you may use HelpshiftSdk.install() call and do not pass in any argument. Both of these methods pick instal time configurations from the Configurator.

Install configurations

There are some configurations which are meant to be passed via the install call which configure the instance of Helpshift running in the application.

  1. unityGameObject Name of the Game object which will respond to Helpshift's callbacks.
  2. enableInAppNotifications Whether you want to enable in-app notifications for updates to on-going conversations.

SDK configurations

The Helpshift SDK accepts multiple flags which govern the behaviour of the individual Helpshift screens. If you want to use the SDK configurations via the Configurator, please use the HelpshiftSdk APIs without any arguments, or use the *WithMeta variety if you want to pass in some custom meta-data.

For example :

using Helpshift;
.
.
.
.
private HelpshiftSdk help;
void foo () {
  help = HelpshiftSdk.getInstance();
  // Show FAQs with config from GUI and no meta-data
  help.showFAQs();
  // Show FAQs with config from GUI and meta-data
  Dictionary <string, object> meta = new Dictionary <string, object>();
  ...
  ...
  help.showFAQsWithMeta(meta);
}

Next up

Helpshift APIs

Discover ways to do customer support via Helpshift.

Notifications

Configure Push and In-app notifications.

Tracking

Track events and user actions. Attach custom metadata to every conversation.

Reviews & Feedback

Asking for reviews and feedback.