本文档介绍了如何利用魔笔提供的 Android SDK 将 Copilot 应用集成到 Android 应用中。
一、Android SDK 使用说明
1、使用示例
添加依赖
SDK Maven 仓库地址:
https://maven.aliyun.com/nexus/content/repositories/releases
SDK Gradle 依赖:
implementation 'com.aliyun.mobi:mobi-copilot:1.0.0'
使用 SDK
在 Java 或 Kotlin 文件中导入 MobiCopilot 类。
import com.mobi.sdk.MobiCopilot;
通过 MobiCopilot.Builder() 创建一个 MobiCopilot 实例,传入需要的配置项。
MobiCopilot mobiCopilot = new MobiCopilot.Builder()
.setUrl("Copilot 应用发布地址")
.setAuthToken("通过魔笔 OpenAPI 获取的 authToken,仅用于生产环境")
.setWebView(webView)
.setCustomRouter(new MobiCopilot.MobiCopilotRouter() {
@Override
public void navigateTo(String routerKey, Map<String, Object> routerParams) {
// 自定义功能路由处理逻辑
}
@Override
public void onNavigateError(String routerKey, MobiCopilot.MobiError error) {
// 自定义功能路由错误处理逻辑
}
})
.build();
2、详细说明
配置项 set 方法
set 方法 | 配置项类型 | 是否必填 | 说明 |
setWebView | WebView | 是 | 用于加载和显示 Copilot 应用的 WebView 组件 |
setUrl | String | 是 | Copilot 应用 URL |
setAuthToken | String | 开发环境无效 生产环境必填 | 开发环境应用:不需要传递 authToken 生产环境应用:通过 GenerateNativeUserToken 接口 生成 authToken,传递给 SDK |
setCustomRouter | MobiCopilotRouter | 是 | 功能路由处理对象 |
加载 Copilot 应用
通过 mobiCopilot.loadCopilot() 加载 Copilot 应用,可选参数为 MobiCopilot.MobiErrorListener 实例,用于接收和处理 Copilot 应用的运行时错误。
mobiCopilot.loadCopilot(new MobiCopilot.MobiErrorListener() {
@Override
public void onError(MobiCopilot.MobiError error) {
// 自定义运行时错误处理逻辑
}
});
更新身份验证令牌
authToken 过期时间为 300 秒,需要在过期时间内通过 RefreshNativeUserToken 接口 重新获取,通过 mobiCopilot.updateAuthToken(newAuthToken);
设置新的 authToken
MobiCopilotRouter 说明
自定义功能路由处理逻辑。
方法名 | 参数 | 说明 |
navigateTo | String routerKey, Map<String, Object> routerParams | 当功能路由正常触发时调用 |
onNavigateError | String routerKey, MobiCopilot.MobiError error | 当功能路由发生错误时调用 |
MobiCopilotRouter 说明
自定义运行时错误处理逻辑。
方法名 | 参数 | 说明 |
onError | MobiCopilot.MobiError error | 当 Copilot 应用运行出错时调用 |
注意,当功能路由发生错误时,onNavigateError 和 onError 都会被调用。
MobiError 说明
SDK 定义的错误对象。
方法名 | 返回值类型 | 说明 |
getCode | String | 获取错误码 |
getMessage | String | 获取错误消息 |
错误码 | 说明 |
AuthTokenError | AuthToken 过期 |
NavigateError | 跳转错误,如参数无法序列化 |
updateAuthTokenError | 更新 AuthToken 错误 |
3、兼容性说明
SDK 本身兼容 Android 5+,由于需要在 WebView 中运行 Copilot 应用,客户端提供的 WebView 版本将直接影响 Copilot 应用的运行。
目前,Copilot 应用兼容 com.google.android.webview 80 以上版本。
我们将持续优化 Copilot 应用兼容性并实时生效,您的 Android 应用无需更新。
二、Android SDK Demo 工程使用说明
魔笔提供了 Android Demo 用于演示 Copilot Android SDK 的使用方法。
1、通过 Copilot 应用模板创建应用,发布应用到开发或生产环境;
2、下载 Demo 工程 到本地,项目结构:
.
├── README.md
├── build.gradle
├── settings.gradle
├── gradle/
│ ├── libs.versions.toml
│ └── wrapper/
│ ├── gradle-wrapper.jar
│ └── gradle-wrapper.properties
└── demo/
├── build.gradle
└── src/
└── main/
├── AndroidManifest.xml
├── res/
└── java/
└── com/
└── mobi/
└── demo/
├── MainActivity.java
├── CopilotFragment.java
├── LeaveFragment.java
├── MeetingFragment.java
└── NonScrollableViewPager.java
3、获取应用运行信息
从应用环境信息获取应用地址;
4、将应用 url 和 authToken 作为参数传递给 SDK
将 Copilot 应用的开发环境访问链接,配置到工程的demo/src/main/java/com/mobi/demo/CopilotFragment.java
文件中。
设置 url 和 authToken 传参
开发环境应用:不需要传递 authToken
生产环境应用:通过 GenerateNativeUserToken 接口 生成 authToken,传递给 SDK
authToken 过期时间为 300 秒,需要在过期时间内通过 RefreshNativeUserToken 接口 重新获取,通过
mobiCopilot.updateAuthToken(newAuthToken);
设置新的 authToken。
5、运行 Demo
使用 Android Studio 启动项目。
启动登录访问开发环境的 Copilot 应用,生产环境使用 authToken 免登
成功访问到 Copilot 应用,再向 Copilot 表达请假或预定会议室的意图时,Copilot 将下发跳转到 Native 的页面的功能路由,并匹配相关的页面表单项。
6、注意事项
该 Demo 中注册的 navigateTo 方法仅适配于通过 App Copilot Template 应用模板创建的应用中的功能路由配置,如修改了功能路由配置,请更新 navigateTo 方法以处理不同路由标识和路由参数的跳转行为。
如 Android Studio 提示 gradle 插件不兼容,可更新 Android Studio 或尝试降低 gradle/libs.versions.toml 中的插件版本。