快速入门

本文介绍如何在安卓项目中快速上手涂鸦 MiniApp SDK。

初始化 SDK

在调用小程序的 API 之前，您需要先初始化 MiniApp SDK，在 App 启动时调用初始化 API，用以保证小程序框架的正常运行。

接口说明

/**
 * 初始化小程序
 */
ThingMiniAppClient
     .initialClient()
     .initialize();

打开小程序

小程序管理主要介绍操作小程序的 API，包括但不限于：

• 打开小程序
• 预加载小程序
• 清理小程序缓存等

针对不同的业务场景，打开小程序所需的 API 也不尽相同。所以涂鸦提供了不同 API 以应对不同的场景。

• 打开线上小程序：线上小程序的打开一般只需要小程序 ID 即可。
• 二维码打开小程序：适用于扫码涂鸦开发者平台二维码，传入二维码数据打开小程序。这种方式可以打开正式版、开发版、体验版、IDE 调试版小程序。
• URL 形式打开小程序：适用于打开小程序时，需要指定具体页面路径时，仅支持打开线上版本小程序。

方式一：通过 AppID

在打开小程序时，会优先判断本地是否存在缓存：

• 如果存在缓存，则直接加载缓存在本地的小程序，同时后台线程更新小程序版本。
• 如果没有缓存，则会先触发小程序下载，下载成功后再打开小程序。

更新逻辑中，如果更新到了新的小程序版本，则会在下次打开时生效。

接口说明

/**
 * 通过 appId 打开小程序
 * @params context      不可空
 * @params appId        小程序 ID，不可空
 * @params appVersion   小程序版本，可空
 * @params params       业务参数，可空
*/
fun openMiniAppByAppId(context: Context, appId : String, appVersion: String? = null, params: Bundle? = null)

参数说明

参数名称	参数含义	是否必传	说明
appId	小程序 ID	是	可在 涂鸦开发者平台 查询
appVersion	小程序版本号	否	指定版本
params	业务参数	否	给小程序携带参数

示例代码

ThingMiniAppClient
    .coreClient()
    .openMiniAppByAppId(context, "tydhopggfziofo1h9h", null, null);

方式二：扫描二维码

二维码打开小程序需要先扫码 涂鸦开发者平台 上的二维码，查询到二维码内容，然后调用对应 API 打开小程序。

接口说明

/**
 * 二维码数据打开小程序
 * @params context  不可为空
 * @params url      二维码内容，不可为空
 * @pamras params   业务参数，可为空
*/
fun openMiniAppByQrcode(context: Context, url : String, params: Bundle? = null)

参数说明

参数名称	参数含义	是否必传	说明
url	二维码内容	是	扫码涂鸦开发者平台二维码查询
params	业务参数	否	需要给小程序携带参数时可传

示例代码

ThingMiniAppClient
    .coreClient()
    .openMiniAppByQrcode(context, "tuyaSmart--miniApp?url=godzilla://tydhopggfziofo1h9h", null);

方式三：通过 URL

URL 方式能更有针对性地打开小程序的指定页面。

接口说明

/**
 * 通过 URL 形式打开小程序
 * @params context  不可为空
 * @params url      小程序对应的具体 URL 链接，不可为空
 * @params params   业务参数，可为空
*/
fun openMiniAppByUrl(context: Context, url : String, params: Bundle? = null)

参数说明

参数名称	参数含义	是否必传	说明
url	小程序 URL	是	格式为 godzilla://miniprogramId/pagePath
params	业务参数	否	需要给小程序携带参数时可传

示例代码

ThingMiniAppClient
    .coreClient()
    .openMiniAppByUrl(context, "godzilla://tydhopggfziofo1h9h/pages/home/index", null);

删除小程序

小程序在使用后，SDK 会将小程序包和其对应信息存储到本地。存储到本地的信息会占用设备空间，如果想要清理小程序及其缓存，则需要调用以下 API。

接口说明

/**
 * 清理所有小程序缓存
*/
fun clearCache()

示例代码

ThingMiniAppClient
    .coreClient()
    .clearCache();

预下载小程序

提前把小程序下载到本地，可以加快小程序的启动时间。

接口说明

/**
 * 预下载小程序，仅支持正式版本小程序
 * @params appId 小程序 ID，可在涂鸦开发者平台查看， 不可为空
*/
fun preloadMiniApp(appId: String)

参数说明

参数名称	参数含义	是否必传	说明
appId	小程序 ID	是	可在涂鸦开发者平台查询

示例代码

ThingMiniAppClient
    .coreClient()
    .preloadMiniApp("tydhopggfziofo1h9h");

查询相关信息

小程序在运行过程中，需要一些基础信息帮助涂鸦更好地定位问题，所以涂鸦提供了查询部分运行信息的 API。

接口说明

/**
 * 返回当前最新的基础库版本
*/
fun getJSSdkVersion(): String?

/**
 * 返回当前 SDK 对应的小程序容器版本
*/
fun getMiniAppContainerVersion() : String?

/**
 * 返回当前 App 依赖的 TTT-Kits 版本
*/
fun getMiniAppKitsVersion() : Map<String, String>?

/**
 * vConsole 调试是否支持
 * @param enable true 支持；false 不支持。
*/
fun vConsoleDebugEnable(enable : Boolean)

示例代码

// 查询基础库版本
ThingMiniAppClient
    .debugClient()
    .getJSSdkVersion();

// 查询小程序容器版本
ThingMiniAppClient
    .debugClient()
    .getMiniAppContainerVersion();

// 查询 TTT-Kits 版本
ThingMiniAppClient
    .debugClient()
    .getMiniAppKitsVersion();

// vConsole 调试是否支持开关
ThingMiniAppClient
    .debugClient()
    .vConsoleDebugEnable(true);

vConsole 调试

小程序在运行过程中，可能会遇到各种问题，为了更好地定位问题，涂鸦提供了调试开关，开启调试开关后，可以在 vConsole 看到小程序运行中的日志。

接口说明

/**
 * vConsole 调试是否支持
 * @param enable true 支持；false 不支持。
*/
fun vConsoleDebugEnable(enable : Boolean)

示例代码

// vConsole 调试是否支持开关
ThingMiniAppClient
    .debugClient()
    .vConsoleDebugEnable(true);

自定义拓展 API

MiniApp SDK 提供了一系列 API 方便您直接调用，您在前端代码中通过 ty.xxx({}) 形式即可调用这些 API。

但是在小程序实际开发过程中，现有的这些 API 可能并不能完美地支持业务需求，基于此涂鸦提供了自定义拓展 API 的能力。

自定义 API

自定义的 API 需要继承 BaseExtApiModule 抽象类，协议定义了自定义 API 所需的数据及方法。

接口说明

public abstract class BaseExtApiModule implements IExtApiMiniAppLifeCycle {

    /**
     * API 异步方法实现。在子线程中调用
     *
     * @param params   API 入参{@link Map<String,Object>}格式表示参数名和参数值
     * @param callback API 执行状态，成功或失败都必须回调，告知前端该接口的执行结果
     */
    @WorkerThread
    public abstract void invoke(@Nullable Map<String, Object> params, IGZLResultCallback<ExtApiResult> callback);

    /**
     * API 同步方法实现。在子线程中调用
     *
     * @param params API 入参{@link Map<String, Object>}格式表示参数名和参数值
     * @return {@link ExtApiResult} 返回结果，此类中的 data 参数不能混淆
     */
    @WorkerThread
    public abstract @NonNull
    ExtApiResult invokeSync(@Nullable Map<String, Object> params);

    /**
     * 小程序可活动时候的回调，一般是解除 Pause 状态后。子类可根据需要重写
     * 该回调在在子线程中触发
     * */
    @Override
    @WorkerThread
    public void onMiniAppResume() {

    }

    /**
     * 小程序暂停状态时候的回调，例如退到后台或被其他原生页面覆盖。子类可根据需要重写
     * 该回调在在子线程中触发
     * */
    @Override
    @WorkerThread
    public void onMiniAppPause() {

    }

    /**
     * 小程序销毁时的回调。子类可根据需要重写业务逻辑
     * 该回调在在子线程中触发
     * */
    @Override
    @WorkerThread
    public void onMiniAppDestroy() {

    }

}

注册自定义 API

接口说明

// 创建一个实体类，服从 ThingMiniAppExtApiProtocol 协议
ThingMiniAppClient.developClient()
                .addExtApiImpl("apiname", APIExtService.class)

static class APIExtService extends BaseExtApiModule{

        /**
         * API 异步方法实现。在子线程中调用
         *
         * @param params   API 入参{@link Map<String,Object>}格式表示参数名和参数值
         * @param callback API 执行状态，成功或失败都必须回调，告知前端该接口的执行结果
         */
        @Override
        public void invoke(@Nullable Map<String, Object> params, IGZLResultCallback<ExtApiResult> callback) {

        }

        /**
         * API 同步方法实现。在子线程中调用
         *
         * @param params API 入参{@link Map<String, Object>}格式表示参数名和参数值
         * @return {@link ExtApiResult} 返回结果，此类中的 data 参数不能混淆
         */
        @NonNull
        @Override
        public ExtApiResult invokeSync(@Nullable Map<String, Object> params) {
            return null;
        }
    }

调用自定义 API

要调用自定义 API，小程序需要依赖 MiniKit。配合 MiniKit 中的几个 API，您可以很方便地调用自定义 API：

• ty.extApiCanIUse：提前判断指定的自定义 API 是否可用。

  // 传入自定义 API 名称
  ty.extApiCanIUse({
      api: 'xxx',
      success:(res)=>{
          console.log(res.result)
      },
      fail:(err)=>{
          console.log(err)
      }
  })
  

• ty.extApiInvoke：调用异步类型的自定义 API。

  // 传入自定义 API 名称和参数
  ty.extApiInvoke({
      api: 'xxx',
      params: {},
      success:(res)=>{
          console.log(res.data)
      },
      fail:(err)=>{
          console.log(err)
      }
  })
  

• ty.extApiInvokeSync：调用同步类型的自定义 API。

  // 传入自定义 API 名称和参数
  const data = ty.extApiInvokeSync({api: 'xxx', params: {}})