小鹅通原生SDK- iOS端接入指南

小鹅通 SDK 依托于 XEWebView 来进行页面展示. 类似 UIWebView, 传入店铺页面地址，就可以进行完整的商品展示购买流程。具体可参考 DEMO。

iOS App中课程支付必须接入iOS代币支付方案，因苹果对于虚拟产品有收取“苹果税”的规则，如不遵守会有下架风险 详细了解请点击

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://.h5.xiaoeknow.com	动态参数 app_id：小鹅店铺id
其他页面	通过小鹅店铺管理台以下路径：“课程管理-图文(课程类型，以图文为例)-点击某个具体的课程分享按钮-点击复制按钮”得到链接：https://appidxxxxxx.h5.xiaoeknow.com/v1/course/text/i_5e7f809dd6317_qSMuUoAi?type=2SDK展示链接需要替换链接域名部分为.h5.xiaoeknow ,例如，您的appid参数为”apprnDA0ZDw4581”，那么适配SDK展示的链接如下:https://apprnDA0ZDw4581.h5.xiaoeknow.com/v1/course/text/i_5e7f809dd6317_qSMuUoAi?type=2	动态参数 “appXXXXXXXXXX”:需动态替换为您的小鹅店铺id

2. 接入要求

iOS 8.0 或更高
Xcode 9.0 或更高版本（建议使用最新版本）

3. 接入流程

Github链接推荐使用 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

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端后台开通配置

iOS-SDK 接入