Unity icon AIHelp Unity SDK Integration Guide


1. Download The AIHelp Unity SDK:

Select "Clone or download" to download the SDK file in the github page, unzip the compressed file and get aihelp-plugin-unity.unitypackage


File name Description
aihelp-plugin-unity.unitypackage AIHelp Unity SDK
AndroidManifest.xml Example AndroidManifest file

2. Add AIHelp to your Unity project:

In your Unity project,select menu Assets->Import Package->Custom Package,find aihelp-plugin-unity.unitypackage in the finder window.


Or find aihelp-plugin-unity.unitypackage and double-click to open it, import the aihelp unity sdk into your project


AIHelp import unity package

3. Configure your Android Manifest(Only for Android)

In the AndroidManifest.xml of your project, add the below information:

a. Add Required Permissions

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />

b. Add AIHelp Activities:

<activity
  android:name="com.ljoy.chatbot.ChatMainActivity"
  android:configChanges="orientation|screenSize|locale"
  android:screenOrientation="portrait">
</activity>
<activity
  android:name="com.ljoy.chatbot.FAQActivity"
  android:configChanges="orientation|screenSize|locale"
  android:screenOrientation="portrait"
  android:theme="@android:style/Theme.Holo.Light.DarkActionBar">
  <intent-filter android:label="@string/app_name">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https"
             android:host="cs30.net"
             android:pathPrefix="/elvaFAQ" />
  </intent-filter>
</activity>
<activity
    android:name="com.ljoy.chatbot.OPActivity"
    android:configChanges="orientation|screenSize|locale"
    android:screenOrientation="portrait"
    android:theme="@style/Theme.AppCompat.Light.NoActionBar">
</activity>
<activity
  android:name="com.ljoy.chatbot.WebViewActivity"
  android:screenOrientation="sensor"
  android:configChanges="orientation|screenSize|locale"
  android:theme="@android:style/Theme.Holo.Light.DarkActionBar">
  <intent-filter android:label="@string/app_name">
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
  </intent-filter>
</activity>

c. Add Meta Data (if using ‘app indexing’)

<meta-data
  android:name="com.google.android.gms.version"
  android:value="@integer/google_play_services_version" />

4. Initialize AIHelp SDK in your Project

Android:

Instantiate Class ElvaChatServiceSDKAndroid with AppKey, Domain, AppId:

//ElvaChatServiceSDKAndroid Constructor:

  public ElvaChatServiceSDKAndroid(string appKey, string domain, string appId)
  {
    AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer");
    currentActivity = jc.GetStatic<AndroidJavaObject>("currentActivity");
    sdk = new AndroidJavaClass("com.ljoy.chatbot.sdk.ELvaChatServiceSdk");

    //  pass the appkey, domain and appId of your own app,
    respectively init(appKey, domain, appId);

  }

iOS:

Instantiate Class ElvaChatServiceSDKIOS with AppKey, Domain, AppId:

//ElvaChatServiceSDKIOS Constructor:

  public ElvaChatServiceSDKIOS(string appKey, string domain, string appId)
  {
    //  pass the appkey, domain and appId of your own app,
    respectively init(appKey, domain, appId);
  }

Add Required Permissions:

Please note that, you should add the below content into the Info.plist file of your Unity-iPhone Xcode project:

<key>NSCameraUsageDescription</key>
<string>The customer service of this App may require your permission to access camera</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>The customer service of this App may need to access your location data </string>
<key>NSMicrophoneUsageDescription</key>
<string>This App may require your permission to access audio speaker for ingame customer service</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This App may require your permission to access photo library for ingame customer service</string>

About Parameters:

Parameters Description
AppKey Your unique developer API Key
Domain Your AIHelp domain name. For example: foo.AIHELP.NET
AppId A unique ID assigned to your app.

Coding Example:

//  Must be called during application/game initialization, otherwise you can't
use AIHelp properly


private void initAIHelpSDK()
{
  aihelpService = new AIhelpServiceExample();
}
public AIhelpServiceExample()
{
  #if UNITY_ANDROID
  if(Application.platform == RuntimePlatform.Android)
  sdk = new ElvaChatServiceSDKAndroid(
    "TRYELVA_app_5a6b4540bbee4d7280fda431700ed71a",
    "TryElva.AIHELP.NET",
    "TryElva_platform_14970be5-d3bf-4f91-8c70-c2065cc65e9a");
  #endif
  #if UNITY_IOS
  if(Application.platform == RuntimePlatform.IPhonePlayer)
  sdk = new ElvaChatServiceSDKIOS(
    "TRYELVA_app_5a6b4540bbee4d7280fda431700ed71a",
    "TryElva.AIHELP.NET",
    "TryElva_pf_ec28eb91dd7d463bb359fc53d43dcfd6");
  #endif
}

5. Start Using AIHelp

1. API Summary

Method Name Purpose Prerequisites
showElva Launch AI Conversation Interface
showElvaOP Launch Operation Interface Need to configure Operation sections
showFAQs Show all FAQs by Sections Need to configure FAQs
showConversation Launch VIP Conversation Interface Need to setUserName and setUserId
showSingleFAQ Show Single FAQ Need to configure FAQ
setName Set APP/Game Name Use it after initialization
setUserName Set User In-App Name
setUserId Set Unique User ID
setSDKLanguage Set SDK Language

See below for details:

2. Launch the AI Conversation Interface,Use showElva

void showElva(
    string playerName,
    string playerUid,
    string serverId,
    string showConversationFlag);


void showElva(
    string playerName,
    string playerUid,
    string serverId,
    string showConversationFlag,
    Dictionary<string,object> config);

Coding Example:

public void AIHelpChat()
{
  Dictionary<string, object> tags = new Dictionary<string, object> ();
  List<string> tag = new List<string>(); tag.Add ("server1");

  tag.Add ("pay3");
  tags.Add ("elva-tags", tag);
  Dictionary<string, object> config = new Dictionary<string, object> ();
  config.Add ("elva-custom-metadata", tags);

  sdk.showElva(
      "TEST_PLAYER_NAME",
      "TEST_UID_123",
      "TEST_SRV_ID_123",
      "1",
      config);
}

About Parameters:

  • playerName: In-app User Name
  • playerUid: In-app Unique User ID
  • serverId: The Server ID
  • showConversationFlag: Should be "0" or "1". If set at "1", the VIP conversation entry will be displayed in the upper right hand side of the AI conversation interface.
  • config: Optional parameters for customized information. You can pass specific Tag information using the sting list "elva-tags", see the above coding example. Please note that you also need to configure the same tag information in the Web console so that each conversation can be correctly tagged.

AIHelp showElva English Android

Best Practice:

  1. Use this method to launch your APP's customer service. Configure specific welcome text and AI story line in the AIHelp Web Console to better the customer support experience.
  2. Enable VIP Conversation Entry to allow users’ to chat with your human support team with parameter "showConversationFlag" setting to "1", you may use this method for any user or as a privilege for some users only.

3. Launch The Operation Interface, use showElvaOP

The operation module is useful when you want to present updates, news, articles or any background information about your APP/Game to users.

void showElvaOP(
            string playerName,
            string playerUid,
            string serverId,
            string showConversationFlag);

OR

void showElvaOP(
            string playerName,
            string playerUid,
            string serverId,
            string showConversationFlag,
            Dictionary<string,object> config);

OR

void showElvaOP(
            string playerName,
            string playerUid,
            string serverId,
            string showConversationFlag,
            Dictionary<string,object> config,
            int defaultTabIndex);

Coding Example:

//  Presenting Operation Info to your
customers public void OperationModule()
{
  Dictionary<string, object> tags = new Dictionary<string, object> ();
  List<string> tag = new List<string>();
  tag.Add ("server1");
  tag.Add ("pay3"); tags.Add
  ("elva-tags", tag);
  Dictionary<string, object> config = new Dictionary<string, object> ();
  config.Add ("elva-custom-metadata", tags);
  sdk.showElvaOP
        ( "TEST_PLAYER_NAME",
        "TEST_UID_123",
        "TEST_SRV_ID_123", "",
        "1",
        config);
}

About Parameters:

  • playerName: User Name in Game/APP
  • playerUid: Unique User ID
  • serverId: The Server ID
  • showConversationFlag: Should be "0" or "1". If set at "1", the VIP conversation entry will be shown in the top right hand side of the AI conversation interface.
  • config: Optional parameters for customized information. You can pass specific Tag information using sting list "elva-tags", see above coding examples. Please note you also need to configure the same tag information in the Web console so that each conversation can be correctly tagged.
  • defaultTabIndex: Optional. The index of the first tab will be shown when entering the operation interface. Default value is the left-most tab,if you would like to show the AI conversation interface(the right-most side) set to 999.

AIHelp showElvaOP Android

Best Practice:

  1. Use this API to present news, announcements, articles or any useful information to users/players. Configure and publish the information in AIHelp web console.

4. Display FAQs, use showFAQs

void showFAQs();

OR

void showFAQs(Dictionary<string,object> config);

Coding Example:

public void ShowFAQs()
{
  if(sdk != null)
  {
    Dictionary<string, object> tags = new Dictionary<string, object> ();
    List<string> tag = new List<string>(); tag.Add ("server1");

    tag.Add ("pay3");
    tags.Add ("elva-tags", tag);
    Dictionary<string, object> config = new Dictionary<string, object> ();
    config.Add ("elva-custom-metadata", tags);
    config.Add("showConversationFlag", "1"); // 显示可以从FAQ进 入 人 工客服
    sdk.showFAQs(config);
  }
}

About Parameters:

  • config: Optional parameters for customized information. You can pass specific Tag information using sting list "elva-tags", see the above coding examples. Please note you also need to configure the same tag information in the Web console so that each conversation can be correctly tagged.

AIHelp showFAQs English Android

Best Practice:

  1. Use this method to show FQAs about your APP/Game properly. Configure FAQs in AIHelp Web Console. Each FAQ can be categroized into a section. If the FAQs are great in number, you can also add Parent Sections to categorize sections to make things clear and organized.

5. Show A Specific FAQ,use showSingleFAQ

void showSingleFAQ (string faqId);
void showSingleFAQ (string faqId, Dictionary<string,object> config);

Coding Example:

//  Presenting single FAQ to your customers
public void ShowSingleFAQ(faqId)
{
  if(sdk != null)
  {
    Dictionary<string, object> tags = new Dictionary<string, object> ();
    List<string> tag = new List<string>();
    tag.Add ("server1");
    tag.Add ("pay3");
    tags.Add ("elva-tags", tag);
    Dictionary<string, object> config = new Dictionary<string, object> ();
    config.Add ("elva-custom-metadata", tags);
    config.Add("showConversationFlag", "1"); // 显示可以从FAQ进 入 人 工客服
    sdk.showSingleFAQ(faqId, config);
  }
}

About Parameters:

  • faqId: The PublishID of the FAQ item, you can check it at AIHelp Web Console: Find the FAQ in the FAQ menu and copy its PublishID.
  • config: Optional parameters for customized information. You can pass specific Tag information using sting list "elva-tags", see the above coding example. Please note you also need to configure the same tag information in the Web console so that each conversation can be correctly tagged.

AIHelp showSingleFAQ English Android

Self-Service:

If you configure the "self-service" link in the FAQ's configuration, and set UserId, UserName, ServerId in SDK, then the FAQ shows a functional menu in the right-top cornor.

Best Practice:

  1. Use this method when you want to show a specific FAQ in a proper location of your APP/Game.

6. Set Your App's name for AIHelp SDK to display,use setName

void setName(string game_name);

Coding Example:

sdk.setName("Your Game");

About Parameters:

  • game_name: APP/Game Name

Best Practice:

  1. Use this method after SDK initialization.The App's name will be displayed in the title bar of the customer service interface.

7. Set the Unique User ID, use setUserId

void setUserId(string userId); 

Coding Example:

sdk.setUserId("123ABC567DEF");

About Parameters:

  • playerUid: Unique User ID

Best Practice:

  1. Normally you do not need to use this method if you have passed the user ID in another method. However, if you want to use the FAQ's Self-Service, then you must set the User Id first.

8. Set User Name,use setUserName

void setUserName(string userName);

Coding Example:

sdk.setUserName ("PLAYER_NAME");

About Parameters:

  • playerName: User/Player Name

Best Practice:

  1. Use this method to set the user name, which will be shown in the web console's conversation page for the user. You can address the user with this name during the chat.
  2. Normally you do not need to use this method if you have passed the user name in another method. However, if you want to use FAQ's Self-Service, then you must set the User Id first.

9. Set Unique Server ID,use setServerId

void setServerId(int serverId);

Coding Example:

sdk.seterverId("SERVER_ID");

About Parameters:

  • serverId: The Unique Server ID

Best Practice:

  1. Normally you do not need to use this method if you have passed the server ID in another method. However, if you want to use the FAQ's Self-Service, then you must set the User Id first.

10. Launch VIP Chat Console, use showConversation (need to set UserName)

void showConversation(
            string playerUid,
            string serverId);

OR

void showConversation(
            string playerUid,
            string serverId,
            Dictionary<string,object> config);

Coding Example:

public void ShowVIPChat()
{
  if(sdk != null)
  {
    Dictionary<string, object> tags = new Dictionary<string, object> ();
    List<string> tag = new List<string>(); tag.Add ("server1");

    tag.Add ("pay3");
    tags.Add ("elva-tags", tag);
    Dictionary<string, object> config = new Dictionary<string, object> ();
    config.Add ("elva-custom-metadata", tags);
    sdk.setUserName("PLAYER_NAME");
    sdk.showConversation(faqId, config);
  }
}

About Parameters:

  • playerUid:Unique User ID
  • serverId: The Unique Server ID
  • config: Optional parameters for customized information. You can pass specific Tag information using the sting list "elva-tags", see the above coding example. Please note you also need to configure the same tag information in the Web console so that each conversation can be correctly tagged.

Best Practice:

  1. Normally you do not need to use this method unless you intend to allow users to enter VIP conversations without engaging with the AI chat. You may use this method as a privilege for some users.

AIHelp showConversation English Android

11. Set SDK Lanague,use setSDKLanguage

Setting the SDK Language will change the FAQs, Operational Information, AI Chat and SDK display language.

void setSDKLanguage (string language);

Coding Example:

sdk.setSDKLanguage("en");

About Parameters:

  • language: Standard Language Alias. For example: en is for English, zh_CN is for Simplified Chinese。More language labels can be selected through AIHelp Web Console:"Settings"-->"Language"->Alias.

AIHelp language alias

Best Practice:

  1. Normally AIHelp will use the mobile's lanaguge configuration by default. If you intend to make a different language setting, you need to use this method right after SDK initialization.
  2. If you allow users to change the APP language, then you need to use this method to make AIHelp the same lanague with your APP.

12. Set a Different Greeting Story Line.

If your APP provides multiple entries to AIHelp, and you intend to introduce different AI welcome texts and story lines to users from different entries, you can set config parameters within showElva or showElvaOP

Coding Example:

Dictionary<string, object> welcomeText = new Dictionary<string, object> ();

//  note:anotherWelcomeText is key,should be unchanged.
//  you need to change usersay according to the "User Say" in your new
//  story line

welcomeText.Add("anotherWelcomeText","usersay");
Dictionary<string, object> config = new Dictionary<string, object> ();
config.Add ("elva-custom-metadata", welcomeText);


sdk.showElva(
          "TEST_PLAYER_NAME",
          "TEST_UID_123",
          "TEST_SRV_ID_123",
          "",
          "1",
          config);

OR

sdk.showElvaOP(
        "TEST_PLAYER_NAME",
        "TEST_UID_123",
        "TEST_SRV_ID_123",
        "",
        "1",
        config);

Best Practice:

  1. Introduce different story lines to users from different sources.