[查看Unity SDK中文接入文档](https://github.com/AI-HELP/AIhelp-Unity-SDK/blob/master/README_CN.md) ## AIHelp SDK Integration Guide ### 1. Download The AIHelp Unity SDK： Click "Clone or download" to download the SDK file in the github page, unzip the compressed file and get **aihelp-plugin-unity.unitypackage** Note: (Only for Android) If you don't have "android-support-v4.jar" in your project, you need to copy the "android-support-v4.jar" to the project libs file. Ignore if there is "android-support-v4.jar" in your project | File name | Description | |:------------- |:---------------| | **aihelp-plugin-unity.unitypackage** | AIHelp Unity SDK | | **android-support-v4.jar** | If not, you need to download and copy it to the project libs file. | **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 Note：After you import the sdk, do not change the files location under Plugins/Android and Plugins/iOS, unless you have a valid reason. Changing file location may result in an integration failure. ![Import AIHelp Package](https://github.com/AI-HELP/Docs-Screenshots/raw/master/import-aihelp-unity-package.png "Import AIHelp Package") ### 3. Configure your Android Manifest（Only for Android) ### (If your apk will go through the process of obfuscating eventually, please add following code in proguard file) -keep class com.lioy.** {*;} -keep class bitoflife.** {*;} -keep class org.fusesource.** {*;} -keep class com.nostra13.** {*;} -keep class com.facebook.** {*;} In the AndroidManifest.xml of your project, add the below information： **a. Add Required Permissions**

**b. Add AIHelp Activities:** About the screen orientations: **android:screenOrientation="portrait"** means AIHelp User Interface will adjust display orientation according to the mobile's screen orientation, if you intend to fixate AIHelp UI display, use below setting: Coding Example: Portrait Display: android:screenOrientation="portrait"(Recommended: the vertical screen display is better) Landscape Display: android:screenOrientation="landscape" Mobile phone physical sensor display： android:screenOrientation="sensor" If your project doesn't have AndroidManifest.xml, please create one in reference with AndroidManifest.xml you downloaded in SDK ### 4. SDK initialization（Must be called during application initialization, otherwise you can't use AIHelp properly） ### Android: **Party A is obliged to use Party B's services according to the correct plug-in method and calling method described by Party B's documents.If Party A uses any technical method to influence Party B's billing,Party B will have the right to notify Party A while unilaterally terminating the service immediately And ask Party A to assume responsibility for infulencing the billing of Party B.
When activiting your app, You must use Instantiate ElvaChatServiceSDKAndroid, then call init with appKey, domain, appId , otherwise you can't use AIHelp service properly. init(string appKey,string domain,string appId);** ``` ElvaChatServiceSDKAndroid Constructor: public ElvaChatServiceSDKAndroid() { AndroidJavaClass jc = new AndroidJavaClass("com.unity3d.player.UnityPlayer"); currentActivity = jc.GetStatic("currentActivity"); sdk = new AndroidJavaClass("com.ljoy.chatbot.sdk.ELvaChatServiceSdk"); } // init public void init(string appKey,string domain,string appId){ sdk.CallStatic("init",currentActivity,appKey,domain,appId); } ``` ### iOS: **Party A is obliged to use Party B's services according to the correct plug-in method and calling method described by Party B's documents. If Party A uses any technical method to influence Party B's billing, Party B will have the right to notify Party A while unilaterally terminating the service immediately and ask Party A to assume responsibility for infulencing the billing of Party B.
When activiting your app, You must use Instantiate ElvaChatServiceSDKIOS, then call init with appKey, domain, appId , otherwise you can't use AIHelp service properly. init(string appKey,string domain,string appId);** ``` ElvaChatServiceSDKIOS Constructor public ElvaChatServiceSDKIOS() { } // init public void init(string appKey,string domain,string appId){ elvaInit(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: NSCameraUsageDescription The customer service of this App may require your permission to access camera NSLocationWhenInUseUsageDescription The customer service of this App may need to access your location data NSMicrophoneUsageDescription This App may require your permission to access audio speaker for ingame customer service NSPhotoLibraryUsageDescription This App may require your permission to access photo library for ingame customer service NSPhotoLibraryAddUsageDescription This App may require your permission to access photo library for ingame customer service **About Parameters：** | Parameters | Description | |:------------- |:---------------| | appKey | Your unique developer API Key, Obtained from the AIHelp web management system| | domain | Your AIHelp domain name, Obtained from the AIHelp web management system. For example: foo.AIHelp.NET| | appId | A unique ID assigned to your app, Obtained from the AIHelp web management system| Note: Please log into [AIHelp Web Console](https://console.aihelp.net/elva) with your registration email account to find the __appKey__, __domain__ and __appId__ In the _Application_ page of the _Settings_ Menu. If your company does not have an account, you can register an account at [AIHelp Website](http://aihelp.net/index.html) **Coding Example：(Must be called during application initialization, otherwise you can't use AIHelp properly)**
**Party A is obliged to use Party B's services according to the correct plug-in method and calling method described by Party B's documents. If Party A uses any technical method to influence Party B's billing, Party B will have the right to notify Party A while unilaterally terminating the service immediately and ask Party A to assume responsibility for infulencing the billing of Party B.** ``` private static AIhelpService _instance; public static AIhelpService Instance { get{ if (_instance == null) { //Debug.LogError ("AIHelp service is not initialized!"); _instance = new AIhelpService (); } return _instance; } } public void Initialize(string appkey, string domain, string appId) { if (sdk != null) { sdk.init(appkey, domain, appId); postInitSetting (); } } public AIhelpService() { #if UNITY_ANDROID if(Application.platform == RuntimePlatform.Android) sdk = new ElvaChatServiceSDKAndroid(); #endif #if UNITY_IOS if(Application.platform == RuntimePlatform.IPhonePlayer) sdk = new ElvaChatServiceSDKIOS(); #endif } ``` **Register Initialization Callback (optional）：** ###

Register Initialization Callback `registerInitializationCallback`

``` void registerInitializationCallback(string gameObject); ``` **Code Example：** ``` public void RegisterInitializationCallback(string gameObject) { if(sdk != null) { sdk.registerInitializationCallback(gameObject); } } ``` **About Parameters：** - gameObject: The name of GameObject in your Unity Scene, you can use transform.name to get the GameObject during runtime. For example： ``` // Register Callback AIhelpService.Instance.RegisterInitializationCallback (transform.name); // Do Initialization AIhelpService.Instance.Initialize ("TRYELVA_app_5a6b4540bbee4d7280fda431700ed71a", "TryElva.AIHELP.NET", appid); ``` Prerequisite： - Must register callback before initialization. - Must define and implement callback method `OnAIHelpInitialized`in the GameObject's script class： ``` // Implement initialization callback public void OnAIHelpInitialized(string str) { // add code here Debug.Log ("AIhelpInitCallback is called str:" + str); } ``` --- ### 5. Start Using AIHelp ### 1. API Summary | Method Name| Purpose |Prerequisites| |:------------- |:---------------|:---------------| |Recommended interface:| | **[setName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#setName)** | Set APP/Game Name|Use it after Initialization| | **[setUserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName)** | Set User In-App name| If the username is not obtained, the empty string "" is passed, and the default nickname "anonymous" is used.| | **[setUserId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserId)** | Set Unique User ID| If the userid is not available, the empty string "" is passed, and a unique device id is generated.| | **[setServerId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#ServerId)** | Set the server ID where the (user) is located | If the game party can't get the data, pass the empty string ""| | **[setSDKLanguage](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#setSDKLanguage)** | Set SDK Language| Note: The default is to use the phone system language setting, you can call the setting language in the app after setting.| |Optional interface:| | **[showElva](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showElva)** | Launch AI Conversation Interface| |**[showConversation](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showConversation)**|Launch VIP Conversation Interface| Need to [setUserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName) and [setUserId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserId) | | **[showElvaOP](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showElvaOP)** | Launch Operation Interface| Need to configure Operation Sections| | **[showFAQs](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showFAQs)** | Show all FAQs by Sections|Need to configure FAQs,Need to [setUserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName) and [setUserId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserId)| | **[showFAQSection](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showFAQSection)** | Show all FAQs in a category | | **[showSingleFAQ](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showSingleFAQ)** | Show Single FAQ|Need to Configure FAQ,Need to [setUserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName) and [setUserId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserId)| **Note：It is not necessary for you to use all the APIs, especially when you only have one user interface for the customer service in your application. Some APIs already contains entry to other APIs, 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 config); ``` **Coding Example：** ``` public void AIHelpChat() { Dictionary tags = new Dictionary (); List tag = new List(); tag.Add ("server1"); tag.Add ("pay3"); tags.Add ("elva-tags", tag); Dictionary config = new Dictionary (); 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.
![showElva](https://github.com/AI-HELP/Docs-Screenshots/raw/master/showElva-EN-Android.png "showElva") **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 experiences. > 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. The AI Help ``` void showElvaOP( string playerName, string playerUid, string serverId, string showConversationFlag); ``` OR ``` void showElvaOP( string playerName, string playerUid, string serverId, string showConversationFlag, Dictionary config); ``` OR ``` void showElvaOP( string playerName, string playerUid, string serverId, string showConversationFlag, Dictionary config, int defaultTabIndex); ``` **Coding Example：** ``` // Presenting Operation Info to your customers public void OperationModule() { Dictionary tags = new Dictionary (); List tag = new List(); tag.Add ("server1"); tag.Add ("pay3"); tags.Add ("elva-tags", tag); Dictionary config = new Dictionary (); 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 corner 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.
![showElvaOP](https://github.com/AI-HELP/Docs-Screenshots/raw/master/showElvaOP-EN-Android.png "showElvaOP") **Best Practice：** > 1. Use this API to present news, announcements, articles or any useful information to users. Configure and publish the information in AIHelp web console. ###

4. Display FAQs, use `showFAQs `

``` void showFAQs(); ``` OR ``` void showFAQs(Dictionary config); ``` **Coding Example：** ``` public void ShowFAQs() { if(sdk != null) { Dictionary config = new Dictionary (); Dictionary map = new Dictionary (); List tags = new List(); // The first way to customize needs to be consistent with the background (for the key form) tags.Add("vip1"); // "elva-tags" Is the key value can not be changed map.Add("elva-tags", tags); // The second way to customize does not need to go to the background configuration (for the key-value form) map.Add("udid", "123456789"); // "elva-custom-metadata" Is the key value can not be changed config.Add("elva-custom-metadata", map); // Add this parameter, where the key is immutable. The highest priority. Plus the upper right corner of the post faq will never show. // (If you want to display, you need to delete this parameter and join config.Add("showContactButtonFlag", "1"); config.Add("hideContactButtonFlag", "1"); // The display can be accessed from the upper right corner of the FAQ list (if you do not want to display it, you need to delete this parameter) config.Add("showContactButtonFlag", "1"); // Click on the upper right corner of the FAQ to enter the upper right corner of the robot interface. (If you do not want to display, you need to delete this parameter.) config.Add("showConversationFlag", "1"); // Click on the upper right corner of the FAQ and you will be taken to the manual customer service page (without adding the default to the robot interface. If you don't need it, delete this parameter) config.Add("directConversation", "1"); // Set the username If you don't get the username, pass in the empty string "" and the default nickname "anonymous" will be used. sdk.setUserName("user_name"); // Set the user ID. If you don't get the userid, pass in the empty string "" and the system will generate a unique device id. sdk.setUserId("user_id"); // Set the service ID sdk.setServerId("server_id"); 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.
![showFAQs](https://github.com/AI-HELP/Docs-Screenshots/raw/master/showFAQs-EN-Android.png "showFAQs") **Best Practice：** > 1. Use this method to show FAQs 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 config); ``` **Coding Example：** ``` // Presenting single FAQ to your customers public void ShowSingleFAQ(faqId) { if(sdk != null) { Dictionary config = new Dictionary (); Dictionary map = new Dictionary (); List tags = new List(); // The first way to customize needs to be consistent with the background (for the key form) tags.Add("vip1"); // "elva-tags" Is the key value can not be changed map.Add("elva-tags", tags); // The second way to customize does not need to go to the background configuration (for the key-value form) map.Add("udid", "123456789"); // "elva-custom-metadata" Is the key value can not be changed config.Add("elva-custom-metadata", map); // Add this parameter, where the key is immutable. The highest priority. Plus the upper right corner of the post faq will never show. // (If you want to display, you need to delete this parameter and join config.Add("showContactButtonFlag", "1"); config.Add("hideContactButtonFlag", "1"); // The display can be accessed from the upper right corner of the FAQ list (if you do not want to display it, you need to delete this parameter) config.Add("showContactButtonFlag", "1"); // Click on the upper right corner of the FAQ to enter the upper right corner of the robot interface. (If you do not want to display, you need to delete this parameter.) config.Add("showConversationFlag", "1"); // Click on the upper right corner of the FAQ and you will be taken to the manual customer service page (without adding the default to the robot interface. If you don't need it, delete this parameter) config.Add("directConversation", "1"); // Set the username If you don't get the username, pass in the empty string "" and the default nickname "anonymous" will be used. sdk.setUserName("user_name"); // Set the user ID. If you don't get the userid, pass in the empty string "" and the system will generate a unique device id. sdk.setUserId("user_id"); // Set the service ID sdk.setServerId("server_id"); sdk.showSingleFAQ(faqId, config); } } ``` **About Parameters：** - __faqId__: The PublishID of the FAQ item, you can check it at in [AIHelp Web Console](https://aihelp.net/elva): 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.
showSingleFAQ

**Self-Service：** If you configure the "self-service" link in the FAQ's configuration, and set [UserId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserId), [UserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName), [ServerId](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#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 display in the title bar of the customer service interface. ###

7. Set the Unique User ID, use `setUserId`

``` void setUserId(string userId); //If the userid is not available, the empty string "" is passed, and a unique device id is generated. ``` **Coding Example：** ``` sdk.setUserId("123ABC567DEF"); //If the userid is not available, the empty string "" is passed, and a unique device id is generated. ``` **About Parameters：** - __playerUid__:Unique User ID **Best Practice：** > 1. Normally you don 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](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#selfservice), then you must set the User Id first. ###

8. Set User Name，use `setUserName`

``` void setUserName(string userName); //If the username is not obtained, the empty string "" is passed, and the default nickname "anonymous" is used. ``` **Coding Example：** ``` sdk.setUserName ("PLAYER_NAME");//If the username is not obtained, the empty string "" is passed, and the default nickname "anonymous" is used. ``` **About Parameters：** - __playerName:__ User 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](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#selfservice), 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](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#selfservice), then you must set the User Id first. ###

10. Launch VIP Chat Console, use `showConversation`(need to set [UserName](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#UserName))

``` void showConversation( string playerUid, string serverId); ``` or ``` void showConversation( string playerUid, string serverId, Dictionary config); ``` **Coding Example：** ``` public void ShowVIPChat() { if(sdk != null) { Dictionary tags = new Dictionary (); List tag = new List(); tag.Add ("server1"); tag.Add ("pay3"); tags.Add ("elva-tags", tag); Dictionary config = new Dictionary (); config.Add ("elva-custom-metadata", tags); sdk.setUserName("PLAYER_NAME"); If the username is not obtained, the empty string "" is passed, and the default nickname "anonymous" is used. 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 vector 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 conversation without engaging with the AI chat. You may use this method as a privilege for some users.
showConversation

###

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.

**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 your 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](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showElva) or [showElvaOP](https://github.com/AI-HELP/AIhelp-Unity-SDK/raw/master/#showElvaOP)： **Coding Example：** ``` Dictionary welcomeText = new Dictionary (); // 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 config = new Dictionary (); 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.