iOS 接入

• 小程序运行环境受限于 iOS 9.0 以上系统 WKWebView 的 API 调用，只能运行在 iOS 9.0 及以上；

• 小游戏运行环境受限于性能、API 限制等问题，只能运行在 iOS 10.0 及以上。

1. 宿主信息配置

下载宿主信息文件：union-cfg.json ，字段格式：

1
2
3
4
5
6
7
8
9
10

// 在小程序开源官方平台上（注册、登录），设置-->开发设置入口获取。
{
       "officialNo":"开源联盟成员标识",
      "containerNo":"联盟宿主app标识",
      	   "appKey":"联盟宿主app小程序标识",
         "hostName":"宿主app的名称",
       "schemeHead":"调起智能小程序的协议标识",
 "shareCallBackUrl":"分享回流URL",
          "version":"更改宿主配置版本号"
 }

在实现 BBASMPlatformAdapterProtocol 协议时，将下载的 json 内容设置到 hostConfig 接口中；每次更新开源小程序 SDK 时，宿主信息如有变动，注意修改 shareCallBackUrl、version 的值。

2. 工程信息配置

由于小程序 SDK 内部使用到了相机、相册、麦克风、定位、通讯录等权限，需要在宿主工程的 info.plist 中添加以下权限：

3. 使用 CocoaPods 集成

基于百度智能小程序 SDK 只开放给开源联盟成员，不能将 SDK 放在 CocoaPods 官网上，需要自建私有 podspec 仓库。
注：对于 gitee 上百度智能小程序开源的私有仓库权限限制，仅开放给开源联盟宿主（非百度系宿主）部分成员，便于宿主团队内部成员也能进行小程序 SDK 集成开发，在开源 demo 工程中，我们提供了代码同步宿主仓库的工具。

集成环境：

• CocoaPods 版本：1.8.4 以上版本。
• Python 版本：3.0 以上。

在宿主的工程中的 Podfile 文件中，设置百度智能小程序 SDK 依赖。

3.1 开源联盟宿主依赖配置

1
2
3
4
5
6
7
8
9
10
11
12

# 开源联盟宿主的小程序podspec私有库源（在gitee小程序下的私有仓库，宿主可将依赖源同步到自己公司下私有仓库中）
source 'https://gitee.com/baidu/swan-ios-specs.git'

# 依赖百度智能小程序SDK库，具体版本号见Changelist
# 开源联盟账号依赖库（与宿主自有账号下二选一依赖）
pod 'BBAMNPUnionLib', '2.23.0'

# 宿主自有账号下依赖库
pod 'BBAMNPLib', '2.23.0'

# 宿主有 swani-ios-runtime 源码权限的
pod 'BBAMNP', '2.23.0'

3.2 百度宿主依赖配置

1
2
3
4
5
6
7
8
9

# 百度内部小程序podspec私有库源
source 'ssh://git@icode.baidu.com:8235/baidu/searchbox-ios/swan-ios-specs'

# 依赖百度智能小程序SDK库（采用百度的passport账号），具体版本号见Changelist
# 二进制依赖
pod 'BBAMNPLib', '2.23.0'

# 源码依赖
pod 'BBAMNP', '2.23.0'

4. 入口调用

4.1 初始化小程序运行时环境

在 AppDelegate 中的“application:didFinishLaunchingWithOptions:”启动入口，注册小程序运行时环境（尽量放在这里注册，以免影响小程序启动）。

注：调用方法请在“self.window.rootViewController = ”语句后执行，防止小程序环境异常情况出现。

• 调用方法：[BBASMManager registerAppLaunchOptions:nil]; （这里不能使用 Pyramid.bba_smManager 替换 BBASMManager）

1
2
3
4
5

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    self.window.rootViewController = ...
    // launchOptions可以为nil，可以在异步队列执行
    [BBASMManager registerAppLaunchOptions:launchOptions];
}

4.2 调起小程序入口

小程序（或小游戏）以 custom scheme 协议方式调起，具体协议格式如下：

• 小程序协议格式：hostscheme://swan/appKey
• 小游戏协议格式：hostscheme://swangame/appKey

调起小程序方法：

1
2

NSString *spURL = @"baiduboxapp://swan/4fecoAqgCIUtzIyA4FAPgoyrc4oUc25c";
[Pyramid.bba_smManager openAppUrl:spURL];

如果从 APP 之外调起小程序（分享回流、 UniversalLink 等入口），需要判断是不是小程序的调起协议：

1
2
3
4
5
6
7
8
9
10

- (BOOL)application:(UIApplication *)application
            openURL:(nonnull NSURL *)url
            options:(nonnull NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    NSString *spURL = [url absoluteString];
    if ([appUrl containsString:@"://swan/"] ||
        [appUrl containsString:@"://swangame/"]) {
        [Pyramid.bba_smManager openAppUrl:spURL];
    }
    return YES;
}

扫码打开小程序，按照扫码出来的协议分两种情况：

• 扫码结果为小程序的调起协议：

1
2
3
4

if ([scanresult containsString:@"://swan/") ||
    [scanresult containsString:@"://swangame/"])  {
    [Pyramid.bba_smManager openAppUrl:scanresult];
}

• 扫码结果为开发者工具预览生成的小程序二维码 URL ，分长链（开发者工具已废弃，需要兼容）和短链（目前推行方式）。

  • 长链格式：https://smartapp.baidu.com/mappconsole/api/packagescheme
  • 短链格式：https://mbd.baidu.com/ma/s/

  宿主处理方式：

  • 小程序 SDK2.18.0 版本以前，扫码结果通过以上 URL 判断，发起 302 跳转 get 请求，在请求的 header 里面加上 Swan-Accept:swan/json、User-Agent:小程序webViewAppUA ，然后请求返回小程序调起协议。

    1 2 3 4 5 6 7 8 9 10 11 12 13

    if ([scanresult containsString:@"https://smartapp.baidu.com/mappconsole/api/packagescheme") || [scanresult containsString:@"https://mbd.baidu.com/ma/s/"]) { // 在小程序SDK2.18.0版本以前版本，需要宿主自己发请求，以NSMutableURLRequest举例： ... [request addValue:@"Swan-Accept" forHTTPHeaderField:@"swan/json"]; [request addValue:[[Pyramid.bba_smManager sharedInstance] webViewAppUA] forHTTPHeaderField:@"User-Agent"]; ... { // 请求成功 swanAppUrl = response[@"data"]; [Pyramid.bba_smManager openAppUrl:swanAppUrl]; } }

  • 在小程序 SDK2.18.0 之后版本，只需要调用小程序内部提供的方法。

    1 2 3 4

    if ([scanresult containsString:@"https://smartapp.baidu.com/mappconsole/api/packagescheme") || [scanresult containsString:@"https://mbd.baidu.com/ma/s/"]) { [[Pyramid.bba_smManager sharedInstance] generateMNPLaunchDispatcherFromURL:scanresult]; }

4.3 配置端能力描述表

从 2.17.0 版本后，前端 swan 框架在调用 NA 端能力时，使用了 canIUse 方案进行 API 是否存在的判断，这就需要依赖于 NA 端能力描述表传给 swan 框架。

4.3.1 端能力描述表生成规则：

在每个端能力（包括扩展能力）前（header 文件里面）按照端能力规范进行代码注释(可参考开源 demo 中 /SwanModule/SwanExt 下的扩展端能力)，然后通过端能力描述收集脚本生成一个总的描述表，将描述表注入到 swanjs 框架中。

4.3.2 使用端能力描述脚本：

【注意】将开源 demo 的 Script/scheme_desc_collector.py ，拷贝到宿主工程中，生成一个端能力描述文件 BBAPluginDescription.zip 文件，拷贝到宿主工程的 Resources 目录下。更新版本时，需要每次重新生成端能力描述文件，如果没有更新，会导致当前集成的 SDK 上的一些端能力无法正常使用。

4.3.3 引用端能力描述文件：

具体实现详见 Adapter 协议 – 配置：pluginDescriptionPath 接口。

4.4 集成扩展包（宿主没有扩展包，忽略）

以开源 demo 为例，宿主需要将 BBAMNPPyramid.bundle 资源拷贝到宿主工程中，自行替换自己的扩展包，结构与 demo 中提供的一致。
具体实现详见 Adapter 协议 – 配置：Extension 配置接口。

5. Adapter 协议实现

由于小程序运行时所用到能力依赖宿主 NA 端的环境，需要 NA 端实现小程序框架中提供的 Adapter 协议；按照功能完整性的必要原则分：必选集、可选集。以 BBASMPlatformAdapterProtocol 为例，实现过程：

• Adapter 协议头文件引用，继承 BBASMAdapterBaseImplement ，声明要实现的接口。实现类的.h：

1
2
3
4
5
6
7
8
9
10

#import <BBASMPlatformAdapterProtocol.h>

NS_ASSUME_NONNULL_BEGIN

// 实现类要继承BBASMPlatformImplement <BBASMPlatformAdapterProtocol>
@interface BBASMPlatformImplement : BBASMAdapterBaseImplement <BBASMPlatformAdapterProtocol>

@end

NS_ASSUME_NONNULL_END

• Adapter 协议与实现类绑定，同时还要实现 Adapter 的接口。实现类的.m：

1
2
3
4
5
6
7
8
9

@implementation BBASMPlatformImplement

// Adapter协议与实现类绑定
RegisterBBASMAdapter()

// 实现Adapter接口
...

@end

5.1 必选集

强依赖宿主的实现才能运行运行小程序。

5.2 可选集

宿主可根据自身需求实现以下这些功能接口；如果没有这些实现，一些小程序用到了这些功能，可能就无法正常在宿主 APP 上运行。

6. Extension 能力扩展

宿主会有私有端能力扩展，需要 NA 端、前端配合开发，详见扩展实现。（百度系的内部产品线，需要将开源工程 demo 下的私有能力扩展（SwanExtPlugin）拷贝到宿主工程中）

7. SDK 升级

宿主在更新小程序 SDK 时，避免不了 Adapter 协议、局部实现的变动，按照以下几步进行操作：

7.1 按更新列表升级

每一期 SDK 升级都会有对应的 changeList 说明，具体见更新列表。

7.2 更新资源文件

扩展包：BBAMNPPyramid.bundle（百度内部产品线需要做 merge 自己宿主上的扩展描述）；
描述表：需要更新端能力描述表，生成的 BBAPluginDescription.zip 。

8. CTS 测试

宿主接入（升级）小程序 SDK 完成后，宿主APP实现是否完整、可运行，可通过CTS测试进行兼容验证；CTS小程序提供为宿主提供了全集功能 case ，宿主方根据自身需求进行验证(不强求全部功能通过测试)。按照功能分为4个CTS小程序：

• API 的 appKey：PccCNGKCYawUcfCxivhfmTEuCICGK0IX_trial
• 组件的 appKey：mlxCOIFLs2SWhxifEFGLmLeRs6sdoSTo_trial
• 框架的 appKey：ADamk7kmWo8xTgZtFGeptWMYyujxKo25_trial
• 插件、动态库的 appKey：5hToyw3VvN4dGqWu32QB3Xju8URBrsxL_trial

注意事项

• 建议使用联盟账号，SDK 内已经提供默认实现；如若使用自己的账号，则需要自己实现一套 Server 体系和授权过程，比较复杂。
• 需要实现的接口，都提供了参考实现，参考开源 demo 工程：swan-ios（或者 product-mnpproject）。
• 2.19.0 之后版本的联盟登陆需要重新申请 union-cfg.json 配置文件，否则可能会出现无法登陆的情况。
• 鉴于小程序和小游戏的受 iOS 系统限制， SDK 内部已做好兼容限制，未符合运行环境的回提示“iOS 系统版本过低”；建议宿主方从入口按照 iOS 系统版本屏蔽小程序和小游戏。