回到顶部
TOP

Objective-C客户端接入文档

一. 概述

1.该文档主要用于游戏开发者使用iOS原生接入方法,在游戏程序中集成我方SDK;
2.该文档所用示例代码均为SDK包中得LJIOSDemo工程代码;
3.本文档对应的SDK版本为1.5.0及以上。

二. 接入准备

2.1 导入依赖库

请在官网下载iOS原生SDK包之后,解压,将libs目录复制到游戏Xcode工程目录下;选中工程,使用右键Add方式将libs目录添加到工程中:
示例

三. 接口接入

注:以下所有接口均为必接接口。

3.1 回调接口

在使用主要接口时,所要用到的回调协议包括如下,请选择合适的实现方式:
初始化回调协议:

    @protocol InitCallback 
    -(void)onInitSuccess:(NSString*)successInfo;
    -(void)onInitFailed:(NSString *)failInfo; 
    @end  

用户回调协议:

    @protocol UserCallback
    -(void)onLoginSuccessWithXMUser:(XMUser*)xmUser CustomParams:          (NSString*)customParams;  
    -(void)onLoginFailedWithReason:(NSString*)reason CustomParams:    (NSString*)customParams;  
    -(void)onLogout:(NSString*)customParams;
    @end  

支付回调协议:

    @protocol PayCallback 
    -(void)onPaySuccess:(NSString*)successInfo;
    -(void)onPayFailed:(NSString *)failInfo; 
    @end  

3.2 初始化接口

在使用其他所有接口之前,请先调用初始化接口,推荐在程序启动时调用,如application:(UIApplication)application didFinishLaunchingWithOptions:(NSDictionary )launchOptions 方法中;

    -(void)initWithCallback : (id)initCallback  

初始化回调

    -(void)onInitSuccess:(NSString*)successInfo;
    -(void)onInitFailed:(NSString *)failInfo;

3.3 登录接口

在需要登录时调用该方法:

    -(void)loginWithCustomParams:(NSString*)customParams Delegate:(id)userCallback  

参数说明:
customParams ———开发者自定义参数,在登录回调中原样返回
userCallback ———用户回调
接口说明:
请勿在游戏启动后直接调用此接口,部分渠道初始化时间较长,初始化不成功调用登录接口会出现崩溃等问题,建议添加登录界面,由用户点击触发登录操作。

登录回调

    /** 
     * @Description
     *     登录失败回调方法
     * @params
     *     reason       ----------登录失败原因 
     *     customParams ----------从登录接口传入的自定义字段
     **/
    -(void)onLoginFailedWithReason:(NSString *)reason CustomParams:(NSString *)customParams
      {}

    /** 
     * @Description
     *    登录成功回调方法
     * @params
     *    xmUser       ----------登录成功后,返回的用户信息类 
     *    customParams ----------从登录接口传入的自定义字段
     **/
    -(void)onLoginSuccessWithXMUser:(XMUser *)xmUser CustomParams:(NSString *)customParams
    { //请在登录成功后,向游戏服务端发起二次验证请求(参考服务端⽂文档),以保证用户信息的可靠性
    }  

接口说明:
a)登录成功后,返回一个用户信息类XMUser,XMUser的数据结构如下:
NSString* userId ———我方提供的唯一userid
NSString* username ———用户名,可能为空
NSString* token ———登录验证令牌
NSString* channelUserId ———渠道用户userId,渠道提供的原始用户id
NSString* channelCode ———渠道编码
NSString* channelLabel ———渠道标识(表意字符串)
NSString* productCode ———产品代码,在我方平台创建产品后,可从产品管理页面获取
b)为了保证登录信息的有效性和合法性,请务必进行登录二次验证,即:
游戏客户端将得到的XMUser信息上传到游戏服务器->
游戏服务器与我方服务器进行登录信息验证->
游戏服务器将验证结果通知游戏客户端,游戏客户端根据验证结果允许玩家进入游戏或重新登录(参考服务端文档)

3.4 支付接口

    -(void)payWithAmount:(int)amount itemName:(NSString*)itemName count:(int)count customParams:(NSString*)customParams CallbackUrl:(NSString*)callbackUrl Delegate:(id)payCallback; 

参数说明:
amount ———支付金额,单位为人民币分
itemName ———商品名称,如金币,钻石等
count ———购买数量
customParams ———开发者自定义字段,会与支付结果一起通知到游戏服务器,游戏服务器可通过该字段判断,区分支付的详细内容
callbackUrl ———支付结果通知地址,支付完成后我方会向该地址发送支付通知,通知交易结果,如金额,customParams等信息
payCallback ———支付回调

支付回调

    /**
     * @Description
     *  支付失败回调方法
     * @params
     *  failInfo       ----------支付失败信息
     **/
    -(void)onPayFailed:(NSString *)failInfo {}  

    /**
     * @Description
     *  支付成功回调⽅方法 
     * @params
     *  successInfo   ----------支付成功信息
     **/
    -(void)onPaySuccess:(NSString *)successInfo {}  

接口说明:
支付回调提供了success和fail两种通知,但充值是否到账还需以服务器通知为准,不可将此作为判断充值是否成功的依据。
onPaySuccess,该回调仅代表用户已发起支付操作,不代表是否充值成功,具体充值是否到账需以服务器通知为准,在此回调中游戏方可开始向服务器发起请求,查看订单是否已支付成功,若支付成功则发放道具。
onPayFail,该回调代表用户已经放弃支付,无需向服务器查询充值状态。

3.5 登出接口

在需要登出账号时,调用此接口:

    -(void)logoutWithCustomParams:(NSString*)customParams Delegate:(id)userCallback

参数说明:
customParams ———自定义字段,在登出回调中原样返回
userCallback ———用户回调
接口说明:
登出操作用于用户切换账号等事件处理,若游戏中存在登出或者切换账号的按钮,则可在点击按钮时进行登出接口调用,在扥出回调中进行重新登录等操作;

登出回调:

    /**
     * @Description
     *  登出回调方法
     * @params
     *  customParams   ----------从登出接口传入的自定义字段
     **/
    -(void)onLogout:(NSString *)customParams {}

接口说明:
该回调在如下情况被调用:
a) 点击游戏内的登出按钮,调用SDK的登出后;
b) 点击渠道用户中心界面的注销按钮;
c) 点击渠道用户中心界面的切换账号按钮;
游戏中没有调用logout接口但收到渠道的登出回调同样会调用该回调,并不是只有调用了logout接口才会收到该回调,请确保在游戏中任何时候,当该函数被调用均可正确登出,回到登录界面。

3.6 用户信息扩展接口

    -(void)setExtRoleData:(NSString*)json

参数说明:
json:用户扩展信息,请传入标准JSON字符串,所要包括的参数信息如下:
_id ———当前场景,包括进入服务器enterServer,创建角色createRole,升级levelUp
roleId ———当前登录的玩家角色id,必须为数字,若无,可传入userId
roleName ———当前登录的玩家角色名,不能为空,不能为null,若无,传入“游戏名称+username”,如“刀塔传奇风吹来的鱼”
roleLevel ———当前登录的玩家角色等级,必须为数字,且不能为0,若无,传入1
zoneId ———当前登录的游戏区服id,必须为数字,且不能为0,若无,传入1
zoneName ———当前登录的游戏区服名称,不能为空,不能为null,若无,传入游戏名称+”1区”,如”刀塔传奇1区”
balance ———当前用户游戏币余额,必须为数字,若无,传入0
vip ———当前用户VIP等级,必须为数字,若无,传入1
partyname ———当前用户所属帮派,不能为空,不能为null,若无,传入“无帮派”
接口说明:
上传数据接口需在三处调用,分别为进入服务器,玩家创建角色,玩家升级,有如下三点需要注意:
a) 游戏中该接口必须调用三次,传入不同的_id,以区分不同的上传数据;
b) 若游戏中无对应接口功能,如游戏中无创建角色,则可根据自情况在合适位置进行调用,如登录成功后;
c) 在上传游戏数据时,若存在无对应字段值的情况,可传入默认值,具体参见数据组成部分;
d)如果需要接入uc渠道,需要多传入角色创建时间(服务器时间),放入extra,值为Long型的十位长度字符串
e) 具体使用方式参考demo。

3.7 区分渠道接口

    [XMUtil getChannelLabel]

接口说明:
该接口用于获取当前渠道的channelLabel,可帮助开发者区分渠道,更多请参考官方文档《如何区分渠道》。

四. 导出配置

a. 请参考SDK包中的《母包配置说明文档》对工程进行设置,配置完成后,参考官网自测文档进行测试;
b. 母包测试完成后,请参考官网文档《IOS打包流程》,打渠道包。

五. FAQ

Q:支持的SDK最低版本?
A:运行母包时,最低版本设置不低于6.0,渠道包无此限制,以渠道支持为准。

Q:登录失败?
A:请检查参数配置中的测试渠道编码。

Q:运行报错?
A:请严格参考《母包配置说明文档》,对工程进行配置。

向上
向下