Getting started with integrating Helpshift in your Unity app.
Guide to integrating the Unity plugin for the Helpshift SDK X which you can call from your C# and Javascript game scripts.
Helpshift SDK .zip folder includes:
.unitypackage
which you can import through the Unity package import procedure.helpshiftx-plugin-unity-version.unitypackage
into your Unity game:helpshiftx-plugin-unity-version.unitypackage
file to import the Helpshift SDK.iOS/Helpshift.framework
folder while importing the unitypackage. Refer here.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.
Use Unity Jar Resolver plugin to download and integrate android library dependencies.
If your project already uses the Unity Jar Resolver, you can skip the Unity Jar Resolver importing step.
unity-jar-resolver/external-dependency-manager-1.2.160.unitypackage
file to import the Unity Jar resolver.If you are not able to import Unity Jar Resolver packaged with Helpshift plugin due to any reason, you can use any version of Unity Jar Resolver as per your needs. Refer here: Unity Jar Resolver
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 'com.android.support:appcompat-v7:28.0.0' //... }
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:
Domain Name
Platform ID
App Id
on dashboard is your platform Id)
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.
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); } ... }
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 21 will not work. All the APIs will be non operable.
You can use the API call help.ShowConversation(configMap)
to allow a user to directly send feedback or start a new conversation without having to first view FAQs. 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 SDK, 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); } void openHelpshift(){ // 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); }
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); } void ShowFAQs(){ // configuration map Dictionary<string, object> configMap = new Dictionary<string, object> { // other values { "tags", new String[] { "foo", "bar" } }, { "initialUserMessage", "Give Feedback"} }; // open the FAQs screen help.ShowFAQs(configMap); }
If you want to add Custom Metadata at the time of Issue creation, follow the steps.
Dictionary
Dictionary
Dictionary
configMap
with key "customMetadata"
to any of the SDK X APIs (like ShowConversation(configMap)
).Use code:
using Helpshift; private HelpshiftSdk help; void Awake(){ // install call here } void openHelpshift(){ Dictionary<string, string> customMetadataDictionary = new Dictionary<string, string>(); customMetadataDictionary.Add("Level", "9"); customMetadataDictionary.Add("Spend", "46.55 USD"); customMetadataDictionary.Add("Device Timestamp", DateTime.UtcNow.ToLongTimeString()); Dictionary<string, object> config = new Dictionary<string, object>(); // other configs... //.. config.Add("customMetadata", customMetadataDictionary); help.ShowConversation(configMap); }
Metadata should only be sent as String key-value pairs.
On Custom Issue Fields keys & compatibility
If you want to set Custom Issue Fields at the time of Issue creation, follow the steps.
Dictionary
Dictionary
"type"
and "value"
for that custom issue fieldconfigMap
with key "customIssueFields"
of the ShowConversation(configMap)
using Helpshift; private HelpshiftSdk help; void Awake(){ // install call here } void openHelpshift(){ 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); Dictionary<string, object> config = new Dictionary<string, object>(); // other configs... //.. config.Add("customIssueFields", cifDictionary); help.ShowConversation(configMap); }
The following are the valid values for the type
key of a Custom Issue Field.
Compatibility table for type and values:
Type | Value | Comments |
---|---|---|
singleline | string | Character limit of 255 |
multiline | string | Character limit of 100,000 |
number | string | |
dropdown | string | Drop-down options should exist for the given Custom Issue Field |
date | number | Epoch time. For example - Date.now() |
checkbox | boolean |