iOS 接入

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

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

1. 宿主信息配置

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

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

在实现 BBASMPlatformAdapterProtocol 协议时，将下载的 json 路径设置到 hostConfigFilePath 接口中；每次更新开源小程序 SDK 时，宿主信息如有变动，注意从平台上下载下来更新本地union-cfg.json文件。

【重要】从 2.32.0 版本开始，宿主需要在开源宿主平台上，按照 APP渠道包名 补充对应线上、线下 APP 包名，补充完成后下载并更新工程中的 union-cfg.json 文件，否则小程序会打开失败。

2. 工程信息配置

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

权限	Key	说明
相机	Privacy - Camera Usage Description	使用相机的端能力：swan.camera.insert
相册	Privacy - Photo Library Usage Description	从相册选择（保存）图片：swan.chooseImage
相册	Privacy - Photo Library Additions Usage Description	保存图片（在 iOS 11 以上必须要加上）
日历	Privacy - Calendars Usage Description	向系统添加、删除日历 (swan.addEventOnCalendar、swan.deleteEventOnCalendar)
麦克风	Privacy - Microphone Usage Description	音视频录制：swan.recorder.start
通讯录	Privacy - Contacts Usage Description	获取通讯录：swan.getPhoneContacts
后台音乐	Required background modes	App plays audio or streams audio/video using AirPlay
后台定位	Required background modes	pivacy - Location When In Use Usage Description
URL Schemes 白名单	LSApplicationQueriesSchemes	openAppByURL 端能力

2.36 版本后，日历、通讯录拆分成单独的静态库，宿主可选集成，具体配置参考 Demo 。如不集成则无需配置对应权限。

3. 工程集成

【注】小程序框架支持swift混合编程，宿主工程中若无swift文件，需要增加一个空Swift文件并添加bridge-header.h，编译环境要求宿主使用Xcode 12以上版本；从SDK2.29.0版本静态库从“.a”转成“.framework”格式，注意自依赖方式BBAMNP库的引入方式。

目前提供两种方式的SDK集成方式：

• CocoaPods 方式：为宿主提供两种依赖源，由于 BBAMNP 库改成 “.framework”，执行 “pod install”，出现” xcassets 拷贝失败”，需要升级 CocoaPods 为1.10.1；（开源联盟宿主可按 gitee 仓库上进行 pod 依赖，百度内部宿主可按 icode 仓库上进行 pod 依赖）
• Easybox 方式：百度系内部宿主按照 Easybox 方式进行集成；

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

---

3.1 开源联盟宿主依赖配置

开源联盟宿主成员按照CocoaPods方式进行包依赖，具体可参考外部开源demo，进行SDK升级接入。在宿主工程中的 Podfile 文件中，设置百度智能小程序 SDK 依赖。

2.34 及以上版本，按照如下方式接入

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

// 小程序SDK，指定版本号（完整版SDK，包含小游戏。如果需要联调小程序源码，pod 'BBAMNP'）
pod 'BBAMNPLib', '2.37.0'
  
// 精简版SDK（精简版，不包含小游戏）
pod 'BBAMNPLiteLib', '2.37.0'

# 风控库（联盟账号必须依赖, 自有账号不用依赖）
pod 'SSDKLightLib', '1.1.0'

2.32 及以下版本，按照如下方式接入

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

# 开源联盟账号依赖库（与宿主自有账号下二选一依赖）
pod 'BBAMNPUnionLib', '2.32.0'

# 宿主自有账号下依赖库（源码依赖，有 swani-ios-runtime 源码权限：pod 'BBAMNP', '2.32.0'）
pod 'BBAMNPLib', '2.32.0'

外部开源宿主联盟需要申请gitee上小程序仓库访问权限：

• 小程序开源 demo 仓库；
• 小程序开源 CocoaPods 私有依赖仓库；（包含SDK）
• 小程序运行时源码仓库；(只开放签署源码协议的宿主)

3.2 百度内部宿主依赖配置

内部开源宿主联盟需要申请 iCode 上小程序仓库访问权限：

• 小程序开源 demo 仓库；
• 小程序开源 CocoaPods 私有依赖仓库；（包含SDK）
• 小程序运行时源码仓库；

3.2.1 按照CocoaPods方式

在宿主工程中的 Podfile 文件中，设置百度智能小程序 SDK 依赖。
【重要】CocoaPods 版本需要 1.10.1 及以上

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

// 小程序 SDK，指定版本号（完整版SDK，包含小游戏。如果需要联调小程序源码，pod 'BBAMNP'）
pod 'BBAMNPLib', '2.37.0'
   
// 精简版 SDK（精简版，不包含小游戏）
pod 'BBAMNPLiteLib', '2.37.0'

# 百度系扩展库（从2.28.0版本后，百度内部宿主需要引用该库）
pod 'BBAMNPBDExtension', '2.37.0'

3.2.2 按照Easybox方式

在宿主工程的 boxfile 文件中，设置小程序库以及小程序依赖库，具体依赖版本可按照对应手百的boxfile进行依赖配置。（注：小程序SDK的版本与手百boxfile设置“BBAMNP”版本是不一样的，按照对应手百boxfile的版本号进行库依赖）

小程序SDK 2.29.0 版本后框架色值表汇总到了 BBAUIKit.bundle 中

• 宿主需要在 boxfile 里加入

  post_install_resources_script "ruby ./Script/bdpappearance_colors.rb $INSTALLER_RESOURCES_FILE_LIST BBAUIKit.bundle" 

  （如果项目的 boxfile 中已配置执行 bdpappearance_colors 脚本，则无需重复添加）
• 宿主需在工程 Script 目录下加入 bdpappearance_colors.rb 脚本，脚本从 Demo 中拷贝

2.30 版本后 Demo 工程支持 Easybox ，宿主可执行 box init SwanAppDemo_Box.xcodeproj / box install 初始化并安装工程（支持 Easybox 3.0+ 版本），依赖库的版本也可以参考 Demo 中的 Boxfile

【注】

1. 开源 Demo 的 release 分支为 mnp/release/2.37.0, 宿主需要 checkout 到接入版本的 release 分支。
2. 百度系宿主需要多引入 BBAMNPBDExtension 库，具体详细介绍见百度系私有能力。
3. 2.36版本后小程序日志上报依赖 UBC，未接入 UBC 的百度系宿主必需接入并设置公参，文档参考 Tekes, 代码参考 Demo 中的 BBASMAppCommonParamsGetter 类 。

4. 入口调用

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

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

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

• 调用方法：[BBASMManager registerAppLaunchOptions:nil]; （如果Pyramid组件没有初始化，不能使用 Pyramid.bba_smManager 替换 BBASMManager）

- (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

调起小程序方法：

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

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

- (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;
}

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

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

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 ，然后请求返回小程序调起协议。

    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 之后版本，只需要调用小程序内部提供的方法。

    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。更新版本时，需要使用新版 Demo 中的端能力描述脚本生成描述表，如果没有更新，会导致当前集成的 SDK 上的一些端能力无法正常使用。

4.3.3 引用端能力描述文件：

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

5. Adapter 协议实现

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

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

#import <BBASMPlatformAdapterProtocol.h>

NS_ASSUME_NONNULL_BEGIN

// 实现类要继承 BBASMAdapterBaseImplement 并遵循对应的 <BBASMPlatformAdapterProtocol> 协议
@interface BBASMPlatformImplement : BBASMAdapterBaseImplement <BBASMPlatformAdapterProtocol>

@end

NS_ASSUME_NONNULL_END

• Adapter 协议与实现类绑定，同时还要实现 Adapter 的接口。注意一定要在@implementation下方写 RegisterBBASMAdapter() ，实现类的 .m 如下：

@implementation BBASMPlatformImplement

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

// 实现Adapter接口
...

@end

5.1 必选集

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

功能	协议（Adapter）	说明
配置	BBASMPlatformAdapterProtocol	宿主信息、extension 配置、自定义 UA
账号	BBASMAccountAdapterProtocol	登录方式：自有账号、开源联盟账号（默认：开源联盟账号，只能二选一），百度内部宿主还要必须实现BBASMBDAccountAdapterProtocol这个协议
授权	BBASMAuthorizeAdapterProtocol	授权（选择自有账号方式，需要实现该 Adapter ，百度内部产品线忽略）
视频	BBASMVideoAdapterProtocol	视频播放器（见开源 demo 实现）
分享	BBASMShareAdapterProtocol	分享：具体分享功能依赖宿主的分享渠道
支付	BBASMPaymentAdapterProtocol	支付：直连、聚合（见开源 demo 实现）

5.2 可选集

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

功能	协议（Adapter）	说明
定位	BBASMLocationAdapterProtocol	定位功能 （SDK 内部已经提供默认实现，如不满足需求宿主可进行扩展）
地图	BBASMMapAdapterProtocol	地图功能 （SDK 内部已经提供默认实现，如不满足需求宿主可进行扩展）
扫码	BBASMScanCodeAdapterProtocol	扫码（SDK 内部已经提供默认实现，如不满足需求宿主可进行扩展， 2.47 版本开始提供）
基础	BBASMUtilAdapterProtocol	小程序包解压：由于宿主集成的解压库与开源提供 SSZipArchive 库出现冲突，如果宿主不依赖 SSZipArchive（百度内部为 ZipArchive）库，需要实现该接口；默认宿主可以不实现
收货地址	BBASMShippingAddressAdapterProtocol	收货地址：自有账号需要实现（百度内部产品，需要升级 passportKit 8.78.1 以上版本） ，联盟账号不需要实现这个接口
发票	BBASMInvoiceAdapterProtocol	发票：自有账号需要实现（百度内部产品，需要升级 passportKit 8.8.4 以上版本）
直播	BBASMLiveAdapterProtocol	直播功能可参考开源demo的BBASMLiveImplement实现

6. Extension 能力扩展

宿主会有私有端能力扩展，需要 NA 端、前端配合开发，详见扩展实现。

7. SDK 升级

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

7.1 按更新列表升级

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

7.2 更新资源文件

描述表：需要更新端能力描述表 。

8. CTS 测试

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

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

---

9. 宿主开发者问题反馈平台

宿主在对接小程序 SDK 过程中，遇到技术、产品等问题，可以点页面下方反馈建议进行反馈。

注意事项

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