Android icon AIhelp Android SDK Integration Guide


There are two methods to integrate AIhelp Android SDK to your APP's project. If you use Android Studio or another development platform which supports Gradle. We recommend you use method #1:

Method #1. Use Gradle to integrate AIhelp SDK online:

1. Add Below Lines in your Project's build.gradle:

  allprojects {
    repositories {
      jcenter()
  }
  

2. Add Below Dependencies in the build.gradle of your APP or Module which intracts with AIhelp sdk:

  dependencies {
  ...
    compile 'net.aihelp:elva:1.3.6.2'
    compile 'com.android.support:appcompat-v7:23.4.0'
    compile 'com.android.support:design:23.4.0'
    compile 'com.android.support:recyclerview-v7:23.4.0'
    compile 'com.android.support:cardview-v7:23.4.0'
  ...
  }
  

Wait until the build.gradle sync completion and make sure there is no error during sync: Under the "External Libraries" folder of Android Studio Project sturcture view, you should be able to find the folder "elva-1.3.6" and other dependencies specified above. If there is an error during sync or you can not find elva folder. Use the Method #2 below:

Method #2. Download The AIhelp Android SDK:

Select "Clone or download" to download Android SDK in the github page, unzip the downloaded file.

AIhelp-Android-SDK Contains:

SubFolder name Description
android-libs AIHelp Android SDK Dependencies
aihelpsdk AIHelp Android SDK Core Files

Add AIHelp to your Android project:

  1. Copy files under folder aihelpsdk/libs to the the libs folder of your APP's project.
  2. Copy files under folder aihelpsdk/res to the res folder of your APP's project.
  3. Import dependencies under android-libs to your Project:

If your project has already imported some of the dependencies, just import those you do not have. If you use Gradle,all you need to do is add the below dependencies in your build.gradle:

  compile 'com.android.support:appcompat-v7:23.4.0'
  compile 'com.android.support:design:23.4.0'
  compile 'com.android.support:recyclerview-v7:23.4.0'
  compile 'com.android.support:cardview-v7:23.4.0'
  # add this if using appindexing:
  compile 'com.google.android.gms:play-services-appindexing:8.1.0'
  

If you use Eclipse that does not use Gradle, you need to import each of the dependencies into your project as a library. You also need to explicitly add dependency relationship between the AIHelp SDK and the libraries: elvachatservice depends on design, which depends on appcompat, recyclerview and cardview.

3. Configure your Android Manifest

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="sensor">
  </activity>
  <activity
    android:name="com.ljoy.chatbot.FAQActivity"
    android:configChanges="orientation|screenSize|locale"
    android:screenOrientation="sensor"
    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="sensor"
    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>
  

About the screen orientations: android:screenOrientation="sensor" means that AIhelp User Interface will adjust display orientation according to the mobile's screen orientation, if you intend to fixate AIhelp UI display, use the below setting:

Landscape Display:

android:screenOrientation="landscape"

Portrait Display:

android:screenOrientation="portrait"

4. Initialize AIHelp SDK in your Project

  ELvaChatServiceSdk.init(
                  Activity activity,
                  String appKey,
                  String domain,
                  String appId
                  )
  

About Parameters:

Parameters Description
Activity App's Activty
AppKey Unique Developer API Key
Domain AIHelp Domain Name. For Example: foo.AIHELP.NET
AppId Unique ID Assigned to your App.

Coding Example:

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

  import com.ljoy.chatbot.sdk.ELvaChatServiceSdk;

  public class MyActivity extends Activity {

  @Override
  public void onCreate(Bundle savedInstanceState)
    { super.onCreate(savedInstanceState);
    try {
      ELvaChatServiceSdk.init(this,
                              "YOUR_API_KEY",
                              "YOUR_DOMAIN_NAME",
                              "YOUR_APP_ID");
    } catch (InstallException e) { Log.e(TAG,
        "invalid init params : ", e);
      }
    }
  }
  

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

2. Launch the AI Conversation Interface,Use showElva

  ELvaChatServiceSdk.showElva(
              String playerName,
              String playerUid,
              String serverId,
              String showConversationFlag);
  

or

  ELvaChatServiceSdk.showElva(
              String playerName,
              String playerUid,
              String serverId,
              String showConversationFlag,
              HashMap<String,Object> customData);
  

Coding Example:

  // Presenting AI Help Converation with your customers

  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  // other data
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);

  ELvaChatServiceSdk.setName("APP_NAME"); // set APP name
  ELvaChatServiceSdk.showElva(
          "USER_NAME",
          "USER_ID",
          "Server_ID",
          "1", // show conversation entry
          config);
  

About Parameters:

  • playerName: In-App User Name
  • playerUid: In-App Unique User ID
  • serverId: Server ID
  • playerParseId: Can be empty string, can NOT be NULL
  • showConversationFlag: Should be "0" or "1". If set at "1", the VIP conversation entry will be displayed in the upper right of the AI conversation interface.
  • config: Optional parameters for custom HashMap information. You can pass specific Tag information using ArrayList 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 texts and AI story lines in the AIHelp Web Console to better the customer support experiences.
  2. Enable VIP Conversation Entry to allow user to chat with your human support team with parameters "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. The AI Help

  ELvaChatServiceSdk.showElvaOP(
      String playerName,
      String playerUid,
      String serverId,
      String showConversationFlag);


  ELvaChatServiceSdk.showElvaOP(
      String playerName,
      String playerUid,
      String serverId,
      String showConversationFlag,
      HashMap<String,Object> config);


  ELvaChatServiceSdk.showElvaOP(
              String playerName,
              String playerUid,
              String serverId,
              String showConversationFlag,
              HashMap<String,Object> config,
              int defaultTabIndex);
  

Coding Example:

  //  Presenting Operation Info to your customers
  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  //  other data
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);

  ELvaChatServiceSdk.setName("APP_NAME"); // set APP name
  ELvaChatServiceSdk.showElvaOP(
          "USER_NAME",
          "USER_ID",
          "Server_ID",
          "1", // show conversation entry
          config);
  

About Parameters:

  • playerName: User Name in Game/APP
  • playerUid: Unique User ID
  • serverId: The Server ID
  • playerParseId: Can be empty string, can NOT be NULL
  • showConversationFlag: Should be "0" or "1". If set at "1", the VIP conversation entry will be shown in the top right corner of the AI conversation interface.
  • config: Optional param for custom HashMap information. You can pass specific Tag information using ArrayList 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.
  • defaultTabIndex: Optional. The index of the first tab to 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) 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 the AIHelp web console.

4. Display FAQs, use showFAQs

  ELvaChatServiceSdk.showFAQs();

  ELvaChatServiceSdk.showFAQs (HashMap config)
  

Coding Example:

  //  Presenting FAQs to your customers
  HashMap<String,Object> map = new HashMap();
  config.put("showConversationFlag","1");//show conversation entry in the top right corner

  ELvaChatServiceSdk.setUserName("USER_NAME"); // set User Name
  ELvaChatServiceSdk.setUserId("USER_ID"); // set User Id
  ELvaChatServiceSdk.setServerId("SERVER_ID"); // set Serve Id

  ELvaChatServiceSdk.showFAQs(config);
  

About Parameters:

  • config: Optional parameters for custom HashMap information. You can pass specific Tag information using the ArrayList 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 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 many, you can also add Parent Sections to categorize sections to make things clear and organized.

5. Show A Specific FAQ,use showSingleFAQ

  ELvaChatServiceSdk.showSingleFAQ(String faqId);

  ELvaChatServiceSdk.showSingleFAQ(String faqId,HashMap config);
  

Coding Example:

  Presenting Single FAQ to your customers

  ELvaChatServiceSdk.setUserName("USER_NAME"); // set User Name
  ELvaChatServiceSdk.setUserId("USER_ID"); // set User Id
  ELvaChatServiceSdk.setServerId("SERVER_ID"); // set Server Id

  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  // other data
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);
  config.put("showConversationFlag","1");// show conversation entry in the top right corner.

  ELvaChatServiceSdk.showSingleFAQ("23",config);
  

Coding Example:

  Presenting Single FAQ to your customers

  ELvaChatServiceSdk.setUserName("USER_NAME"); // set User Name
  ELvaChatServiceSdk.setUserId("USER_ID"); // set User Id
  ELvaChatServiceSdk.setServerId("SERVER_ID"); // set Server Id

  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  // other data
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);
  config.put("showConversationFlag","1");// show conversation entry in the top right corner.

  ELvaChatServiceSdk.showSingleFAQ("23",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 custom HashMap information. You can pass specific Tag information using ArrayList 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 the 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 AIHelps’ SDK to display,use setName

ELvaChatServiceSdk.setName(String game_name);

Coding Example:

ELvaChatServiceSdk.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

ELvaChatServiceSdk.setUserId(String playerUid);

Coding Example:

ELvaChatServiceSdk.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

ELvaChatServiceSdk.setUserName (String playerName);

Coding Example:

ELvaChatServiceSdk.setUserName ("PLAYER_NAME");

About Parameters:

  • playerName: User/Player Name

9. Set Unique Server ID,use setServerId

ELvaChatServiceSdk.setServerId(String serverId);

Coding Example:

ELvaChatServiceSdk.setServerId("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 other 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)

  ELvaChatServiceSdk.showConversation(
                  String playerUid,
                  String serverId);
  

or

  ELvaChatServiceSdk.showConversation(
                  String playerUid,
                  String serverId,
                  HashMap config);
  

Coding Example:

  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  //other data
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);

  ELvaChatServiceSdk.setUserName("USER_NAME");
  ELvaChatServiceSdk.showConversation("USER_ID","SERVER_ID",config);
  

About Parameters:

  • playerUid:Unique User ID
  • serverId: The Unique Server ID
  • config: Optional parameters for custom HashMap information. You can pass specific Tag information using the ArrayList 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.

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.

ELvaChatServiceSdk.setSDKLanguage(string language);

Coding Example:

ELvaChatServiceSdk.setSDKLanguage("en");

About Parameters:

  • language: Standard Language Alias. For example: en is for English, zh_CN is for Simplified Chinese。More language label 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 the 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 the config parameters in showElva or showElvaOP

map.put("anotherWelcomeText","usersay");

Coding Example:

  HashMap<String,Object> map = new HashMap();
  ArrayList<String> tags = new ArrayList();
  tags.add("pay1");
  tags.add("s1");
  tags.add("elvaTestTag");
  map.put("elva-tags",tags);
  //  note:anotherWelcomeText is key,should be unchanged.
  //  you need to change usersay according to the "User Say" in your new
  //  story line
  map.put("anotherWelcomeText","usersay");
  HashMap<String,Object> config = new HashMap();
  config.put("elva-custom-metadata",map);

  ELvaChatServiceSdk.setName("APP_NAME"); // set APP Name

  //  Enter show AI support
  ELvaChatServiceSdk.showElva(
          "USER_NAME",
          "USER_ID",
          "Server_ID",
          "1", // show conversation entry
          config);
  

or

  //  Enter operational module
  ELvaChatServiceSdk.showElvaOP( "USER_NAME",
          "USER_ID",
          "Server_ID",
          "1", // show conversation entry
          config);
  

Best Practice:

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