Skip to main content

Getting Started Android

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 X which you can call from your C# and Javascript game scripts.

Requirements​

  • Unity 2018.1.0 and above.
  • SDK X is functional only above API Level 24 i.e Android OS 7 Nougat and above.
  • The minSDKVersion in code is kept as API Level 19 to allow importing the SDK and compiling in apps that allow installation till API Level 19 i.e Android 4.4 KitKat.
  • If your app is installed on a device below API level 24 (i.e below Android OS 7 Nougat) then you can choose to have a different medium for providing support. For example, Email, Web etc.
Note
  • From 10.4.0, SDK is compiled using Java 8 to ensure compatibility with Android 15 build tool chain.
  • SDK 10.3.0 and above functions and is supported on Android 7 and above (API level 24 and above).
  • You can still compile your app using a minimum API level of 19, but the support starts for API level 24 and above. For details regarding Helpshift SDK's Android OS support policy, please refer to this article.

Download Helpshift Unity SDK​

1. SDK X - In-app Customer Service​

Helpshift SDK .zip folder includes:

helpshiftX-plugin-unity-v10.4.0.unitypackageUnity package of Helpshift SDK X
unity-jar-resolver (v1.2.170.0)Resolves Android Helpshift package support lib dependencies.
iOS/dSYM/HelpshiftX.framework.dSYMDebugging symbol file for HelpshiftX framework, used for symbolication of crash reports and debugging in Xcode.

Add Helpshift to your Unity project​

  • Unzip the Helpshift Unity SDK package.
  • Helpshift 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. In the Import Unity Package window, click Import
    4. If you are also integrating for iOS, select iOS/Helpshift.framework folder while importing the unitypackage. Refer here.

Resolve Android Appcompat library requirements​

Helpshift SDK depends on android appcompat libraries. You can get these libraries in one of the following ways depending on the build process that you use.

Resolve dependency when using Unity's Internal or Unity's internal Gradle build system​

Use Unity Jar Resolver plugin to download and integrate android library dependencies.

Note

If your project already uses the Unity Jar Resolver, you can skip the Unity Jar Resolver importing step.

You can use any version of Unity Jar Resolver as per your needs. Helpshift packages this for convenience of developers.

You can find the Unity Jar Resolver releases here: https://github.com/googlesamples/unity-jar-resolver/tags

  • Import the Unity Jar Resolver plugin into your Unity project

    1. In the Open Unity project, navigate to Assets drop-down menu and select the Import Package > Custom Package
    2. From the unzipped Helpshift SDK, select unity-jar-resolver/external-dependency-manager-1.2.170.unitypackage file to import the Unity Jar resolver.
    3. In the Import Unity Package window, click Import

  • If the Unity Jar resolver wants to enable Android Auto-resolution, click the Enable button, to resolve all the dependencies automatically on changing any dependency file. You can enable or disable the settings using Assets > Play Services Resolver > Android Resolver > Settings

  • By default, the Unity jar resolver auto-resolves all the required dependencies. Following are the steps to resolve dependencies manually:

    1. In the Open Unity project, navigate to Assets dropdown menu and choose Play services resolver > Android Resolve
    2. Select the Resolve or Force Resolve

  • To know more about the Unity Jar Resolver, refer to: Unity Jar Resolver

Resolve dependency when using custom Gradle template or Export Project​

Unity's in-built gradle build support and exporting to android studio does not support per plugin gradle script. Therefore, by default, Helpshift SDK cannot add the dependencies by itself.

The mainTemplate.gradle is genereted when you enable the Custom Gradle Template property on the Player window.

The build.gradle exists in generated Gradle project when you enable the Export Project property on the Player window and Build the project.

Update dependencies section of the mainTemplate.gradle or build.gradle file as:

    dependencies {
        implementation fileTree(dir: 'libs', include: ['*.jar'])
        implementation(name: 'Helpshift', ext:'aar')
        implementation 'androidx.appcompat:appcompat:1.0.0'
    }

Please refer to Unity's Gradle template documentation here: https://docs.unity3d.com/Manual/gradle-templates.html

Initializing Helpshift in your app​

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

using Helpshift;

  1. First, create an app on the Helpshift Dashboard

  2. Create an app with Android as a selected Platform

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

Domain NameYour Helpshift domain. E.g. happyapps.helpshift.com
Platform IDYour App's unique App Id
You can find these by navigating to `Settings`>`SDK (for Developers)` in your agent dashboard. Select your App and _check Android as a platform_ from the dropdowns and copy the 2 tokens to be passed when initializing Helpshift.

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

using Helpshift;

public class MyGameControl : MonoBehaviour
{
    private HelpshiftSdk help;
    ...
    void Awake() {
        help = HelpshiftSdk.GetInstance();
        var configMap = new Dictionary<string, object>();
        help.Install(appId, domainName, configMap);
    }
    ...
}

Initializing Helpshift in your app for China​

A special install config key, isForChina, should be used for integrating Helphift SDK for China region. This config key accepts a boolean value. Pass true if you are integrating the SDK in an app for China region. The value defaults to false if left unspecified.

using Helpshift;

public class MyGameControl : MonoBehaviour
{
    private HelpshiftSdk help;
    ...
    void Awake() {
        help = HelpshiftSdk.GetInstance();
        var configMap = new Dictionary<string, object>();
        configMap.Add("isForChina", true);
        help.Install(appId, domainName, configMap);
    }
    ...
}
Important

Placing the install call

You should place install call inside the Awake() method. Placing it elsewhere might cause unexpected runtime problems.

HelpshiftInitializationException

Calling any API before the install call would throw an unchecked HelpshiftInitializationException in debug mode.

Android OS version Support

Calling install() below android SDK version 24 will not work. All the APIs will be non operable.

Start using Helpshift​

Helpshift is now integrated in your app. You should now use the support APIs for 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 Awake(){
        // install call here
    }

    void OnGUI () {
        ...
        var configMap = new Dictionary<string, object>();
        // Starting a conversation with your customers
        if (MenuButton (contactButton))
        {
            help.ShowConversation(configMap);
        }
    }
}
Note
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.