一、前置条件
- 请开发者提供应用的基本信息,包括:服务器IP地址,应用名称,Android (应用签名,应用包名),IOS(Bound ID),供我方在运营商报备。
- 微网会输出开发者,每个应用对接的AppId供开发者使用,作为开发者的标识。
- 微网SDK不支持在模拟器上编译运行。
- 微网SDK支持中国移动(3/4G)、联通(3/4G)、电信4G的取号能力。
-
微网SDK支持网络环境为
- 纯数据网络
- 数据网络与wifi网络双开
- 对于双卡手机,微网SDK取当前流量卡号
二、开发环境搭建
-
微网SDK支持Xcode 10.0,iOS8.0+及以上版本。
-
导入framework
将微网SDK压缩包中framework文件夹下所有资源添加到工程中(注意勾选Copy items if needed)
-
Xcode配置
1,Other Linker Flags 中 添加 –ObjC
注意:如果以上操作仍然出现unrecognized selector sent to instance找不到方法报错,则添加更 改为-all_load
2,设置 Enable Bitcode = No
在xcode->Build Settings->Build Options 中,设置 Enable Bitcode = No
3,添加libc++.1.tbd和libz.1.2.8.tbd
在xcode->General(或者Build Phases)->Linked Frameworks and Libraries中点击 + ,搜索并选择添加libc++.1.tbd和libz.1.2.8.tbd
4,Swift工程设置
Swift工程需要额外添加-force_load 在xcode->BuildSetting->Other Linker Flags 添 加-force_load。
三、接口方法说明
1、获取认证实例
使用场景:使用接口前获取使用实例
接口说明:开发者调用接口前必须先获取该实例
-
方法原型
+ (instancetype) getInstance;
-
代码示例
WESDKLogin *loginManager = [WESDKLogin getInstance];
2、SDK获取版本号
使用场景:进行初始化的时候需要先获取SDK的版本
接口说明:获取SDK的版本号方法
-
方法原型
+ (NSString *) getVersion;
3、SDK初始化
使用场景:在app启动时调用
接口说明:保证在预取号或一键登录前调用成功一次,初始化返回false时,后续操作会失败,一键登录和号码认证功能同时使用时,只需要成功调用一次即可
-
方法原型
/**
使用运营商数据初始化SDK
@param data 微网通联平台获取到的sdkInfo
@param appId 微网通联平台获取到的appId
@param error 初始化失败的错误
@return 是否初始化成功
*/
- (BOOL) initWithData:(NSString *)data
withAppid:(NSString *)appId
andError:(NSError **)error;
-
示例代码
//微网通联平台获取到的appCode
NSString *Output = responseObject[@"Output"];
NSError *error;
BOOL initResult = [[WESDKLogin getInstance] initWithData:Output
withAppid:@"your app id"
andError:&error];
NSLog(@"init-success:%d",initResult);
4、SDK预取号
使用场景:在执行拉起授权页的方法前调用此方法,比如调一键登录的vc的viewdidload中,或者rootVC的viewdidload中,或者app启动后,此调用将有助于提高拉起授权页的速度和成功率,是拉起授权页的前提必须操作
接口作用:初始化成功后,如果当前为电信/联通/移动的号码,可调用预取号接口,提前获知当前用户的手机网络环境是否符合一键登录的使用条件,成功后将得到用于一键登录使用的临时凭证,默认的凭证有效期60min(电信)/30min(联通)/60min(移动)
使用建议:
开发者在拉起授权页之前,提前进行预取号,否则会造成拉起授权页错误
此方法为异步方法,需要0.5s~2s的时间取得临时凭证,建议您预取号成功后,再拉起授权页
不建议频繁的多次调用和在拉起授权页后调用
-
方法原型
//预取号
- (void) perMobileWithResultListen:(PreMobileResultListener)perMobileListen;
-
参数说明
字段 类型 含义 perMobileListen PreMobileResultListener 预取号回调 回调函数会返回一个NSDictionary类型的结果,以下是回调结果的结构:
字段 类型 含义 resultCode WESDKCode 返回码 resultMsg NSString 返回码描述信息 expiresTime NSTimeInterval 过期时间 operatortype NSString 运营商类型 -
示例代码
[[WESDKLogin getInstance] perMobileWithResultListen:^(NSDictionary *result) {
NSLog(@"perMobile response is %@",result);
WESDKCode resultCode = ((NSNumber
*)result[@"resultCode"]).unsignedIntegerValue;
dispatch_async(dispatch_get_main_queue(), ^{
if (resultCode == WESDKCodeSucceed) {
//预取号成功,拉起授权页
} else {
//预取号失败,使用其他登录方式
}
});
}];
5、拉起授权页
使用场景:调用该接口会拉起SDK中的授权页面,供用户进行点击确认一键登录的操作,调用此方法前,开发者需要设置授权页面的元素,请参考页面可调属性进行授权页面的设置,如不设置,将按照微网提供的默认样式呈现授权页面
接口说明:调用该接口SDK将会拉起授权页面,用户授权一键登录后,SDK将返回预取号临时凭证AccessCode给到应用客户端
-
方法原型
/**
一键登录,获取到的token,可传给移动认证服务端获取完整手机号
@param listener 回调
*/
- (void) getLoginTokenWithListener:(TokenResultListener)listener;
-
参数说明
回调函数会返回一个NSDictionary类型的结果,以下是回调结果的结构:
字段 类型 含义 resultCode WESDKCode 返回码 resultMsg NSString 返回码描述信息 AccessCode NSString 手机号置换令牌,返回码WESDKCodeSucceed时才有此值 -
示例代码
//设置页面配置对象,详细属性说明见 拉起授权页
WECustomModel *custom = [[WECustomModel alloc] init];
custom.currentVC = loginViewController;
//调用设置方法
[[WESDKLogin getInstance] setAuthControllerConfig:custom];
//调用设置方法之后,紧接着拉起授权页
[[WESDKLogin getInstance] getLoginTokenWithListener:^(NSDictionary *result) {
NSLog(@"get Login result:%@",result);
WESDKCode resultCode = ((NSNumber
*)result[@"resultCode"]).unsignedIntegerValue;
if (resultCode == WESDKCodeSucceed) {
NSString *accesscode = result[@"AccessCode"];
//服务端置换手机号,详见服务端接口文档说明
} else if(resultCode == WESDKCodeAuthSuccessOpen) {
//事件统计
NSLog(@"授权页面打开");
} else {
//其他登录方式
}
}];
6、关闭授权页
使用场景:拉起的授权页面后,开发者收到SDK的回调消息调用该方法来关闭授权页面
接口说明:得到SDK的回调消息后,手动关闭授权页
补充说明:用户点击左上角关闭页面按钮时会自动关闭授权页并回调通知开发者,无需开发者干预
-
方法原型
/**
关闭授权界面
@param flag 动画开关
@param completion 回调参数
*/
- (void)we_dismissViewControllerAnimated: (BOOL)flag completion:(void (^ __nullable)(void))completion;
-
示例代码
[[WESDKLogin getInstance] we_dismissViewControllerAnimated:YES
completion:^{
[weakSelf presentViewController:resultController animated:YES
completion:nil];
}];
7、获取本机号码认证令牌
使用场景:开发者在发起号码认证前需调用该接口获取凭证信息再进行服务器的认证
接口说明:在进行号码认证前获取认证需要的accessCode的接口
-
方法原型
typedef void(^TokenResultListener)(NSDictionary *result);
- (void)mobileAuthWithListener:(TokenResultListener)listener;
-
参数说明
响应参数说明
字段 类型 含义 resultCode WESDKCode 返回码 resultMsg NSString 返回码含义 AccessCode NSString 手机号置换令牌(resultCode == WESDKCodeSucceed时有此值) -
示例代码
[[WESDKLogin getInstance] mobileAuthWithListener:^(NSDictionary *result) {
//获取code
WESDKCode code = [((NSNumber *)result[@"resultCode"]) unsignedIntegerValue];
//
if (code == WESDKCodeSucceed) {//成功
//校验
NSString *AccessCode = result[@"AccessCode"];
} else {
//其他校验方式
}
}];
8、设置超时时间
使用场景:在预取号和本机号码校验方法调用之前设置,来控制获取accessCode的超时时间
接口说明:设置预取号和本机号码校验方法的超时时间,默认五秒,设置范围3~8秒
-
方法原型
/**
设置超时,默认五秒,设置范围3~8秒
@param timeout 超时
*/
- (void)setTimeoutInterval:(NSTimeInterval)timeout;
9、输出调试日志
使用场景:设置debug模式进行调试,SDK会输出一下调试日志
接口说明:开发时需要进行调试的时候可以打开日志
-
方法原型
/**
@param isDebug 开关参数
*/
- (void) setDebugMode:(BOOL)isDebug;
10、网络环境判断
使用场景:粗略判断当前的网络环境是否⽀持⼀键登录或者号码认证
接口说明:该方法可以从多个维度(是否含有SIM,是否处于飞行模式,当前网络制式)等多个维度粗略的判断当前网络环境是否支持⼀键登录或者号码认证。此方法为同步方法。当该方法返回 NO 时,不建议继续使用一键登录/号码认证功能
-
方法原型
/// 判断当前网络环境是否支持⼀键登录或号码认证
- (BOOL) checkVerifiyEnable;
四、授权页设计
默认样式
状态栏
支持状态栏设置文字(时间,电池,信号等)和背景颜色为黑色活白色,也可以设置背景图沉浸状态
标题栏
- 标题栏:支持设为隐藏状态
- 返回按钮:点击事件的位置和区域固定,可更换为自定义图片
- 标题:允许修改文本(包括文案、颜色、字体大小)
- 自定义区域:可以在右侧自定义按钮,设置包括文案、图片、跳转链接等内容。
logo
- 支持更换自定义图片,图片尺寸无限制,在X轴上居中
- logo图片可以隐藏,可以设置Y轴偏移量进行上下位置调整
- 此类自定义图片,开发者都可以更具不同分辨率机型,上传大小不同的图片
号码栏
- 可以设置文本颜色、字体大小,不允许隐藏
slogan
- 支持设置文本颜色
- slogan在X轴居中,可以设置Y轴偏移量进行上下位置调整
登录按钮
- 按钮在X轴上居中,可以设置Y轴偏移量进行上下位置调整
- 允许设置文本颜色,字体大小
- 可以通过上传图片的方式自定义按钮样式,不允许隐藏
切换按钮
- 按钮居中,可以设置Y轴位移进行上下位置调整
- 允许修改文字颜色,字体大小,可以隐藏。
隐私栏
- 文案可以设置Y轴位移进行上下文位置调整。
- 允许开发者设置自己的自定义协议,支持0~2份协议链接。
- checkBox勾选框:默认不勾选,开发者可以自定义是否默认勾选
背景、自定义控件
- 授权页支持开发者自己上传自定义图片充当授权页背景。
- 在不遮挡默认元素的情况下,开发者可以在空白处增加自定义控件以满足更多个性化需求。例如跳转APP登录/注册界面,增加微信、QQ等第三方登录界面以及图标、增加UI元素和文字等等。
开发者不得通过任何技术手段,将授权页面的隐私栏、品牌露出内容隐藏、覆盖,对于接入微网SDK并上线的应用,我方和运营商会对上线的应用授权页面做审查,如果有出现未按要求设计授权页面,将隐私栏、运营商品牌、授权登录按钮隐去不可见的设计,我方有权将应用的登录功能下线。
五、页面可调属性
使用场景:开发者如果要设置授权页面的元素,需在调用拉起授权页面前调用该接口进行设置。
接口说明:开发者可以通过setAuthControllerConfig方法修改授权页面属性。
方法名称:getLoginOnViewController:andViewModel:TokenWithListener:
方法原型:
/// 打开登录⻚
/// @param vc present view Controller
/// @param model ⻚⾯配置
/// @param listener 回调
- (void)getLoginOnViewController:(UIViewController *)vc
andViewModel:(WEAuthViewModel *)model
TokenWithListener:(TokenResultListener)listener;
通过model(WEAuthViewModel类型)属性,可以实现:
- 可以允许开发者在授权页面上添加自定义控件;
- 可以设置首页页面UI元素控件布局;
以下是WEAuthViewModel类所有属性的说明
1、状态栏部分设置
注意:状态栏设置的如下两个属性生效的前提条件是:
Status bar is initially hidden 设为 YES,View controller-based status bar appearance 设为 NO
/// 状态栏是否隐藏,默认为NO
@property (nonatomic,assign) BOOL prefersStatusBarHidden;
///状态栏主题⻛格,默认为UIStatusBarStyleDefault*/
@property (nonatomic,assign) UIStatusBarStyle
preferredStatusBarStyle;
2、全屏授权页转场动画
typedef NS_ENUM(NSUInteger, WeLinkPresentationDirection){
WeLinkPresentationDirectionBottom = 0, //底部 present默认效果,底⼊底出
WeLinkPresentationDirectionRight, //右边 右⼊右出
WeLinkPresentationDirectionTop, //上⾯ 上⼊上出
WeLinkPresentationDirectionLeft, //左边 左⼊左出
WeLinkPresentationNoAnimated
//⽆动画
};
///授权页面推出的动画效果:参考WeLinkPresentationDirection枚举
@property (nonatomic, assign) WeLinkPresentationDirection
presentType;
3、导航栏设置
model属性 | 值类型 | 属性说明 |
---|---|---|
navHidden | BOOL | 导航栏隐藏,默认不隐藏 |
navText | NSAttributedString | 导航栏标题,默认:@"免密登录",15pt,白色 |
navColor | UIColor | 设置导航栏颜色 |
navBackHidden | BOOL | 导航栏返回按钮隐藏 |
navReturnImg | UIImage | 导航返回图标(尺寸根据图片大小) |
navBackLeftMargin | NSNumber | 导航栏按钮左偏移 |
navMoreView | UIView | 授权页导航右边的自定义控件,(获取navMoreViewsize的优先级 frame.size >>> [viewsizeThatFit:CGSizeZero],X、Y设置无效) |
4、协议页导航栏
model属性 | 值类型 | 属性说明 |
---|---|---|
privacyNavTitle | NSDictionary<NSString*,NSAttributedString*> | 协议详情页导航栏标题 |
privacyNavBackImg | UIImage | 协议详情页导航栏返回图片(尺寸根据图片大小) |
privacyNavColor | UIColor | 协议详情页导航栏颜色 |
5、自定义控件和页面背景
/**授权界⾯背景图⽚*/
@property (nonatomic,strong) UIImage *authPageBackgroundImage;
/**授权界⾯⾃定义控件View的Block*/
@property (nonatomic,copy) void(^authViewBlock)(UIView *customView);
示例:
customeModel.authViewBlock = ^(UIView *customView) {
UIImageView *imageView = [[UIImageView alloc] initWithImage:
[UIImage imageNamed:@"微⽹logo"]];
imageView.frame = customView.bounds;
[customView addSubview:imageView];
};
6、logo
model属性 | 值类型 | 属性说明 |
---|---|---|
logoImg | UIImage | LOGO图片 |
logoHidden | BOOL | LOGO图片隐藏 |
logoWidth | CGFloat | LOGO图片宽度 |
logoHeight | CGFloat | LOGO图片高度 |
logoOffsetY | NSNumber | LOGO图片Y轴偏移量 |
logoOffsetX | NSNumber | LOGO图片X轴偏移量 |
7、slogan
model属性 | 值类型 | 属性说明 |
---|---|---|
sloganHidden | BOOL | 设置slogan隐藏 |
sloganTextStyle | NSDictionary<NSAttributedStringKey, id> | slogan文字样式 |
sloganText | NSString | 自定义slogan文字 |
sloganOffsetY | NSNumber | Slogan偏移量Y |
sloganOffsetX | NSNumber | Slogan偏移量X |
8、logo设置
model属性 | 值类型 | 属性说明 |
---|---|---|
logoImg | UIImage | LOGO图片 |
logoHidden | BOOL | LOGO图片隐藏 |
logoWidth | CGFloat | LOGO图片宽度 |
logoHeight | CGFloat | LOGO图片高度 |
logoOffsetY | NSNumber | LOGO图片Y轴偏移量 |
logoOffsetX | NSNumber | LOGO图片X轴偏移量 |
9、号码栏设置
model属性 | 值类型 | 属性说明 |
---|---|---|
phoneNumStyle | NSDictionary<NSAttributedStringKey,id> | 手机掩码文字样式(默认黑色,22pt,粗体) |
phoneNumOffsetX | NSNumber | 手机掩码栏X偏移量 |
phoneNumOffsetY | NSNumber | 号码栏Y手机掩码栏Y偏移量 |
10、登录按钮设置
model属性 | 值类型 | 属性说明 |
---|---|---|
logBtnText | NSAttributedString | 登录按钮文本(默认 – @“本机号码登录” 17号字体,白色) |
logBtnImgs | NSArray <UIImage*> | 登录按钮背景图片添加到数组(顺序如下:@[激活状态的图片,失效状态的图片,高亮状态的图片] |
logBtnOffsetY | NSNumber | 登录按钮Y偏移量 |
logBtnMarginLeft | NSNumber | 登录按钮左边距 |
logBtnMarginRight | NSNumber | 登录按钮右边距 |
logBtnMarginLR | NSNumber | 登录按钮左右边距 |
logBtnHeight | CGFloat | 登录按钮高度 |
说明:
左边距和右边距配合使用,优先级高,用于设置左右边距不相等的情况,如果两个值有任⼀值为空则不生效(需要设置高度logBtnHeight != 0,不设置不生效)
左右边距单独使用,优先级低,用于设置左右边距相等的情况(需要设置高度logBtnHeight != 0,不设置不生效)
都不设置,则采用图片(激活状态的图片)尺寸,居中展示
11、Toast (未勾选协议的情况下点击登录按钮)
model属性 | 值类型 | 属性说明 |
---|---|---|
toastViewBlock | void(^toastViewBlock)(UIView*containerView); | 自定义Toast提示,设置后不再展示默认Toast |
notCheckProtocolHint | NSString | 未勾选服务条款复选框时,点击登录按钮的提示。默认为"请同意服务条款"。 |
toastDuration | NSNumber | Toast显示的时⻓,默认1秒 |
toastViewOffsetY | NSNumber | Toast Y轴偏移量,默认是距离containerView九分之五的长度(填写具体的数值,eg:@(530)) |
toastTextStyle | NSDictionary<NSAttributedStringKey,id> | Toast文字的样式 默认:15号字体,白色 |
toastCornerRadius | NSNumber | Toast圆角 默认:7 |
toastBackgroundColor | UIColor | ToastView背景颜色 默认黑色 |
12、Loading (勾选协议的情况下点击登录按钮,等待动画)
@property (nonatomic,copy) void(^authLoadingViewBlock)(UIView
*containerView);
说明:
在SDK返回AccessCode后,UI上会开始展示Loading动画,不设置自定义Loading动画,则展示默认Loading动画。如果想停止默认Loading动画,可以使用方法
[[WESDKLogin getInstance] stopLoading];
13、隐私条款
model属性 | 值类型 | 属性说明 |
---|---|---|
uncheckedImg | UIImage | 复选框未选中时图片 |
checkedImg | UIImage | 复选框选中时图片 |
checkboxWH | NSNumber | 复选框大小(只能正方形)必须大于12,不设置的话,使用图片尺寸,如果图片尺寸小于12,则复选框大小为12*12 |
checkboxChecked | BOOL | 隐私条款check框默认状态 默认:NO |
checkBoxHidden | BOOL | 是否隐藏勾选框,隐藏后自动设置为勾选状态 |
checkBoxResponsePadding | NSNumber | 扩大复选框点击范围,默认扩大15,详情参见CGRectInset函数 |
defaultPrivacySymbol | BOOL | 运营商隐私协议是否使⽤书名号(《》),默认:YES |
appPrivacyAlignment | NSTextAlignment | 隐私条款文本对齐方式,默 认:NSTextAlignmentLeft |
appPrivacyOriginLR | NSArray<NSNumber *> | 隐私条款(包括check框)的左右边距,默认左右边距相等,值等于(屏幕宽 – 280)/ 2,280是登录按钮默认宽度 |
appPrivacyOffsetY | NSNumber | 隐私条款Y偏移量(注:此属性为与屏幕底部的距离) |
appPrivacyColor | NSArray<UIColor*> | 隐私条款名称颜色:@[基础文字颜色UIColor,条款颜色UIColor] eg.@[[UIColor lightGrayColor],[UIColor greenColor]] |
appPrivacyTextFont | UIFont | 隐私条款文字字体 |
appPrivacyAbbreviatedName | NSString | 隐私条款–APP名称简写 默认取CFBundledisplayname 设置描述文本尾部后此属性无效*/ |
appPrivacyFirst | NSArray | 隐私条款Y⼀:需同时设置Name和UrlString eg.@[@"条款⼀名称",条款⼀URL] @[NSSting,NSURL]; |
appPrivacySecond | NSArray | 隐私条款⼆:需同时设置Name和UrlString eg.@[@"条款⼀名称",条款⼀URL] @[NSSting,NSURL]; |
appPrivacyThird | NSArray | 隐私条款三:需同时设置Name和UrlString eg.@[@"条款⼀名称",条款⼀URL] @[NSSting,NSURL]; |
appPrivacyBefore | NSString | 描述文本首部 default:"同意" |
officialPrivacyBefore | NSString | 自定义运营商条款前缀 默认:@"" |
officialPrivacyEnd | NSString | 自定义运营商条款后缀 默认:@"" |
appPrivacyOneLinkText | NSString | 描述文本⼆ default:"和" |
appPrivacyTwoLinkText | NSString | 描述文本三 default:"、" |
appPrivacyThreeLinkText | NSString | 描述文本四 default:"、" |
appPrivacyEnd | NSString | 描述文本 尾部 default: "并授权AppName使用认证服务" |
说明:
隐私协议文本拼接: DesTextFirst+运营商条款+DesTextSecond+隐私条款⼀+DesTextThird+隐私条款⼆+DesTextFourth+隐私条款三+DesTextLast
14、窗口模式
model属性 | 值类型 | 属性说明 |
---|---|---|
authWindow | BOOL | 窗口模式设置 |
cornerRadius | CGFloat | 自定义窗口弧度 默认是10 |
scaleW | CGFloat | 自定义窗口宽-缩放系数,默认是 竖屏0.8 横屏0.5 |
scaleH | CGFloat | 自定义窗口高-缩放系数,默认是 竖屏0.5 横屏0.9 |
modalTransitionStyle | UIModalTransitionStyle | 窗口模式推出动画 |
authWindowWidth | CGFloat | 自定义窗口宽 |
authWindowHeight | CGFloat | 自定义窗口高 |
bottomWindow | BOOL | 是否使用底部弹窗模式(底部弹窗只支持竖屏) |
maskWindowColor | UIColor | 弹窗蒙层颜色 (默认是透明的) |
弹窗尺寸可以使用绝对值定义,也可以使用比例定义,绝对值定义优先级高于比例定义
UIModalTransitionStyle可以使用的值
UIModalTransitionStyleCoverVertical,下推
UIModalTransitionStyleFlipHorizontal,翻转
UIModalTransitionStyleCrossDissolve,淡出
六、返回码
返回码 | 返回码描述 |
---|---|
WESDKCodeFailure | 失败 |
WESDKCodeUnInitError | SDK尚未初始化或初始化错误 |
WESDKCodeUnPerMobileError | 没有进行预取号操作 |
WESDKCodeProcessException | 数据解析异常 |
WESDKCodeRequestError | 网络请求错误 |
WESDKCodeNoEnough | 余额不足 |
WESDKCodeAccountIncorrectError | 用户名或密码不正确 |
WESDKCodeOperatorConfigError | 获取运营商配置失败 |
WESDKCodeSelectedOtherWay | 用户点击“账号切换”按钮 |
WESDKCodeUserCancelAuthError | 用户取消登录(关闭页面) |
WESDKCodeOtherError | 其他错误 |
WESDKCodeBundleIDError | bundle id 校验失败 |
WESDKCodeNoChanalError | 不支持当前运营商的号码认证或一键登录 |
WESDKCodeUnSupportError | 当前网络环境不支持号码认证或一键登录 |
WESDKCodeNoSIMError | 没有SIM卡 |
WESDKCodeAuthSuccessOpen | 授权界面弹起 |
WESDKCodeSucceed | 成功 |