快速入门

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

SDK 初始化

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

接口说明

/// 初始化 SDK
- (void)initialize;

示例代码

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // App 启动时初始化
    [[ThingMiniAppClient initialClient] initialize];
    return YES;
}

打开小程序

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

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

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

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

方式一：通过 AppID

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

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

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

接口说明

/// 通过小程序 ID 打开小程序
/// - Parameter appId：小程序 ID，可在涂鸦开发者平台查看
- (void)openMiniAppByAppId:(nonnull NSString *)appId;

/// 通过小程序 ID 打开小程序
/// - Parameters：
///   - appId：小程序 ID，可在涂鸦开发者平台查看
///   - params：额外传入的业务参数，小程序可在 Page.onLoad 中获取
- (void)openMiniAppByAppId:(nonnull NSString *)appId params:(nullable NSDictionary *)params;

/// 通过小程序 ID 打开小程序
/// - Parameters：
///   - appId：小程序 ID，可在涂鸦开发者平台查看
///   - appVersion：小程序版本号，需要指定具体版本时可传
///   - params：额外传入的业务参数，小程序可在 Page.onLoad 中获取
- (void)openMiniAppByAppId:(nonnull NSString *)appId appVersion:(nullable NSString *)appVersion params:(nullable NSDictionary *)params;

参数说明

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

示例代码

[[ThingMiniAppClient coreClient] openMiniAppByAppId:@"tydhopggfziofo1h9h"];

// 携带业务参数
[[ThingMiniAppClient coreClient] openMiniAppByAppId:@"tydhopggfziofo1h9h" params:@{@"key": @"value"}];

// 指定小程序版本
[[ThingMiniAppClient coreClient] openMiniAppByAppId:@"tydhopggfziofo1h9h" appVersion:@"5.1.0" params:nil];

方式二：扫描二维码

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

接口说明

/// 二维码数据打开小程序
/// - Parameter qrcode：二维码内容
- (void)openMiniAppByQrcode:(nonnull NSString *)qrcode;

/// 二维码数据打开小程序
/// - Parameters：
///   - qrcode：二维码内容
///   - params：额外传入的业务参数，小程序可在 Page.onLoad 中获取
- (void)openMiniAppByQrcode:(nonnull NSString *)qrcode params:(nullable NSDictionary *)params;

参数说明

参数名称	参数含义	是否必传	备注
qrcode	二维码内容	是	扫码涂鸦开发者平台二维码获取
params	业务参数	否	给小程序携带参数

示例代码

[[ThingMiniAppClient coreClient] openMiniAppByQrcode:@"tuyaSmart--miniApp?url=godzilla://tydhopggfziofo1h9h"];

// 携带业务参数
[[ThingMiniAppClient coreClient] openMiniAppByQrcode:@"tuyaSmart--miniApp?url=godzilla://tydhopggfziofo1h9h" params:@{@"key":@"value"}];

方式三：通过 URL

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

接口说明

/// 通过 URL 形式打开小程序
/// - Parameter url：小程序对应的具体 URL 链接
- (void)openMiniAppByUrl:(nonnull NSString *)url;

/// 通过 URL 形式打开小程序
/// - Parameters：
///   - url：小程序对应的具体 URL 链接
///   - params：额外传入的业务参数，小程序可在 Page.onLoad 中获取
- (void)openMiniAppByUrl:(nonnull NSString *)url params:(nullable NSDictionary *)params;

参数说明

参数名称	参数含义	是否必传	备注
url	小程序 URL	是	格式为 godzilla://miniprogramId/pagePath
params	业务参数	否	给小程序携带参数

示例代码

// 打开指定页面
[[ThingMiniAppClient coreClient] openMiniAppByUrl:@"godzilla://tydhopggfziofo1h9h/pages/home/index"];

// 携带业务参数
[[ThingMiniAppClient coreClient] openMiniAppByUrl:@"godzilla://tydhopggfziofo1h9h/" params:@{@"key":@"value"}];

删除小程序

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

接口说明

/// 清理所有小程序缓存
- (void)clearCache;

示例代码

[[ThingMiniAppClient coreClient] clearCache];

预下载小程序

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

接口说明

/// 预下载小程序，仅支持正式版本小程序
/// - Parameter appId：小程序 ID，可在涂鸦开发者平台查看
- (void)preloadMiniApp:(nonnull NSString *)appId;

参数说明

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

示例代码

[[ThingMiniAppClient coreClient] preloadMiniApp:@"tydhopggfziofo1h9h"];

查询相关信息

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

接口说明

/// 返回当前最新的基础库版本
- (NSString *)getJSSdkVersion;

/// 返回当前 SDK 对应的小程序容器版本
- (NSString *)getMiniAppContainerVersion;

/// 返回当前 App 依赖的 TTT-Kits 版本
- (NSDictionary *)getMiniAppKitsVersion;

示例代码

// 获取基础库版本
NSString *jssdkVersion = [[ThingMiniAppClient debugClient] getJSSdkVersion];

// 获取小程序容器版本
NSString *containerVersion = [[ThingMiniAppClient debugClient] getMiniAppContainerVersion];

// 获取 TTT-Kits 版本
NSDictionary *kitsVersion = [[ThingMiniAppClient debugClient] getMiniAppKitsVersion];

vConsole 调试

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

接口说明

/// vConsole 调试开关
/// - Parameter enable：是否打开调试开关
- (void)vConsoleDebugEnable:(BOOL)enable;

示例代码

// 开启 vConsole 调试开关
[[ThingMiniAppClient debugClient] vConsoleDebugEnable:YES];

自定义拓展 API

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

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

自定义 API

自定义的 API 需要服从 ThingMiniAppExtApiProtocol 协议，协议定义了自定义 API 所需的数据及方法。

接口说明

/// 自定义 API 的名称，返回值需要 App 维度唯一
/// 必须实现
- (NSString *)apiName;

/// 自定义 API 是否可用，返回 True 表示 API 可用
/// 可选实现
- (BOOL)canIUseExtApi;

/// 异步自定义 API 执行，API 为异步方法时必须实现
/// - Parameters：
///   - context：API 执行时的上下文
///   - params：API 执行时传递的参数
///   - success：API 执行成功后需要触发的回调
///   - fail：API 执行失败后需要触发的回调
- (void)invokeExtApi:(nonnull id<ThingMiniAppExtApiContext>)context
              params:(nullable NSDictionary *)params
             success:(nonnull ThingMiniExtApiResponseCallback)success
                fail:(nonnull ThingMiniExtApiResponseCallback)fail;

/// 同步自定义 API 执行，API 为同步方法时必须实现
/// - Parameters：
///   - context：API 执行时的上下文
///   - params：API 执行时传递的参数
- (id<ThingMiniAppExtApiModelProtocol>)invokeExtApiSync:(nonnull id<ThingMiniAppExtApiContext>)context
                                                 params:(nullable NSDictionary *)params;

/// 小程序生命周期：小程序活跃状态，小程序启动时触发
- (void)onMiniAppResume;

/// 小程序生命周期：小程序暂停状态，如退到后台、小程序被其他小程序覆盖时触发
- (void)onMiniAppPause;

/// 小程序生命周期：小程序销毁状态，小程序关闭时触发
- (void)onMiniAppDestroy;

注册自定义 API

注册自定义 API 之前，需要先创建一个实体类，用于返回自定义 API 回调的数据给到前端。此实体类需要服从 ThingMiniAppExtApiModelProtocol 协议，并实现协议中提供的属性和方法。

接口说明

// 创建一个实体类，服从 ThingMiniAppExtApiProtocol 协议
TestExtApiImpl *impl = [[TestExtApi alloc] init];
[[ThingMiniAppClient developClient] addExtApiImpl:impl];

示例代码

// 返回数据给到小程序
// TestExtApiModel 服从 ThingMiniAppExtApiModelProtocol 协议
- (void)invokeExtApi:(id<ThingMiniAppExtApiContext>)context params:(NSDictionary *)params success:(ThingMiniExtApiResponseCallback)success fail:(ThingMiniExtApiResponseCallback)fail {
    if (success) {
        success([TestExtApiModel successExtApiModelWithData:@{@"key":@"value"}]);
    }
}

调用自定义 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: {}})