{"id":88,"type":"Article","title":"X-SDK iOS集成","slug":"ios-x-sdk","content":"在 iOS App 应用中，X-SDK 是一个 framework，可以通过 Pod 引入(pod 'Howxm', '版本号')，也可以直接下载SDK 包导入到项目中，在开始进行体验数据收集时，需要确保 X-SDK 已经成功集成到你的应用中。\r\n\r\n浩客 iOS SDK 支持在 Podfile 引入 SDK并完成安装pod 'Howxm', '1.5.0'\r\n\r\n浩客对 iOS 支持 Swift、Object-C、ReactNative 的调用，如果你使用了 uniapp 开发，可以查阅 [uniapp 插件集成文档](https://howxm.com/help/articles/x-sdk-uniapp)。也可以翻看浩客的 github 账户，我们准备了相关的 [demo 代码库](https://github.com/howxm#%E6%B5%A9%E5%AE%A2%E7%9A%84%E6%8A%80%E6%9C%AF%E5%8F%8B%E5%A5%BD%E6%80%A7)。\r\n\r\n**注意：支持ios11.0+  xcode11.0+**\r\n\r\n| 版本号| 描述 |ios sdk 包下载地址 | 发布时间 |\r\n| -------- | -------- | -------- |-------- |\r\n| 1.5.1     |增加dsyms文件；优化identify逻辑；修复bug避免crash\t | [https://static.howxm.com/sdks/ios/1.5.1/Howxm.zip](https://static.howxm.com/sdks/ios/1.5.1/Howxm.zip)   | 2025-03-04   |\r\n| 1.5.0     |极大地优化SDK网络请求，丰富了debug模式的日志\t | [https://static.howxm.com/sdks/ios/1.5.0/Howxm.zip](https://static.howxm.com/sdks/ios/1.5.0/Howxm.zip)   | 2023-11-14   |\r\n| 1.4.0     |支持Swift、 Object-C、ReactNative 调用 | [https://static.howxm.com/sdks/ios/1.4.0/Howxm.zip](https://static.howxm.com/sdks/ios/1.4.0/Howxm.zip)   | 2023-08-01   |\r\n\r\n\r\n# 1. IOS集成操作步骤\r\n\r\n## **Step 1：创建 iOS App 应用**\r\n创建应用时，选择应用类型「iOS」，并完善应用信息，包括应用名称（必填）及App Bundle ID（非必填）。\r\n![](https://help-assets.jinshuju.net/assets/file/1257/WeChatWorkScreenshot_f4ea0e88-d636-46ec-82c1-0c49aa106d2a.png)\r\n\r\n## **Step2：复制SDK代码进行集成**(示例均以 Swift 为例)\r\n在创建完成iOS应用后，可以在左侧「应用设置」里，可以找到SDK代码，通过 Podfile 引入浩客SDK\r\n![](https://help-assets.jinshuju.net/assets/file/1475/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_cf0b3df7-1c95-4923-968d-a0cbb1c3057f.png)\r\n\r\n\r\n**注意： initializeSDK 尽可能越早的调用，其他的API都依赖该API**\r\n![](https://help-assets.jinshuju.net/assets/file/1477/%E4%BC%81%E4%B8%9A%E5%BE%AE%E4%BF%A1%E6%88%AA%E5%9B%BE_8e6ac10c-32f3-4aef-b1bc-de30ed0c97ab.png)\r\n\r\n\r\n**iOS App 集成示例代码：**\r\n\r\n```swift\r\nimport Howxm\r\n...\r\nHowxm.initializeSDK(\r\n        your appId,\r\n        yourViewController,\r\n        {\r\n           //initializeSDK success callack \r\n           Howxm.identify(Customer(\"当前用户的唯一ID (required)\",  \"张三\",\r\n\t\t\t\t\t          \"zhangsan@howxm.com\", \"13000000000\", [\"birthday\": \"2000-01-02\"]), {\r\n                         //identify success callback\r\n                      }, {\r\n                         //identify failed calback\r\n            })\r\n        }\r\n \r\n```\r\n\r\n**注意：该代码只可应用于所绑定的 iOS App，在进行集成之前，请确认应用ID是否正确。**\r\n\r\n**获取应用ID**\r\n\r\n你可以在 **应用设置-App 设置** 中直接复制应用ID。\r\n\r\n\r\n## **Step3：验证 SDK 集成是否生效**\r\n在完成第二步 SDK 代码集成后，你可以访问所集成 X-SDK 代码的App应用，就可以看到 X-SDK 集成的状态变为   绿色  ，点击会提示App连通中，可以对评价、问卷进行正常投放。\r\n![](https://help-assets.jinshuju.net/assets/file/1260/WeChatWorkScreenshot_d5dfd602-a6d3-4b5a-94d2-9cfea9463cf4.png)\r\n否则你将会看到「App 未连通」的红色提醒：\r\n![](https://help-assets.jinshuju.net/assets/file/1259/WeChatWorkScreenshot_e604617d-5496-41ca-8b4c-27c897e28fba.png)\r\n\r\n需要检查SDK代码是否正确安装，或者确认应用绑定的应用ID是否正确。\u003cbr\u003e\r\n\r\n**注意：如果在72小时内，X-SDK没有收到来自目标App的访问数据时，也会出现「App 未连通」的提醒，你可以再次进入App应用，状态即可恢复。**\r\n\r\n\r\n## **Step 4：投放问卷、评价，回收数据**\r\n当 SDK 集成完毕，即可使用浩客评价、问卷等相关能力；也可以邀请团队成员加入到你的应用中，协作进行管理。\u003cbr\u003e\r\n\r\n* [创建一个评价](https://howxm.com/help/articles/create-feedback)\r\n* [创建一个问卷](https://howxm.com/help/articles/create-survey)\r\n* [邀请团队成员加入](https://howxm.com/help/articles/apps-team)\r\n\r\n----------\r\n# 2. IOS支持语言\r\n -  **iOS SDK 支持 Swift、Objective-C 以及 ReactNative**，文章下方所有示例代码均以 Swift 为准，其他示例代码参考github 上放置的demo repo 点击下方对应链接进行访问\u003cbr\u003e\r\n - [Swift](https://github.com/howxm/howxm-ios-swift-demo) \u003cbr\u003e\r\n - [Objective-C] (https://github.com/howxm/howxm-ios-OC-demo) \u003cbr\u003e\r\n - [ReactNative] (https://github.com/howxm/howxm-RN-demo) \u003cbr\u003e\r\n\r\n----------\r\n# 3. X-SDK 接口能力\r\n\r\n**X-SDK 的接口信息、参数、使用场景，请先查看**  [接口文档](https://howxm.com/help/articles/x-sdk-api) \r\n\r\n在完成 X-SDK 集成后，可以使用相关接口能力进行用户身份验证、复杂的免打扰机制，完成更加复杂的场景，比如：\u003cbr\u003e\r\n\r\n* 传入用户身份信息，实现复杂的免打扰机制，以及对于人群的定向投放\r\n* 传入扩展属性信息，用于对某些场景的识别，获得更加细分的数据洞察\r\n* 手动弹出评价/问卷，用于用户完成某些动作后的，精准投放等\r\n\r\n以下为 X-SDK 所具备的接口，参数类型请参考 [接口文档](https://howxm.com/help/articles/x-sdk-api)\r\n请确保已经阅读并且理解 [X-SDK的整体介绍](https://howxm.com/help/articles/x-sdk-intro)\u003cbr\u003e\r\n**下方示例代码均以 Swift 为例**\r\n\r\n## **3.1 identify 用户身份信息传递**\r\n\r\n接口信息，详细可查看：[identify](https://howxm.com/help/articles/x-sdk-api#1-identify)\r\n\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```swift\r\n// uid is required, extraAttributes 可以传入其他用户属性，例如生日、会员等级、套餐信息等等。属性以 key:value 的形式传入，目前支持数字、字符串、日期类型的数据\r\nHowxm.identify(Customer(\"uid (required)\", \"张三\",  \"zs@howxm.com\", \"13000000000\", [\"age\": 18]), {\r\n       // success callback\r\n}, {\r\n      // failed calback\r\n})\r\n\r\n```\r\n\u003cbr\u003e\r\n\r\n## **3.2 event 抛出事件接口**\r\n\r\n接口信息，详细可查看：[event](https://howxm.com/help/articles/x-sdk-api#2-event)\r\n\r\n\r\n```swift\r\n// 接口定义\r\nHowxm.event(code, attributes,\r\n yourViewController, // 可选，默认使用initializeSDK中传入的viewController\r\n {\r\n  // success callback\r\n }, { \r\n  // failed callback\r\n })\r\n\r\n// Example\r\nHowxm.event(\"payment_click\", [\"product\": \"pro\", \"price\": 9],\r\n nil,\r\n {\r\n  // success callback\r\n }, { (message: String?) in\r\n  // failed callback\r\n })\r\n \r\n```\r\n**注意：当触发方式为「通过传入事件触发」时，投放规则自动生效。**\u003cbr\u003e\r\n\r\n\r\n## **3.3 checkOpen 弹出策略检查接口**\r\n\r\n接口信息，详细可查看：[checkOpen](https://howxm.com/help/articles/x-sdk-api#3-checkopen)\r\n\r\ncheckOpen 接口会基于用户uid和免打扰策略来判断，是否需要给用户弹框显示问卷组件\u003cbr\u003e\r\n\r\n\u003cbr\u003e\r\n以下为示例代码：\u003cbr\u003e\r\n\r\n```swift\r\nHowxm.checkOpen(\"campaignId\", \"用户uid\", {\r\n   // success callback\r\n }, {\r\n // 表示当未通过投放规则校验，投放失败\r\n  // failed callback\r\n })\r\n \r\n```\r\n\u003cbr\u003e\r\n**传入参数说明:**\u003cbr\u003e\r\n\u003cbr\u003e\r\n\r\n| **字段**     | **说明** | **是否必填** | **类型**    | **备注**      |\r\n|------------|--------|----------|-----------|-------------|\r\n| campaignId | 问卷/评价ID   | 必填       | String 类型 | 某个问卷/评价ID，请从该问卷/评价的设置中获取 |\r\n| uid        | 用户id   | 必填       | String 类型 | 用于识别唯一用户身份  |\r\n\r\n\r\n## **3.4 open 弹出问卷接口**\r\n\r\n接口信息，详细可查看：[open](https://howxm.com/help/articles/x-sdk-api#4-open)\r\n\r\n\r\n```swift\r\n// customer 选填, 不传默认使用identify 中认证的用户，未identify则为匿名用户\r\n// inViewController 选填，默认使用initializeSDK中传入的inViewController\r\n// extra 选填，其他属性\r\nHowxm.open(\"campaignId\", Customer(\"用户uid\"), [\"a\": 1],  inViewController); // campaignId可以通过问卷、评价操作栏中「获取问卷ID」/「获取评价ID」进行获取\r\n \r\n```\r\n\r\n**注意：当触发自动弹出方式为「通过代码调用 Open 触发」时，建议代码调用 checkOpen 判断免打扰检测是否通过**\u003cbr\u003e\r\n\r\n```swift\r\nHowxm.checkOpen(\"campaignId\", \"用户uid\", {\r\n   // success callback \r\n   // 通过投放规则校验, 打开弹框\r\n   Howxm.open(\"campaignId\")\r\n }, {\r\n // 表示当未通过投放规则校验，投放失败\r\n  // failed callback\r\n })\r\n \r\n```\r\n\r\n## **3.5 register 注册事件回调**\r\n通过此方法可注册全局回调事件，在问卷展示和回收过程的不同阶段进行自定义处理。调用方法如下：\r\n\r\n```\r\nHowxm.onBeforeOpen({campaignId, uid, extraAttributes in\r\n\tlet message = \"OnBeforeOpen:campaignId = \\(campaignId),uid = \\(uid ?? \"未设置\"),extraAttributes = \\(String(describing: extraAttributes))\"\r\n\tprint(message)\r\n})\r\n\r\nHowxm.onOpen({campaignId, uid, extraAttributes in\r\n\tlet message = \"OnOpen:campaignId = \\(campaignId),uid = \\(uid ?? \"未设置\"),extraAttributes = \\(String(describing: extraAttributes))\"\r\n\tprint(message)\r\n})\r\n\r\nHowxm.onPageComplete({campaignId, uid, fieldsEntry in\r\n\tlet message = \"OnPageComplete:campaignId= \\(campaignId) and uid = \\( uid ?? \"未设置\") and fieldsEntry = \\(String(describing: fieldsEntry))\"\r\n\tprint(message)\r\n})\r\n\t\t\t\t\t\t\r\nHowxm.onComplete({campaignId, uid in\r\n\tlet message = \"OnComplete:campaignId= \\(campaignId) and uid = \\( uid ?? \"未设置\")\"\r\n\tprint(message)\r\n})\r\n\r\nHowxm.onClose({campaignId, uid in\r\n\tlet message = \"OnClose:campaignId= \\(campaignId) and uid = \\( uid ?? \"未设置\")\"\r\n\tprint(message)\r\n})\r\n\r\n```\r\n\r\n回调阶段定义\r\n\r\n| 名称                            | 说明                                                       |\r\n|--------------------------|---------------------------------------------|\r\n| onBeforeOpen            | 问卷展示前调用                                    |\r\n| onOpen                      | 问卷展示后调用                                     |\r\n| onClose                      | 问卷在屏幕消失后调用                          |\r\n| onComplete               | 用户提交了最后一页题目后调用            |\r\n| onPageComplete       | 用户每提交一页，系统调用一次            |\r\n\r\n","featured":false,"category_id":4,"created_at":"2023-07-26T09:22:38.359Z","updated_at":"2025-03-05T07:21:38.977Z"}