iOS 接入指南

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

注：接入 Open SDK 的开发者，请先认真阅读《微信 Open SDK 个人信息处理规则》及《微信 Open SDK 开发者合规使用指南》，并确保对 OpenSDK 的接入使用情况符合上述指南中的相关要求。

注意：SDK 更新日志请前往《微信 Open SDK for iOS 更新日志》查看。

关于 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 接入成功验证指引

环境要求

1. 确认微信的 Universal Links 正常

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

Safari 输入：

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

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

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

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

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

以 SDK Sample 配置为例：

{ "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 的入口提示（如下图）

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

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

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

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

SDK 接入指引

请注意红字部分配置。

1. 配置应用的 Universal Links

1）根据 苹果文档 配置你应用的 Universal Links

微信对 Universal Links 配置要求：

a）Universal Links 必须支持 https

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

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

示例：

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

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

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

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

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

3. 下载微信终端 SDK 文件

SDK 文件包括 libWeChatSDK.a、WXApi.h、WXApiObject.h 三个。如选用手动集成，请前往 资源下载页 下载最新 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，此处请参考 差异点说明。

关于 CocoaPods 的更多信息请查看 CocoaPods 官方网站。

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

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

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

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

#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，此处请参考 差异点说明。

4.2 手动集成

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

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

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

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

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

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

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

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

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

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

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

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

#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，此处请参考 差异点说明。

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

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

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

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

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

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

SceneDelegate：

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

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

-(void) onReq:(BaseReq*)req

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

-(void) onResp:(BaseResp*)resp

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

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

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

+ (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 源码。

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

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

注意事项：

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

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

3）会多次回调 block

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

示例代码：

// 在 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 值说明：

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