Android SDK 集成

一、Android SDK 使用说明

1、使用示例

添加依赖

SDK Maven 仓库地址：

https://maven.aliyun.com/nexus/content/repositories/releases

SDK Gradle 依赖：

implementation 'com.aliyun.mobi:mobi-copilot:1.0.1'

使用 SDK

在 Java 或 Kotlin 文件中导入 MobiCopilot 类。

import com.mobi.sdk.MobiCopilot;

通过 MobiCopilot.Builder() 创建一个 MobiCopilot 实例，传入需要的配置项。

MobiCopilot mobiCopilot = new MobiCopilot.Builder()
        .setUrl("Copilot 应用发布地址")
        .setAccessToken("通过魔笔 OpenAPI 获取的 accessToken，仅用于生产环境")
        .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 方法

加载 Copilot 应用

通过 mobiCopilot.loadCopilot() 加载 Copilot 应用，可选参数为 MobiCopilot.MobiErrorListener 实例，用于接收和处理 Copilot 应用的运行时错误。

mobiCopilot.loadCopilot(new MobiCopilot.MobiErrorListener() {
    @Override
    public void onError(MobiCopilot.MobiError error) {
        // 自定义运行时错误处理逻辑
    }
});

更新身份验证令牌

accessToken 过期时间为 300 秒，需要在过期时间内通过 RefreshNativeUserToken 接口 重新获取，通过 mobiCopilot.updateAccessToken(newAccessToken); 设置新的 accessToken。

MobiCopilotRouter 说明

自定义功能路由处理逻辑。

MobiCopilotRouter 说明

自定义运行时错误处理逻辑。

注意，当功能路由发生错误时，onNavigateError 和 onError 都会被调用。

MobiError 说明

SDK 定义的错误对象。

3、兼容性说明

SDK 本身兼容至 Android 7.0，由于需要在 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 和 accessToken 作为参数传递给 SDK

将 Copilot 应用的开发环境访问链接，配置到工程的demo/src/main/java/com/mobi/demo/CopilotFragment.java文件中。

• 开发环境应用：无需传递 accessToken，如果 Copilot 应用的登录配置中不允许匿名访问，则通过登录页进行认证，推荐使用测试账号登录，也可通过创建身份源扩展其他的登录方式。如果允许匿名访问，则无需认证。

• 生产环境应用：如果 Copilot 应用的登录配置中不允许匿名访问，则需要先在魔笔控制台-用户与权限-身份源中创建并启用一个 Native 类型的身份源，确保该身份源对应的权限组具备足够的访问权限，然后通过 GenerateNativeUserToken 接口 生成 accessToken，传递给 SDK。accessToken 过期时间为 300 秒，需要在过期时间内通过RefreshNativeUserToken 接口 重新获取，最后通过 mobiCopilot.updateAccessToken(newAccessToken); 设置新的 accessToken。如果允许匿名访问，则无需认证，需注意配置 SDK 时不传入 accessToken，如果传入了 accessToken，则将根据 accessToken 进行身份认证，匿名访问不生效。

5、运行 Demo

使用 Android Studio 启动项目。

通过登录页访问开发环境的 Copilot 应用，使用 accessToken 访问生产环境的 Copilot 应用。

成功访问到 Copilot 应用，用户输入请假或预定会议室的需求后，Copilot 将发送对应的功能路由卡片，用户可通过功能路由卡片跳转至 Native 页面并携带意图框架提取到的参数。

6、注意事项

• 该 Demo 中注册的 navigateTo 方法仅适配于通过 App Copilot Template 应用模板创建的应用中的功能路由配置，如修改了功能路由配置，请更新 navigateTo 方法以处理不同路由标识和路由参数的跳转行为。

• 如 Android Studio 提示 gradle 插件不兼容，可更新 Android Studio 或尝试降低 gradle/libs.versions.toml 中的插件版本。

• 本项目默认使用的 gradle 插件版本为 8.7，构建时需要 JDK 17 以上的 Java 环境。