Getting Started iOS

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

Requirements

• Unity 2018.1.0 and above.
• Xcode 12.0 and above.
• Supported iOS versions:
  • iOS 15, 14, 13, 12, 11, and 10

Download HelpshiftX Unity SDK for iOS

Download SDK

HelpshiftX SDK .zip folder includes:

Add Helpshift to your Unity project

• Unzip the HelpshiftX Unity SDK package.
• HelpshiftX Unity SDK appears as a standard .unitypackage which you can import through the Unity package import procedure.
• Following are the steps to import the helpshiftX-plugin-unity-version.unitypackage into your Unity game:
  1. In the Open Unity project, navigate to Assets drop-down menu and select the Import Package > Custom Package
  2. From the unzipped SDK, select helpshiftX-plugin-unity-version.unitypackage file to import the Helpshift SDK.
  3. Click Import.

Info.plist changes - Addition of usage description strings

“User Attachments” feature is enabled for SDK which allows User to upload an attachment. The attachments can be picked from the Photo Library or can be captured directly using the camera. The options for these sources look like:

To use the camera and photo library, Apple requires the app to have Usage Description strings in the Info.plist while. Failing to add these strings might result in app rejection. The following strings are needed for the attachment feature:

Initializing Helpshift in your app

Helpshift's namespace

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

using Helpshift;

Helpshift uniquely identifies each registered App with a combination of 2 tokens:

show me

Initialize Helpshift by calling the method install(platformId, domain) API

using Helpshift;
.
.
.
public class MyGameControl : MonoBehaviour
{
    private HelpshiftSdk help;
    ...

    void Awake() {
        help = HelpshiftSdk.GetInstance();
        var configMap = new Dictionary<string, object>();
        help.Install(platformId, domainName, configMap);
    }
    ...
}

Install Helpshift via ObjC

If you intend to initialize the SDK from Xcode using Objective C, You can specify Domain Name, Platform 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 <HelpshiftX/HelpshiftX.h>
#import "HelpshiftX-Unity.h"

- (BOOL) application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Set install configurations
    NSDictionary *installConfig = @{@"enableInAppNotification":@YES};

    // Make install call
    [Helpshift installWithPlatformId:@"<your_platform_id>" domain:@"<your_domain_name>" config:installConfig];
    return [super application:application didFinishLaunchingWithOptions:launchOptions];
}

Integrating Feedback Section

You can use the API call ShowConversation(configMap) to allow a user to directly send feedback. Once, a user starts a new conversation, this API call will show the conversation screen. The conversation will continue until it is resolved or rejected by the agent.

To configure the conversation screen, you can pass various config options in a Dictionary<string, object>. It is advised to add Initial User Message in the configMap. Example :

using Helpshift;

private HelpshiftSdk help;

// install call here
void Awake(){
    help = HelpshiftSdk.GetInstance();
    help.Install(platformId, domainName, null);
}

// configuration map
Dictionary<string, object> configMap = new Dictionary<string, object>
        {
            { "tags", new String[] { "foo", "bar" } },
            { "initialUserMessage", "Give Feedback"}
        };

// open the support chat screen
help.ShowConversation(configMap);

Integrating FAQs

You can use the API call ShowFAQs(configMap) to provide a way for the user to invoke the purpose-built help/FAQs section in your app. This is the easiest approach to enable help in your app as it bundles all the capabilities of the Helpshift SDK in a simple and intuitive interface. You can wire this API call to a "Help" or "FAQs" action in your app.

To configure the FAQs screen, you can pass various config options in a Dictionary<string, object>. It is advised to add Initial User Message in the configMap.

Example :

using Helpshift;

private HelpshiftSdk help;

// install call here
void Awake(){
    help = HelpshiftSdk.GetInstance();
    help.Install(platformId, domainName, null);
}

// configuration map
Dictionary<string, object> configMap = new Dictionary<string, object>
        {
            { "tags", new String[] { "foo", "bar" } },
            { "initialUserMessage", "Give Feedback"}
        };

// open the FAQs screen
help.ShowFAQs(configMap);

Adding Custom Metadata to Feedback

If you want to add Custom Metadata at the time of Issue creation, follow the steps.

1. Initialize a top-level custom metadata Map
2. Define your custom metadata Map
3. Add the key-value pairs in that custom metadata Map
4. Add the custom metadata Map to the top-level Map
5. Pass the Map to configMap with key "customMetadata" to any of the SDK APIs (like ShowConversation(configMap)).

Dictionary<string, string> customMetadataMap = new Dictionary<string, string>();
    customMetadataMap.Add("Level", "9");
    customMetadataMap.Add("Spend", "46.55 USD");
    customMetadataMap.Add("Device Timestamp", DateTime.UtcNow.ToLongTimeString());

    Map<String, Object> config = new HashMap<>();
    // other configs...
    //.. 
    config.put("customMetadata", customMetadataMap);

    Helpshift.showConversation(MainActivity.this, config);

Dictionary<string, string> customMetadataMap = new Dictionary<string, string>();

    Map<String, Object> config = new HashMap<>();
    // other configs...
    //..
    config.put("customMetadata", customMetadataMap);

    Helpshift.showConversation(MainActivity.this, config);

Set Custom Issue Fields

If you want to set Custom Issue Fields at the time of Issue creation, follow the steps.

1. Initialise a top level custom issue fields' Dictionary
2. Define your custom issue field Dictionary
3. Add the "type" and "value" for that custom issue field
4. Add the custom issue field map to top level map (with key as your configured key and value as custom issue field map)
5. Pass the map to configMap with key "customIssueFields" of the ShowConversation(configMap)

    Dictionary<string, object> joiningDate = new Dictionary<string, object>();
    joiningDate.Add("type", "date");
    joiningDate.Add("value", DateTimeOffset.UtcNow.ToUnixTimeMilliseconds());

    Dictionary<string, string> stockLevel = new Dictionary<string, string>();
    stockLevel.Add("type", "number");
    stockLevel.Add("value", "1505");

    Dictionary<string, string> employeeName = new Dictionary<string, string>();
    employeeName.Add("type", "singleline");
    employeeName.Add("value", "Bugs helpshift");

    Dictionary<string, string> isPro = new Dictionary<string, string>();
    isPro.Add("type", "boolean");
    isPro.Add("value", "true");

    Dictionary<string, object> cifDictionary = new Dictionary<string, object>();
    cifDictionary.Add("joining_date", joiningDate);
    cifDictionary.Add("stock_level", stockLevel);
    cifDictionary.Add("employee_name", employeeName);
    cifDictionary.Add("is_pro", isPro);


    Map<String, Object> config = new HashMap<>();
    // other configs...
    //.. 
    config.put("customIssueFields", cifMap);

    Helpshift.showConversation(MainActivity.this, config);

The following are the valid values for the type key of a Custom Issue Field.

• "singleline"
• "multiline"
• "number"
• "checkbox"
• "dropdown"
• "date"

Compatibility table for type and values: