RaStarOverseaSDK 使用说明

---

版本号	SDK Hash值	更新日期	作者
1.0.0	1e7429f73ace7784863b79e6fe5a96f0	2017/7/11	Vincent
1.0.1	fccc118741e72d44f2a6d170dddc39ec	2017/7/13	Vincent
1.0.2	06eedc71ff33ca93ab7ed42c2b9dbbcf	2017/9/01	Vincent

---

SDK 使用说明

此SDK为RaStar 海外版本。适用于iOS 8.0以上版本的Apple设备，包括iPhone、iPad等。

SDK 使用准备

Facebook

由于此SDK接入Facebook相关功能性代码，故在使用之前需在Facebook开发者后台申请相关权限，并获取相对应开发者的Info.plist 数据。

• 创建应用

登录FaceBook开发者后台后创建应用

登录Facebook开发者后台后如图所示点击创建应用。

创建新应用

创建新应用
其中，显示名称为Facebook后台显示名称。

• 填写相关信息
  创建完成新应用后，点击进入应用，在产品设置页面选择Facebook登录，点击开始。

选择Facebook登录

进入Facebook登录设置之后，选择 iOS Type，并跳过1、2项。

• 在Facebook后台添加自己项目工程的Bundle ID。

添加Bundle ID

此处添加的BundleID必须与最终打包工程的BundleID一致。

• 获取对应Info.plist参数
  打开单点启动按钮。获取 Info.plist 数据，并将其添加到项目工程的 Info.pilst 文件正文后方。

获取Facebook提供的Info.plist参数

添加至工程Info

• 由于使用Facebook版本为：4.22.1 故需要添加以下字段供支持：

4.22.1需要添加

如下所示plist文件：

添加完成后plist

至此，Facebook 后台相关配置完毕。

---

Game Center

此SDK 内嵌Apple Game Center。为实现相关功能，需在Apple 开发者后台配置相关参数

• 生成AppID

生成App ID

进入开发者后台后依次进行如图所示操作，填写正确BundleID。

勾选相关服务

勾选Game Center服务

在App Services 中务必保证Game Center勾选，其他功能按需勾选。成功后在AppIDs 中可以见到刚刚创建的App ID。如下所示：

创建App ID完成

至此，App Developer中相关配置完成。

• 创建App

前往Apple iTunes Connect 后台创建相关App 并加入Game Center 相关功能。

创建App

创建后 进入App 管理，进入 功能 -> Game Center 按需配置排行榜和成就选项。

配置Game Center

打开工程Project Capabilities Game Center按钮，此时Steps 应全部显示成功。

配置成功

至此，Game Center相关配置完成。

---

项目工程配置

添加依赖库

复制SDKTest(即 Demo) 中的 RaStar_Oversea_Framework 文件夹（内部包含RSOverseaSDK.Plist、RaStarOverseaSDK.framework、RaStarAbroadSDKBundle.bundle、Frameworks_Facebook文件夹）至项目工程目录中，并右键添加至工程中。

添加依赖库

前往 Project --> Build Settings（构建设置）选项卡，将 RaStar_Oversea_Framework 和 Frameworks_Facebook 添加到项目的Framework Search Paths（框架搜索路径）。如下图所示：

添加框架搜索路径

前往 Project --> Build Phases（构建阶段）选项卡，将FBSDKCoreKit.framework、FBSDKShareKit.framework、FBSDKLoginKit.framework、RaStarOverseaSDK.framework、Bolts.framework添加至Link Binary With Libraies 下依赖库列表。由于SDK需要，另添加GameKit、StoreKit、Security、SystemConfiguration依赖库至引用列表。因为SDK内部包含Bundle资源，故将RaStarAbroadSDKBundle 添加至 Copy Bundle Resources 资源引用列表。如下图所示：

添加依赖库及资源列表

设置动态引用

因为SDK内部涉及对某些类的拓展。故需要在工程中设置动态引用，前往 Project --> Build Settings（构建设置）选项卡，于搜索栏搜索
Other Linker Flags 并于该选项后添加 –ObjC 如下图所示：

设置动态引用

基本参数填写（plist）

设定基本参数，例如Apps广告相关参数，支付相关参数等，如下图所示：

基本参数填写

标准货币符号请参考 Apple 收费标准表中所对应标准货币符号（eg.USD、EUR、CNY、JPY、AUD等）
至此，项目设置阶段完成，项目左侧文件树应为如下图所示：

文件树

---

SDK接入

链接应用委托

因为此SDK应用需要切换到原生Facebook应用或者iOS Safari 操作，需要对操作结果进行处理，故需要将AppDelegate类关联到FBSDKApplicationDelegate 对象。另外，需要绑定相关AppsFlyer参数故需要在AppDelegate.m 文件中添加下列代码：

#import "AppDelegate.h"
#import `
#import 

@interface AppDelegate ()

@end

@implementation AppDelegate


- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    
    [[FBSDKApplicationDelegate sharedInstance] application:application
                             didFinishLaunchingWithOptions:launchOptions];
    // 在此添加任意自定义逻辑。
    [RaStarCommom setAppsFlyer];
    return YES;
}
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url
  sourceApplication:(NSString *)sourceApplication annotation:(id)annotation {
    
    BOOL handled = [[FBSDKApplicationDelegate sharedInstance] application:application
                                                                  openURL:url
                                                        sourceApplication:sourceApplication
                                                               annotation:annotation
                    ];
    // 在此添加任意自定义逻辑。
    return handled;
}

如未设置，则程序内部点击Facebook相关按钮操作时可能出现程序崩溃或授权成功后不跳转，以及AppsFlyer无法做出对应统计等。

Oversea SDK 方法属性说明

协议说明

内部包含4个不同协议，分别为初始化：RaStarInitDelegate、登录：RaStarLoginDelegate、绑定：RaStarBindDelegate、支付：RaStarPayDelegate。具体协议方法，见下，或RaStarCommom.h文件。

@protocol RaStarInitDelegate 
@optional
//初始化成功
- (void)onInitSuccess;
//初始化失败
- (void)onInitFail;

@end

@protocol RaStarLoginDelegate 
@optional
//登录成功返回Token、绑定信息
- (void)onLoginSuccess:(NSString *)accessToken BindInfo:(NSDictionary *)infoDic;
//登录失败
- (void)onLoginFail;
//切换登录
- (void)onLoginSwitch:(NSString *)accessToken BindInfo:(NSDictionary *)infoDic;

@end
@protocol RaStarPayDelegate 
@optional
//购买成功 订单号
-(void)onPaySuccess:(NSString *)orderID;
//购买失败 失败原因
-(void)onPayFailure:(NSString *)failure;
//取消支付
-(void)onPayCancel;

@end
@protocol RaStarBindDelegate 
@optional
//绑定成功 绑定信息
- (void)onBindSeccess:(NSDictionary *)infoDic;

@end
@interface RaStarCommom : NSObject 
@property (nonatomic , weak) id  initDelegate;
@property (nonatomic , weak) id  loginDelegate;
@property (nonatomic , weak) id  payDelegate;
@property (nonatomic , weak) id  bindDelegate;

方法

/** 
此方法用于创建RaStarCommon实例，以下类方法均依赖此实例实现。
*/
+ (instancetype)sharedInstance;
/**
 设置AppsFlyer相关
 此方法需在 'didFinishLaunchingWithOptions' 中实现
 */
+ (void)setAppsFlyer;

/**
 追踪应用打开
 此方法需在 'applicationDidBecomeActive' 中实现
 */
+ (void)trackAppLaunch;

SDK 初始化方法

/**
 初始化方法

 @param appid APPID
 @param appKey APPKEY
 @param cch_id CCH_ID
 @param md_id MD_ID
 @param delegate 初始化协议
 */
- (void)initSDKWithAppID:(NSString *)appid AppKey:(NSString *)appKey cch_ID:(NSString *)cch_id md_ID:(NSString *)md_id Delegate:(id)delegate;

参数名	是否必传	默认值	说明
appid	Y	--	游戏ID
appKey	Y	--	游戏Key
cch_id	Y	--	渠道ID
md_id	Y	--	广告ID
delegate	Y	--	初始化协议

初始化返回在协议回调中获取

SDK 登录方法

/**
 登录方法

 @param delegate 登录协议
 */
- (void)loginWithDelegate:(id)delegate;

此方法在需要进行登录操作时调用。

参数名	是否必传	默认值	说明
delegate	Y	--	登录协议

注：此方法无具体登录UI展示，为方法内部静默登录，登录成功后在相关协议回调中返回access token值，并在Window层展示悬浮球。登录失败无展示，仅发送失败回调。SDK内置切换账号按钮，切换成功返回切换登录回调，回调方法附带新账号（切换后账号）的access token值。

SDK 绑定协议

/**
 添加绑定回调

 @param delegate 绑定协议
 */
- (void)setRSBindDelegate:(id)delegate;

此方法可在登录时同时添加，也可在其他CP认为的合适的时间添加.

参数名	是否必传	默认值	说明
delegate	Y	--	绑定协议

数据收集相关

/**
 创建角色上传

 @param roleId 角色ID --必传
 @param roleLevel 角色等级 --必传
 @param roleName 角色名称 --必传
 @param serverId 服务器ID --必传
 @param serverName 服务器名称 --必传
 @param partyName 公会名称 --非必传 传默认值“无”
 @param timeLevelUp 等级升级时间戳 --非必传 传默认值-1
 @param vip vip等级 --非必传 传默认值0
 @param timeCreate 创建角色时间戳 --非必传 传默认值-1
 @param balance 账号余额 --非必传 传默认值0
 @param extra 扩展字段 --非必传 传默认值extra
 */
+ (void)collectCreateRoleWithRoleID:(NSString *)roleId RoleLevel:(NSString *)roleLevel RoleName:(NSString *)roleName ServerId:(NSString *)serverId ServerName:(NSString *)serverName PartyName:(NSString *)partyName TimeLevelUp:(NSString *)timeLevelUp Vip:(NSString *)vip TimeCreate:(NSString *)timeCreate Balance:(NSString *)balance Extra:(NSString *)extra;

/**
 进入服务器上传
 
 @param roleId 角色ID --必传
 @param roleLevel 角色等级 --必传
 @param roleName 角色名称 --必传
 @param serverId 服务器ID --必传
 @param serverName 服务器名称 --必传
 @param partyName 公会名称 --非必传 传默认值“无”
 @param timeLevelUp 等级升级时间戳 --非必传 传默认值-1
 @param vip vip等级 --非必传 传默认值0
 @param timeCreate 创建角色时间戳 --非必传 传默认值-1
 @param balance 账号余额 --非必传 传默认值0
 @param extra 扩展字段 --非必传 传默认值extra
 */
+ (void)collectEnterServerWithRoleID:(NSString *)roleId RoleLevel:(NSString *)roleLevel RoleName:(NSString *)roleName ServerId:(NSString *)serverId ServerName:(NSString *)serverName PartyName:(NSString *)partyName TimeLevelUp:(NSString *)timeLevelUp Vip:(NSString *)vip TimeCreate:(NSString *)timeCreate Balance:(NSString *)balance Extra:(NSString *)extra;

/**
 角色升级上传
 
 @param roleId 角色ID --必传
 @param roleLevel 角色等级 --必传
 @param roleName 角色名称 --必传
 @param serverId 服务器ID --必传
 @param serverName 服务器名称 --必传
 @param partyName 公会名称 --非必传 传默认值“无”
 @param timeLevelUp 等级升级时间戳 --非必传 传默认值-1
 @param vip vip等级 --非必传 传默认值0
 @param timeCreate 创建角色时间戳 --非必传 传默认值-1
 @param balance 账号余额 --非必传 传默认值0
 @param extra 扩展字段 --非必传 传默认值extra
 */
+ (void)collectLevelUpWithRoleID:(NSString *)roleId RoleLevel:(NSString *)roleLevel RoleName:(NSString *)roleName ServerId:(NSString *)serverId ServerName:(NSString *)serverName PartyName:(NSString *)partyName TimeLevelUp:(NSString *)timeLevelUp Vip:(NSString *)vip TimeCreate:(NSString *)timeCreate Balance:(NSString *)balance Extra:(NSString *)extra;

/**
 新手教程完成数据收集
 */
+ (void)collectTutorialCompletion;

注：非必传参数上报时传默认值

SDK 支付相关

/**
 发起支付
 
 @param amount 金额
 @param name 角色名称
 @param level 角色等级
 @param rid 角色id
 @param sid 区服号
 @param sname 区服名称
 @param subject 产品名称
 @param orderNum 订单号
 @param ext 扩展字段
 @param delegate 代理
 */
- (void)payWithAmount:(NSString *)amount Name:(NSString *)name Level:(NSString *)level Roleid:(NSString *)rid Sid:(NSString *)sid Sname:(NSString *)sname Subject:(NSString *)subject OrderNum:(NSString *)orderNum Ext:(NSString *)ext Delegate:(id)delegate;

此接口用于发起支付时调用，成功或失败回调由协议方法回调。方法内部包含发货成功的订单号(web支付无订单号返回)，失败返回原因。

参数名	是否必传	默认值	说明
amount	Y	--	金额
name	Y	--	角色名称
level	Y	--	角色等级
rid	Y	--	角色ID
sid	Y	--	区服号
sname	Y	--	区服名称
subject	Y	--	产品名称
orderNum	Y	--	订单号
ext	N	extra	扩展字段
delegate	Y	--	代理

非必传参数发起请求时填写默认值
商品名称和金额需与后台配置完全一致
订单号需求唯一

---

附录：

内购测试时，请前往 Apple iTunes Connect 后台 所对应App 创建相关内购产品，并同步至RaStar后台进行商品配置，并申请内购沙箱账号进行测试。
Facebook登录时，请前往 Facebook开发者后台 申请测试账号进行测试，如使用真实账号，有导致封号危险。
Game Center 登录时，情前往 Apple iTunes Connect 后台 申请测试账号进行测试，真实账号在未提交Apple审核上架前无法登录成功。