Getting Started Android

You're 4 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.

Requirements

  • Unity 5.3.0 and above.
  • Supported Android OS version: 14 and above

If you have a project with Unity version prior to 5.3, you could use the build mentioned here.

Download Helpshift Unity SDK

Helpshift SDK Unity package comes in two variants

1. Helpshift SDK-only dex unity package

Download SDK v3.0.0

This package comes with a secondary dex file consisting of only Helpshift SDK code. Secondary dex install is triggered when the Helpshift SDK is initialized. The SDK apis remain unaffected with secondary dex approach. View Helpshift SDK-only dex impact analysis.

Pre-conditions to use this package

  1. Your app integrates with other plugins using android support libraries.
  2. This package consists of the android support libraries (v23.4.0) as needed by Helpshift SDK. Each library can be added/removed (as per your need) while importing the package.

View integration analysis

2. Unified dex unity package

Download

This package comes with a secondary dex file consisting of Helpshift SDK code as well as android support libraries v23.4.0. Secondary dex install is triggered when the Helpshift SDK is initialized. The SDK apis remain unaffected with this secondary dex approach. View unified dex impact analysis.

Pre-conditions to use this package

  1. Your app does not integrate with other plugins using android support libraries.
  2. The package consists of the required android support libraries (v23.4.0) as needed by Helpshift SDK and cannot be modified by you.
  3. Android support libraries code will be loaded by the secondary dex in your application via Helpshift SDK initialization at runtime.

View integration analysis

The Helpshift SDK .unitypackage contains the following files

Helpshift
Folder containing the C# scripts which expose the Helpshift API to 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 file into your Unity game.

The Helpshift Unity package also comes with the appcompat, recyclerview, design and cardview libraries which are the dependencies of the Helpshift Android SDK. If you already have any of the above mentioned dependencies in your app, please uncheck the appropriate folders while importing the package.

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.

Add package name to AndroidManifest.xml

If you are using gradle build system then ${applicationId} is automatically replaced during build time.

Otherwise, open AndroidManifest.xml located at <project_dir>/Assets/Plugins/Android/helpshift/ and look for ${applicationId} located in <provider> tag. Replace it with the package name of your android app.

As an example, if your package name is PACKAGE_NAME, <provider> tag will now look like this:

    <provider
        android:name="com.helpshift.support.providers.HSPluginFileProvider"
        android:authorities="PACKAGE_NAME.helpshift.fileprovider"
        android:exported="false"
        android:grantUriPermissions="true" >
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/hs__provider_paths" />
    </provider>

Initializing Helpshift in your app

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

using Helpshift;

Helpshift SDK uniquely identifies your App with the combination of:

API Key
Your unique developer API Key.
Domain Name
Your Helpshift domain name. For example : foo.helpshift.com
App ID
A 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.

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

using Helpshift;
.
.
.
private HelpshiftSdk help;

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

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();
        this.help.install("<API_KEY>", "<DOMAIN_NAME>", "<APP_ID>");
    }

    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

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

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

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 the HelpshiftSdk.install() call and do not pass in any arguments. In this case the install time configuration will also be picked up 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.
  3. notificationIcon Name of the drawable file which you want to use for showing Helpshift notifications in the notification drawer. Do not include the file extension in the name. (Android only) The notification file should be present in the drawable folder in the resources of your app i.e Assets/Plugins/Android/helpshift/res/drawable.
  4. notificationSound Name of the resource file which you want to use when you receive a Helpshift notification. Do not include the file extension in the name. (Android only) The notification sound file should be present in the raw folder in the resources of your app i.e Assets/Plugins/Android/helpshift/res/raw.

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.