1. 概述

键盘输入（Keyboard），简称KB，在最少输入、最大时间内输入理想的文本。支持中文，外文，韩文，日文等识别，同时支持多种键盘（T9，Qwerty以及容错键盘）以及多种输入模式（拼音，五笔，笔画等）。

本文档旨在讲解如何快速地集成灵云KB功能到开发者应用中。关于各服务接口更详细的说明，请参考灵云SDK开发手册。在集成过程中如有疑问，可登录灵云开发者论坛，查找答案或与其他开发者交流。

1.1 概念解释

对指南中涉及的名词作简要描述，使开发者在阅读开发指南时，对此有一些大致的了解和预备知识的了解。 如：

1.2 能力定义（capkey）

1.3 识别流程

2. 能力使用说明

2.1 准备工作

下载键盘输入SDK并解压缩。

请下载相应资源包并解压缩。

2.2 使用Android版SDK

2.2.1 库目录文件介绍

• jar包文件

  • hcicloud-8.1.jar

• 必选模块

  • libhci_curl.so
  • libhci_sys.so
  • libhci_sys_jni.so
  • libhci_kb.so
  • libhci_kb_jni.so
  • libhci_kb_local_recog.so

特别注意

Module的build.gradle中，必须配置packagingOptions.doNotStrip参数，以保留灵云SDK中的签名信息，该信息在SDK内部使用，用来保护灵云SDK的知识版权。 若此参数未配置，或配置不正确，在进行本地能力调用时，将会返回本地引擎初始化失败的信息。

• build.gradle示例

    apply plugin: 'com.android.application'
  
    android {
        compileSdkVersion 17
        buildToolsVersion "27.0.3"
  
        defaultConfig {
            applicationId "com.sinovoice.example"
            minSdkVersion 7
            targetSdkVersion 17
            packagingOptions {
                doNotStrip "*/armeabi/*.so"
                doNotStrip "*/armeabi-v7a/*.so"
                doNotStrip "*/arm64-v8a/*.so"
                // add other if needed
            }
        }
  
        buildTypes {
            release {
                minifyEnabled false
                proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.txt'
            }
        }
    }
  
    dependencies {
        compile files('libs/hcicloud-8.1.jar')
        compile files('libs/hcicloud_recorder-8.1.jar')
    }
  

2.2.2 添加用户权限

在工程 AndroidManifest.xml 文件中添加如下权限。

  <!--通常需要设置一些sd卡路径（例如日志路径）为可写，因此需要能够写外部存储 -->

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

  <!--以下访问网络的权限均需要打开-->

  <!--连接网络权限，用于执行云端能力 -->
  <uses-permission android:name="android.permission.INTERNET" />
  <!--读取网络信息状态 -->
  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
  <!--获取当前wifi状态 -->
  <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
  <!--允许程序改变网络连接状态 -->
  <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
  <!--读取手机信息权限 -->
  <uses-permission android:name="android.permission.READ_PHONE_STATE"/>

  <!--以下访问权限可选-->

  <!--手机定位信息-->
  <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
  <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

3. 能力集成说明

本章节主要讲述KB能力的集成过程，开发者可根据本章内容完成KB能力的简单调用。本章节以本地识别为例，讲述KB能力的集成调用流程，调用顺序参考识别流程。

3.1 通用模块初始化

在调用KB能力之前，需要初始化灵云SDK的通用模块。详见灵云SDK开发手册

• Android示例代码

    // 创建初始化参数辅助类
    InitParam initparam = new InitParam();
    // 授权文件所在路径，此项必填
    String authDirPath = context.getFilesDir()  .getAbsolutePath();;
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_AUTH_PATH, authDirPath)    ;
    // 灵云云服务的接口地址，此项必填
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_CLOUD_URL,     "http://api.hcicloud.com:8888");
    // 开发者密钥，此项必填，由捷通华声提供
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_DEVELOPER_KEY,     "01234567890");
    // 应用程序序号，此项必填，由捷通华声提供
    initparam.addParam  (InitParam.AuthParam.PARAM_KEY_APP_KEY, "1234abcd");
    // 日志的路径，可选，如果不传或者为空则不生成日志
    String logDirPath =     "/storage/emulated/0/sinovoice/com.sinovoice.   example/log";
    initparam.addParam  (InitParam.LogParam.PARAM_KEY_LOG_FILE_PATH,  logDirPath);
    //日志等级，0=无，1=错误，2=警告，3=信息，4=细节，5=调试
    //SDK将输出小于等于logLevel的日志信息
    initparam.addParam  (InitParam.LogParam.PARAM_KEY_LOG_LEVEL, "5");
    // 灵云系统初始化
    // 第二个参数在Android平台下，必须为当前的Context
    int errCode = HciCloudSys.hciInit   (initparam.getStringConfig(), this);
    if(errCode != HciErrorCode.HCI_ERR_NONE) {
        // "系统初始化失败"
        return;
    }
  

3.2 授权检测

在初始化灵云SDK的通用模块后，还需要调用授权检测函数获取云端授权。

• Android示例代码

    // 获取授权
    private int checkAuthAndUpdateAuth() {
        // 获取系统授权到期时间
        int initResult;
        AuthExpireTime objExpireTime = new AuthExpireTime   ();
        initResult = HciCloudSys.hciGetAuthExpireTime   (objExpireTime);
        if (initResult == HciErrorCode.HCI_ERR_NONE) {
            // 显示授权日期,如用户不需要关注该值,此处代码可忽   略
            Date date = new Date    (objExpireTime.getExpireTime() * 1000);
            SimpleDateFormat sdf = new SimpleDateFormat ("yyyy-MM-dd",Locale.CHINA);
            Log.i(TAG, "expire time: " + sdf.format(date))  ;
  
            if (objExpireTime.getExpireTime() * 1000 >  System.currentTimeMillis()) {
                Log.i(TAG, "checkAuth success");
                return initResult;
            }
        }
  
        // 获取过期时间失败或者已经过期
        initResult = HciCloudSys.hciCheckAuth();
        if (initResult == HciErrorCode.HCI_ERR_NONE) {
            Log.i(TAG, "checkAuth success");
            return initResult;
        } else {
            Log.e(TAG, "checkAuth failed: " + initResult);
            return initResult;
        }
    }
  

3.3 KB初始化

• Android代码

// 创建初始化参数辅助类
KbInitParam initParam = new KbInitParam();
// 设置本地资源库的路径
initParam.addParam(KbInitParam.PARAM_KEY_DATA_PATH, 
                    "/storage/emulated/0/sinovoice/com.sinovoice.example/data");
// 使用本地识别能力
initParam.addParam(KbInitParam.PARAM_KEY_INIT_CAP_KEYS, "kb.local.recog");
// 初始化KB能力
errCode = HciCloudKb.hciKbInit(initParam.getStringConfig());

常见errcode，详见灵云SDK开发手册

3.4 开启会话（session）

KB 是通过会话（session）来管理识别过程的。在KB能力初始化成功之后，需要通过开启识别会话来完成识别。详见灵云SDK开发手册

• Android代码

Session session = new Session();
KbConfig sessionConfig = new KbConfig();
sessionConfig.addParam(KbConfig.SessionConfig.PARAM_KEY_CAP_KEY, "kb.local.recog");
// 开启会话
errCode = HciCloudKb.hciKbSessionStart(sessionConfig.getStringConfig(), session);

3.5 输入识别

在启动会话（session）成功后，即可可以进行 KB的输入识别。配置参数详见灵云SDK开发手册

• Android代码

KbConfig recogConfig = new KbConfig();
//设置输入模式，以"inputMode=pinyin"中文输入模式为例
recogConfig.addParam(KbConfig.InputConfig.PARAM_KEY_INPUT_MODE, "pinyin");
KbQueryInfo queryInfo = new KbQueryInfo();
KbRecogResult recogResult = new KbRecogResult();

//设置查询内容
queryInfo.setQuery("nichidaolema");
queryInfo.setSlideInfoItemCount(0);
queryInfo.setSlideInfoItemList(null);
queryInfo.setSelectedItemCount(0);
queryInfo.setQuerySelectedItemList(null);
errCode = HciCloudKb.hciKbRecog(session, 
                                recogConfig.getStringConfig(), 
                                queryInfo, 
                                recogResult);
if (errCode == HciErrorCode.HCI_ERR_NONE) 
{
    ShowMessage("hciKbRecog success");
    //输出识别结果
    PrintKbResult(recogResult);
}

常见errcode，详见灵云SDK开发手册

3.6 结束识别

最后我们需要反初始化，依次关闭会话，终止KB能力，关闭灵云系统。

• Android代码

//关闭KB识别会话
errCode = HciCloudKb.hciKbSessionStop(session);
//终止KB能力
errCode = HciCloudKb.hciKbRelease();
//终止灵云系统
errCode = HciCloudSys.hciRelease();

常见errcode，详见灵云SDK开发手册

4. FAQ

Q1: 请问你的键盘SDK怎么使用键盘的UI界面？

A: 我们SDK不包含键盘界面，键盘是在对应平台的UI层自己实现，将用户数据收集为我们需要的格式sdk识别接口传入给KB引擎即可。

Q2: 键盘SDK怎么支持不同语言的识别？

A: 只要替换相应语言的资源文件即可（kb.conf,kb.dic）。

Q3: 怎么调整候选词的频率？

A: 使用:hciKbUdbCommit(Session session, StringstrConfig, KbUdbItemInfo udbItemInfo)添加用户自定义词这个接口来调整词频，将拼音和文字保存到udbItemInfo在传入接口即可调节词频。

Q4: 怎么保存自造词？

A: 保存自造词的接口为hciKbUdbCommit(Session session,String strConfig, KbUdbItemInfo udbItemInfo)将自造词和自造词对应的拼音保存到udbItemInfo在传入接口即可保存自造词，保存后会在授权路径生成kb.local.recog文件,使用方法参考相关开发指南。