iOS-SDK 接入 · 小鹅云文档

# **小鹅通原生SDK- iOS端接入指南** 小鹅通 SDK 依托于 XEWebView 来进行页面展示. 类似 UIWebView, 传入店铺页面地址，就可以进行完整的商品展示购买流程。具体可参考 DEMO。 <br/> <font color='red'>**iOS App中课程支付必须接入iOS代币支付方案，因苹果对于虚拟产品有收取“苹果税”的规则，如不遵守会有下架风险**</font> [详细了解请点击](recall_scene/lnline_sdk/business/pay.md) <br/> ### **1.前置条件** * 注册使用小鹅店铺，取得店铺app\_id。 * 购买小鹅店铺sdk接入服务，取得client\_id。 #### **1.1 SDK相关参数名词解释** | **参数名** | **描述** | **备注** | | --- | --- | --- | | app\_id | 店铺id | 小鹅店铺的店铺id，在管理台获取 | | client\_id | sdk客户端ID（对应Client ID） | 开通sdk服务后在管理台获取 | | secret\_key | 店铺配置安全密钥 | 开通sdk服务后在管理台获取 | #### **1.2 SDK-URL链接配置规则说明** | **参数名** | **规则说明** | **备注** | | --- | --- | --- | | 店铺首页 | [https://{{app\_id}}.h5.xiaoeknow.com](https://%7B%7Bapp_id%7D%7D.h5.xiaoeknow.com/) | 动态参数 app\_id：小鹅店铺id | | 其他页面 | 通过小鹅店铺管理台以下路径：“课程管理-图文(课程类型，以图文为例)-点击某个具体的课程分享按钮-点击复制按钮”得到链接：[https://appidxxxxxx.h5.xiaoeknow.com/v1/course/text/i\_5e7f809dd6317\_qSMuUoAi?type=2SDK](https://appidxxxxxx.h5.xiaoeknow.com/v1/course/text/i_5e7f809dd6317_qSMuUoAi?type=2SDK)展示链接需要替换链接域名部分为{{app\_id}}.h5.xiaoeknow ,例如，您的appid参数为”apprnDA0ZDw4581”，那么适配SDK展示的链接如下:[https://apprnDA0ZDw4581.h5.xiaoeknow.com/v1/course/text/i\_5e7f809dd6317\_qSMuUoAi?type=2](https://apprnDA0ZDw4581.h5.xiaoeknow.com/v1/course/text/i_5e7f809dd6317_qSMuUoAi?type=2) | 动态参数 “appXXXXXXXXXX”:需动态替换为您的小鹅店铺id | ## **2\. 接入要求** * iOS 8.0 或更高 * Xcode 9.0 或更高版本（建议使用最新版本） ## **3\. 接入流程** [Github链接](https://github.com/xiaoeteam/XiaoeAppSDK-iOS) 推荐使用 CocoaPods 导入 framework。如有特殊需求，也可以手动导入。 #### **3.1 CococaPods 导入** 在你的 Podfile 文件中加入一行： ~~~ pod 'XEShopSDK' ~~~ 运行 pod install #### **3.1 手动导入** XEShopSDK.framework 加入到工程将对应的 framework 添加到 Embedded Binaries 中 ⚠️注意：需要在 Build Settings 的 Other Linker flags 加上 -ObjC ### **3.2 配置 Info.plist 中的权限** ~~~ <key>NSCameraUsageDescription</key> <string>请允许访问您的相机</string> <key>NSPhotoLibraryAddUsageDescription</key> <string>请允许保存图片到相册</string> <key>NSPhotoLibraryUsageDescription</key> <string>请允许访问您的相册</string> <key>NSMicrophoneUsageDescription</key> <string>请允许访问您的麦克风</string> <key>UIRequiredDeviceCapabilities</key> ~~~ 为了能够拉起微信支付，你需要配置如下 ~~~ <key>LSApplicationQueriesSchemes</key> <array> <string>weixin</string> </array> ~~~ ### **3.3 配置 app scheme（微信支付完成后跳转回App，无支付可忽略）** 然后通过 XEConfig 将 scheme 传递给 SDK。 ⚠️只有配置了 Scheme, 并正确调用 SDK 的对应方法，微信支付完成后才能正确跳转回到你的 app 中。 ### **3.4 初始化 SDK** 使用 SDK 前需要先初始化。 ~~~ // 生成一个配置对象从小鹅通申请的 clientId，appId 从小鹅通申请的店铺 Id XEConfig *config = [[XEConfig alloc] initWithClientId:clientId appId: APPID] config.scheme = SCHEME; // 配置 scheme 以便微信支付完成后跳转 config.enableLog = NO; // 关闭 sdk 的 log 输出 [XESDK.shared initializeSDKWithConfig:conf]; // 使用配置初始化 SDK ~~~ ### **3.5 界面展示** 使用 XEWebView 来展示店铺界面 ~~~ ... // 初始化 XEWebView，纯代码或者 Storyboard self.webView.noticeDelegate = self; // 实现代理方法，监听相关的通知 // 加载链接 [self.webView loadRequest:urlRequest]; ~~~ ### **3.6 认证** #### **3.6.1 同步认证信息** 登录后获取认证信息。同步给 SDK 的方法如下： ~~~ - (void)synchronizeCookieKey:(nullable NSString *)key cookieValue:(nullable NSString *)value; ~~~ ⚠️注意，接受到下文回调 XENoticeTypeLogin 时，应从通过您的App后台到小鹅云获取最新token并使用此方法同步到sdk内部 #### **3.6.2 清除认证信息** 在您的 App 内发生用户切换或用户退出的时, 为了避免出现客户信息混乱, 请务必执行如下代码登出小鹅通用户角色. 代码示例: ~~~ - (void)logout; ~~~ ### **3.7 接收回调事件** 当遇到需要登陆才可以访问的页面，会触发下面的回调，此时去获取登录态信息，并同步给 SDK。（⚠️强烈建议在展示XEWebView前同步token到sdk中，以避免异步同步token方法导致用户体验不佳） ~~~ #pragma mark - XEWebViewNoticeDelegate - (void)webView:(XEWebView *)webView didReceiveNotice:(XENotice *)notice { switch (notice.type) { case XENoticeTypeLogin: // 收到登陆请求⚠️必须实现以在token失效时同步登录态至sdk内部 { // 这里应该调用登陆接口，获取到cookie_key, cookie_value, // 并通过 -synchronizeCookieKey:cookieValue: 同步至SDK break; } case XENoticeTypeShare: // 收到分享的回调数据 { // 在这里自定义分享操作 break; } case XENoticeTypeReady: // Web页面已准备好，可以调用分享接口 { // 这里可以启用分享按钮 break; } default: break; } } ~~~ #### **3.7.1 XENotice 类型** XENotice 是 XEShopSDK 提供给商家的一种事件通知，用来告知特定事件的发生，并提供相关参数，以便商家针对特定事件进行二次开发。目前所提供的类型如下： ##### **3.7.1.1 XENoticeTypeLogin 登录通知** 收到该通知时代表需要登录，请调用小鹅通登录态接口进行登录，并将返回值通过 SDK 的接口设置给 XESDK。 ##### **3.7.1.2 XENoticeTypeShare 接收到分享结果的通知** 回调数据： ~~~ { "share_content": "小鹅通分享描述", "share_image": "小鹅通分享图片链接", "share_link": "http://appTCVlUyvG2205.h5.xiaoeknow.com", "share_title": "小鹅通分享标题" } ~~~ 说明 | 字段 | 说明 | | --- | --- | | share\_image | 图片链接 | | share\_title | 标题 | | share\_link | 页面链接 | | share\_content | 描述 | ##### **3.7.1.3 XENoticeTypeTitleChange WebView 标题改变** ##### **3.7.1.3 XENoticeTypeOutLinkUrl 点击自定义链接回调** 规则为带参数 needoutlink=1 的链接, 例：[https://xiaoe-tech.com/?needoutlink=1](https://xiaoe-tech.com/?needoutlink=1) ### **3.8 页面分享** 如需要获取页面的分享信息, 需要调用 XEWebView 的share()方法来触发分享事件： ~~~ - (void)share; ~~~ 触发分享操作后， XEWebView 会异步调用 webView:didReceiveNotice:代理方法，XENotice 的 response 会包含分享需要的各种信息。并不是所有可见页面都能触发分享. 没有回调则代表该页面不可分享。 ### **3.9 日志开关** SDK 提供了日志功能，默认日志为关闭状态. 开发者可以通过 XEConfig 中的设置打开日志开关. ~~~ // 是否开启控制台日志输出，默认为NO。仅在 DEBUG 模式下有效 @property (nonatomic, assign) BOOL enableLog; ~~~ ## **4 常见问题** #### **4.1 iOS 使用 SDK 时，出现支付后不能返回 APP** 请参考上方接入指南，配置 app scheme. #### **4.2 iOS点击去支付无法跳转到对应客户端微信** 首先确认用户设备是否安装相应客户端，其次确认 shouldStartLoadWithRequest 里是否拦截微信的 scheme，最后确认工程是否加了微信 scheme 白名单。 #### **4.3 pod 搜索不到最新的 SDK 呀？** 您电脑本地的 pod repo 没有更新。运行 pod repo update 即可。 #### **4.4点击分享按钮没有弹出分享。** 点击分享按钮后，SDK 会将页面相关信息返回到应用中。应用开发者需要自行实现分享的 UI。监听一下消息即可获取分享相关信息： ~~~ - (void)webView:(id<XEWebView>)webView didReceiveNotice:(XENotice *)notice { switch (notice.type) { case XENoticeTypeShare: // 收到分享的回调数据 { NSLog(@"分享数据：%@", notice.response); break; } } ~~~ #### **4.5 分享回调没有图片等数据？** 需在B端后台开通配置 #### **4.6 接入过程中的问题及其他未注明事宜，请咨询您的专属管家。**