# iOS 接入指南

微信 Open SDK for iOS 是微信开放平台面向 iOS 端第三方应用提供的开发工具包，支持分享与收藏、微信登录、微信支付等能力。本文档介绍 Open SDK 在 iOS 端的接入与使用方法。

**注：接入 Open SDK 的开发者，请先认真阅读[《微信 Open SDK 个人信息处理规则》](https://support.weixin.qq.com/cgi-bin/mmsupportacctnodeweb-bin/pages/RYiYJkLOrQwu0nb8)及[《微信 Open SDK 开发者合规使用指南》](/doc/oplatform/Mobile_App/agreement/sdk)，并确保对 OpenSDK 的接入使用情况符合上述指南中的相关要求。**

注意：SDK 更新日志请前往[《微信 Open SDK for iOS 更新日志》](/doc/oplatform/Mobile_App/Downloads/iOS_Resource)查看。

## 关于 OpenSDK 1.8.6 及以上版本的更新说明

由于苹果 iOS 13 系统版本安全升级，为此 OpenSDK 在 1.8.6 及以上版本进行了适配。1.8.6 及以上版本支持 Universal Links 方式跳转，对 OpenSDK 分享进行合法性校验。

建议开发者接入新版本 SDK，覆盖测试微信 7.0.7 或以上版本、iOS 12 或 13，以验证所使用的接口的功能性和可用性。

**目录**

- SDK 接入成功验证指引
- SDK 接入指引
- 使用 SDK 自检函数排查接入问题

## 关于老版本 OpenSDK 中使用的 openUrl 接口说明

- 由于老版本 SDK 中使用的 openUrl 接口为系统废弃接口，如开发者在 iOS 18 升级 Xcode 16 进行打包，则会偶现 SDK 无法拉起微信的问题
- 该问题已经在 2.0.4 的版本换新接口。因此，请近期有发版计划的开发者及时更新到 2.0.4，避免影响用户日常使用

## SDK 接入成功验证指引

**环境要求**

| 项目 | 要求 |
| :--- | :--- |
| SDK 版本 | 1.8.6 或以上 |
| 微信版本 | 7.0.7 或以上 |
| 系统版本 | iOS 12 或以上 |

### 1. 确认微信的 Universal Links 正常

首先，确认微信（7.0.7 或以上版本）的 Universal Links 在设备上正常，以确保 OpenSDK 与微信双向使用 Universal Links 通信。

Safari 输入：

```
https://help.wechat.com/app/
```

下拉查看是否有打开微信入口（如下图）。若无入口，可能是由于系统拉取微信 Universal Links 失败，请检查手机网络状态是否正常，或更新/重装微信。

![](https://res.wx.qq.com/op_res/YzQUzALXcrrPKJytteq1UWVZ1uDnVyE7l-Db7RUl8k1gWmV_yfbTQ7Ppcy6ZHGKE)

### 2. 确认 App 的 Universal Links 配置成功

微信使用第三方 App 的 Universal Links 唤起第三方 App 时，会在 Universal Links 末尾拼接路径和参数，因此开发者 Universal Links 配置必须加上**通配符**，并测试 Universal Links 拼接字符串能否唤起 app。

**建议 Universal Links 配置 path，例如 `/app/*`，避免全域命中 Universal Links 跳转。**

以 SDK Sample 配置为例：

```json
{ "appID": "teamID.com.tencent.xin.SDKSample", "paths": ["/sdksample/*"] }
```

**测试配置是否成功：**

1）Safari 输入 Universal Links（包括完整路径）+ 随机字符串（例如：abc）

SDK Sample 的 Universal Links：

```
https://help.wechat.com/sdksample/
```

测试输入 Safari 的 Universal Links：

```
https://help.wechat.com/sdksample/abc
```

2）下拉页面检查是否有打开 app 的入口提示（如下图）

![](https://res.wx.qq.com/op_res/LIP8n0ettnbQjXVELUmLx-T2iMXF8oZPcwgD2248WJWNm0X6QYEQ_3kgq7r28WxC)

### 3. 连续发起分享，确认不会发生多次二次跳转行为

当用户首次使用新版本 SDK 发起分享时，将会出现如下交互流程：从 App 拉起微信 → 出现「正在连接」页面 → 返回 App → 重新打开微信。以上是新的安全验证流程，每个用户在首次使用时会出现上述跳转。（如同一用户多次使用分享都出现跳转，请按照以下接入指引，检查 Universal Links 配置）

![](https://res.wx.qq.com/op_res/y0pPDN_HPoNM7hzdSg0TpYHOUpE0hdrjMDp0npt9uJGOVIGtPZJhs1nLHilL2uiW)

### 4. 如 App 有使用微信授权登录功能，确认授权不出现二次确认弹窗

授权登录如出现以下二次确认弹窗，原因是微信无法通过 App 提供的 Universal Links 返回导致，很可能是 App 的 Universal Links 不生效，请按照接入指引检查 Universal Links 配置。

![](https://res.wx.qq.com/op_res/NbExOUOU6mnXhHgKmC226gLCVb5pA71c6drDJC0Jd5cePiLmbKCUKc7bgzzZgxn-)

## SDK 接入指引

请注意红字部分配置。

### 1. 配置应用的 Universal Links

**1）根据 [苹果文档](https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content) 配置你应用的 Universal Links**

微信对 Universal Links 配置要求：

a）Universal Links 必须支持 https

b）Universal Links 配置的 paths 不能带 query 参数

c）微信使用 Universal Links 拉起第三方 App 时，会在 Universal Links 末尾拼接路径和参数，因此 App 配置的 paths 必须加上通配符 `/*`

示例：

```json
{
    "appID": "8P7343TG54.com.tencent.xin.SDKSample",
    "paths": ["/sdksample/*"]
}
```

**2）打开 Associated Domains 开关，将 Universal Links 域名加到配置上**

![](https://res.wx.qq.com/op_res/jQLkVJeF8fvx6h9gxdkxBVOqNHxKUZBWTLmWnQuPlS-WUaqu7oZMLqlS8CTsKSEg)

**3）检查确认 App 的 Universal Links 配置成功**，通过上述 SDK 接入成功验证指引 操作。

### 2. 向微信注册你的应用程序 id 和 Universal Links

请到 [开发者应用登记页面](https://open.weixin.qq.com) 进行登记，登记并选择移动应用进行设置后，将获得 AppID，可立即用于开发。但应用登记完成后还需要提交审核，只有审核通过的应用才能正式发布使用。

### 3. 下载微信终端 SDK 文件

SDK 文件包括 `libWeChatSDK.a`、`WXApi.h`、`WXApiObject.h` 三个。如选用手动集成，请前往 [资源下载页](/doc/oplatform/Mobile_App/Downloads/iOS_Resource) 下载最新 SDK 包。

### 4. 搭建开发环境

#### 4.1 通过 CocoaPods 集成

1）在 Xcode 中建立你的工程。

2）在工程的 Podfile 里面添加以下代码：

```
pod 'WechatOpenSDK-XCFramework'
```

保存并执行 `pod install`，然后用后缀为 .xcworkspace 的文件打开工程。

注意：命令行下执行 `pod search WechatOpenSDK-XCFramework`，如显示的版本不是最新的，则先执行 `pod repo update` 操作更新本地 repo 的内容。

*若接入 .a 静态库版本的 OpenSDK，此处请参考 [差异点说明](iOS_Static_Library_Difference)。*

关于 CocoaPods 的更多信息请查看 [CocoaPods 官方网站](https://cocoapods.org/)。

3）在 Xcode 中，选择你的工程设置项，选中「TARGETS」一栏，在「info」标签栏的「URL type」添加「URL scheme」为你所注册的应用程序 id（如下图所示）。

![](https://res.wx.qq.com/op_res/ohBULcCbr3PPan9SwnrNM6fEr-4kGDn98NenybClk1-fZE2rRYqU6xJCyVIMoFo9)

**4）在 Xcode 中，选择你的工程设置项，选中「TARGETS」一栏，在「info」标签栏的「LSApplicationQueriesSchemes」添加 `weixin`、`weixinULAPI`、`weixinURLParamsAPI`（如下图所示）。**

经验证，在 iOS 15 系统上，使用 Xcode 13 编译出的 App，`LSApplicationQueriesSchemes` 的数量会限制为 50 个。第 50 个之后的 scheme 配置会不生效，需要确保 `weixin`、`weixinULAPI` 和 `weixinURLParamsAPI` 配置在 `LSApplicationQueriesSchemes` 的前 50 个。

![](https://res.wx.qq.com/op_res/UA9NqONywI8DFeIMFMdND1tBAozE7hWe0fnrY88k68I0Rqq6Q60XCm2ZG9I7PfuzQIqbdsHIdVDiMjRPafZTig)

5）在你需要使用微信终端 API 的文件中 import `WXApi.h` 头文件，并增加 `WXApiDelegate` 协议。

```objective-c
#import <UIKit/UIKit.h>
#import <WechatOpenSDK/WXApi.h> // （SDK 版本 >= 2.0.5）
// #import <WXApi.h> // 旧版本 SDK 的导入方式（SDK 版本 < 2.0.5）

@interface AppDelegate : UIResponder<UIApplicationDelegate, WXApiDelegate>

@property (strong, nonatomic) UIWindow *window;

@end
```

*若接入 .a 静态库版本的 OpenSDK，此处请参考 [差异点说明](iOS_Static_Library_Difference)。*

#### 4.2 手动集成

1）在 Xcode 中建立你的工程。

2）将 `WechatOpenSDK-XCFramework.xcframework` 文件添加到你所建的工程中（如下图所示，建立了一个名为 Test 的工程，并把以上文件添加到 Test 文件夹下）。

（注：请使用 Xcode 4.5 及以上版本）

![](https://res.wx.qq.com/op_res/XD7ZOZsdOef2a90Nmj44o3X4aZni1xJHEBIYBbl1piDdjwil2eD3Gy2HQJapjEiNrktUiP2CXI45aUOftlgLGQ)

添加完成后，在 Xcode 中，选择你的工程设置项，选中「TARGETS」一栏，能够看到「General」下的「Frameworks, Libraries, and Embedded Content」和「Build Phases」下的「Link Binary With Libraries」中有 `WechatOpenSDK-XCFramework.xcframework`。

![](https://res.wx.qq.com/op_res/XD7ZOZsdOef2a90Nmj44_GBmMHYW8VC4nQ2w9fHbJcIKDw8GslqWiCFRgyK6cREf1Y5tzZt7hZ3zRBd7WQHIQ)

![](https://res.wx.qq.com/op_res/XD7ZOZsdOef2a90Nmj44oxrjTWmgFUsaVXZuEmb8rMxfQqxpTrwtKA9vo8yMzKGKRy-RW43il_8l1YgNSx0vHg)

*若接入 .a 静态库版本的 OpenSDK，此处请参考 [差异点说明](iOS_Static_Library_Difference)。*

3）开发者需要在工程中链接上：`Security.framework`、`CoreGraphics.framework`、`WebKit.framework`。

4）在你的工程文件中选择「Build Setting」，在「Other Linker Flags」中加入 `-ObjC -all_load`。

（注：请使用 Xcode 4.5 及以上版本）

![](https://res.wx.qq.com/op_res/e8KPBRtMUrhRpA3aqUWbVGU-oJJWzkKmtQxaZFUHCgZiVLBASlqZp-JMsNqHyfng)

5）在 Xcode 中，选择你的工程设置项，选中「TARGETS」一栏，在「info」标签栏的「URL type」添加「URL scheme」为你所注册的应用程序 id（如下图所示）。

![](https://res.wx.qq.com/op_res/NFS7xqSfwkeorZKhFhAaA5JlwLGitxOtyG9c6F2UfF6nggDUCq7zzVW0cq0mOmVq)

**6）在 Xcode 中，选择你的工程设置项，选中「TARGETS」一栏，在「info」标签栏的「LSApplicationQueriesSchemes」添加 `weixin`、`weixinULAPI`、`weixinURLParamsAPI`（如下图所示）。**

![](https://res.wx.qq.com/op_res/UA9NqONywI8DFeIMFMdND1tBAozE7hWe0fnrY88k68I0Rqq6Q60XCm2ZG9I7PfuzQIqbdsHIdVDiMjRPafZTig)

经验证，在 iOS 15 系统上，使用 Xcode 13 编译出的 App，`LSApplicationQueriesSchemes` 的数量会限制为 50 个。第 50 个之后的 scheme 配置会不生效，需要确保 `weixin`、`weixinULAPI` 和 `weixinURLParamsAPI` 配置在 `LSApplicationQueriesSchemes` 的前 50 个。

7）在你需要使用微信终端 API 的文件中 import `WXApi.h` 头文件，并增加 `WXApiDelegate` 协议。

```objective-c
#import <UIKit/UIKit.h>
#import <WechatOpenSDK/WXApi.h> // （SDK 版本 >= 2.0.5）
// #import <WXApi.h> // 旧版本 SDK 的导入方式（SDK 版本 < 2.0.5）

@interface AppDelegate : UIResponder<UIApplicationDelegate, WXApiDelegate>

@property (strong, nonatomic) UIWindow *window;

@end
```

*若接入 .a 静态库版本的 OpenSDK，此处请参考 [差异点说明](iOS_Static_Library_Difference)。*

### 5. 在代码中使用开发工具包

1）要使你的程序启动后微信终端能响应你的程序，必须在代码中向微信终端注册你的 id。（如下所示，在 AppDelegate 的 `didFinishLaunchingWithOptions` 函数中向微信注册 id）。

```objective-c
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // 向微信注册
    [WXApi registerApp:APP_ID universalLink:UNIVERSAL_LINK];
    return YES;
}
```

2）重写 AppDelegate 的 `handleOpenURL` 和 `openURL` 方法：

```objective-c
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url {
    return  [WXApi handleOpenURL:url delegate:self];
}

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    return [WXApi handleOpenURL:url delegate:self];
}
```

**3）重写 AppDelegate 或 SceneDelegate 的 `continueUserActivity` 方法：**

注意：适配了 SceneDelegate 的 App，系统将会回调 SceneDelegate 的 `continueUserActivity` 方法，所以需要重写 SceneDelegate 的该方法。

AppDelegate：

```objective-c
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void(^)(NSArray<id<UIUserActivityRestoring>> * __nullable restorableObjects))restorationHandler {
    return [WXApi handleOpenUniversalLink:userActivity delegate:self];
}
```

SceneDelegate：

```objective-c
- (void)scene:(UIScene *)scene continueUserActivity:(NSUserActivity *)userActivity {
    [WXApi handleOpenUniversalLink:userActivity delegate:self];
}
```

4）现在，你的程序要实现和微信终端交互的具体请求与回应，因此需要实现 `WXApiDelegate` 协议的两个方法：

```objective-c
-(void) onReq:(BaseReq*)req
```

> 是微信终端向第三方程序发起请求，要求第三方程序响应。第三方程序响应完后必须调用 `sendRsp` 返回。在调用 `sendRsp` 返回时，会切回到微信终端程序界面。

```objective-c
-(void) onResp:(BaseResp*)resp
```

> 如果第三方程序向微信发送了 `sendReq` 的请求，那么 `onResp` 会被回调。`sendReq` 请求调用后，会切到微信终端程序界面。

具体在此两方法中所要完成的内容由你定义，具体可参考微信开发工具包中的 SDK Sample Demo 源码。

5）如果你的程序要发消息给微信，那么需要调用 WXApi 的 `sendReq` 函数：

```objective-c
+ (void)sendReq:(BaseReq *)req completion:(void (^__nullable)(BOOL success))completion;
```

> 其中 req 参数为 `SendMessageToWXReq` 类型。

> 需要注意的是，`SendMessageToWXReq` 的 `scene` 成员：如果 scene 填 `WXSceneSession`，消息会发送至微信的会话内；如果 scene 填 `WXSceneTimeline`，消息会发送至朋友圈；如果 scene 填 `WXSceneFavorite`，消息会发送到「我的收藏」中。scene 默认值为 `WXSceneSession`。

至此，你已经能使用微信终端 SDK 的 API 内容了。如果想更详细了解每个 API 函数的用法，请查阅官网 API 文档或自行下载阅读 [微信 SDK Sample Demo 源码](https://open.weixin.qq.com/zh_CN/htmledition/res/dev/download/sdk/WeChatSDK_sample_iOS_1.4.2.1.zip)。

## 使用 SDK 自检函数排查接入问题

SDK **1.8.7** 版本，WXApi 新增了自检函数 `checkUniversalLinkReady:`，帮助开发者排查 SDK 接入过程中遇到的问题。

**注意事项：**

1）调用自检函数之前必须要先调用 `registerApp:universalLink` 接口，并确认调用成功

2）自检过程中会有 Log 产生，可以先调用 `startLogByLevel` 函数，根据 Log 排查问题

3）会多次回调 block

4）仅用于新接入 SDK 时调试使用，请勿在正式环境中调用

**示例代码：**

```objective-c
// 在 register 之前打开 log，后续可以根据 log 排查问题
[WXApi startLogByLevel:WXLogLevelDetail logBlock:^(NSString *log) {
    NSLog(@"WeChatSDK: %@", log);
}];

// 务必在调用自检函数前注册
[WXApi registerApp:APP_ID universalLink:UNIVERSAL_LINK];

// 调用自检函数
[WXApi checkUniversalLinkReady:^(WXULCheckStep step, WXCheckULStepResult* result) {
    NSLog(@"%@, %u, %@, %@", @(step), result.success, result.errorInfo, result.suggestion);
}];
```

**WXULCheckStep 值说明：**

| Step | 说明 |
| :--- | :--- |
| `WXULCheckStepParams` | 参数检查 |
| `WXULCheckStepSystemVersion` | 当前系统版本检查 |
| `WXULCheckStepWechatVersion` | 微信客户端版本检查 |
| `WXULCheckStepSDKInnerOperation` | 微信 SDK 内部操作检查 |
| `WXULCheckStepLaunchWechat` | App 拉起微信检查 |
| `WXULCheckStepBackToCurrentApp` | 由微信返回当前 App 检查 |
| `WXULCheckStepFinal` | 最终检查 |

会依次回调这 7 个 step，当回调了 `WXULCheckStepFinal`，说明检测通过，SDK 接入成功。任一 step 回调的 `result.success` 为 NO，流程终止，后续不再回调，可以根据 `result.errorInfo` 查看当前步骤错误的原因，根据 `result.suggestion` 修复问题。