防沉迷SDK-Android(Java)

SDK合规指南

防沉迷SDK合规指南

1 文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.56	2024.05.10	1 新增SDK合规指南；2.可选个人信息的配置。
3.3.34	2021.12.30	1.「客户端回调」新增"接收实名认证信息回调"
3.3.30	2021.11.18	1.文档从聚合SDK独立拆分出来；2.「接收实名认证信息」接口新增"scene"参数；3.「防沉迷弹窗」接口新增"scene"参数

2 接入准备

支持 Android Studio 接入

2.1 添加文件

打开下载好的 FYBase、FYAntiAddiction 目录，拷贝目录中所有 .aar 到工程的 libs 目录中

2.2 配置 gradle

打开工程的 build.gradle

• 拷贝以下代码到 android 字段下。

repositories {
    flatDir {
        dirs 'libs'
    }
}

• 拷贝以下代码到 dependencies 字段下。

implementation 'com.android.support:cardview-v7:28.0.0'
implementation 'com.android.support:appcompat-v7:28.0.0'
fileTree(dir: 'libs', include: ['*.aar']).each { file ->
    api(name: file.name.lastIndexOf('.').with {
        it != -1 ? file.name[0..<it] : file.name
    }, ext: 'aar')
}

2.3 添加SDK配置

1.到星云平台的"对接中心->SDK对接->SDK列表->基础接入参数->SDK配置参数"下载如下的配置文件：

• Android SDK 配置文件：FYCoreConfig.xml

2.打开以上的配置文件，拷贝所有meta-data配置参数到游戏的 AndroidManifest.xml 中的application标签下

3.可选个人信息的配置。如不希望本SDK采集某信息，请将对应字段的值改为0。如允许本SDK采集某信息，请将对应字段的值改为1

(1)在AndroidManifest.xml 中添加如下配置

<meta-data android:name="FY_GAME_PRIVACY" android:value="{
   "android_id ": "0 ",
   "basic_device_data" : "0",
   "os_version" : "0",
   "network_state" : "0"
}"/>

（2)字段名称说明

OS	个人信息类型及字段	用途和目的	是否可选	关闭方式
Android	设备基础信息（设备型号、硬件信息、屏幕分辨率）	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 basic_device_data 字段值为"0"
Android	Android ID	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 android_id 字段值为"0"
Android	操作系统版本	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 os_version 字段值为"0"
Android	网络状态	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 network_state 字段值为"0"
Android	OAID（版本3.3.56已去除）	帮用户排查异常时使用，作为异常分析的依据	是
Android	MAC（版本3.3.56已去除）	帮用户排查异常时使用，作为异常分析的依据	是
Android	IMEI（版本3.3.56已去除）	帮用户排查异常时使用，作为异常分析的依据	是

2.4 配置 Application

1、在游戏包名下新增一个 GameApplication 类，该类继承自 Application，请在GameApplication 类的 attachBaseContext 方法中调用以下代码：

FYAPP.getInstance().init(this);

打开 AndroidManifest.xml 在 application 将其继承于 GameApplication：

2.如果游戏已经继承于其他 Application，请在游戏自定义的 Application 类的 attachBaseContext 方法中调用以下代码：

FYAPP.getInstance().init(this);

3.以上2个步骤任选1个接入，否则会造成 SDK 错误闪退。

2.5 添加权限

打开 AndroidManifest.xml 添加如下权限配置：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2.6 添加Activity

1.在 AndroidManifest.xml 中的 添加 Activity。

<activity 
    android:name="com.stars.debuger.activity.FYDebuggerInfoActivity"
    android:windowSoftInputMode="adjustResize|stateHidden"
    android:configChanges="orientation|screenSize|keyboardHidden"/>

2.7 添加类引用

import com.stars.core.base.FYAPP;
import com.stars.antiaddiction.model.FYANLimitPayInfo;
import com.stars.antiaddiction.model.FYANRealNameInfo
import com.stars.antiaddiction.FYAntiAddiction;

2.8 添加 Activity生命周期方法

1、说明

• 调用点：onKeyDown生命周期

2、调用代码

 FYDebugger.getInstance().onKeyDown(keyCode,event);

3、参考范例

@Override
public boolean onKeyDown(int keyCode, KeyEvent event) {
    FYDebugger.getInstance().onKeyDown(keyCode,event);
    return super.onKeyDown(keyCode, event);
}

2.9 开启调试模式

1.将 AndroidManifest.xml 中的 FY_GAME_DEBUG 的值改为 1，即可开启「调试模式」；FY_GAME_DEBUG 改为 0，即关闭「调试模式」。

2.开启「调试模式」会显示客户端的悬浮球，点击进入调试工具可以查看接口/回调的调用信息，具体调试方法可查看文档。

3 界面跳转标准规范

3.1 首屏-防沉迷

3.2 游戏中-防沉迷

4 客户端接口

接口接入的要诀?

• 必接接口一定要接入，选接接口根据需要接入

• 必传参数一定要传，能传的参数尽量都传

• 所有的生命周期接口一定要接入

4.1 初始化 doInit (必接)

1.说明

• 游戏需要在刚启动游戏的时候调用。
• SDK接口在执行以后，会调用相应的回调方法，可以在回调方法中，处理相应的游戏逻辑

2.调用

FYAntiAddiction.getInstance().doInit(new FYAntiAddictionListener() {

    // 防沉迷回调 
    // 当调用 antiAddiction 接口时会将执行此回调
    @Override
    public void fyanAntiAddictionCallback(FYANResponse response) {
        if(response.getStatus()== FYANResponse.SUCCESS){
            //不符合防沉迷条件
            //可以正常进入游戏
            //可以继续进行游戏
        } else {
            //符合防沉迷条件，需要限制
            //禁止进入游戏
            //退回到登录首页
        }
    }

    // 是否到防沉迷时间回调
    // 当防沉迷时间到，或者调用 isTimeOut 接口将执行此回调
    @Override
    public void fyanTimeOutCallback(FYANResponse response) {
        //总时间
        String totalTime = String.valueOf(response.getDataValue("total_time"));
        //剩余时间
        String remainTime = String.valueOf(response.getDataValue("remain_time"));

        if(response.getStatus()== FYANResponse.SUCCESS){
            // 到达防沉迷时间
            // 游戏必须在此择机弹出防沉迷
        } else {
            // 未到达防沉迷时间
        }
    }

    // 支付限制回调
    // 当调用 limitPay 接口将执行此回调
    @Override
    public void fyanLimitPayCallback(FYANResponse response) {
        // 角色ID
        String playerId = String.valueOf(response.getDataValue("player_id"));
        // 区服ID
        String serverId= String.valueOf(response.getDataValue("server_id"));

        String openId = String.valueOf(response.getDataValue("open_id"));

        String amount = String.valueOf(response.getDataValue("amount"));

        String extra = String.valueOf(response.getDataValue("extra"));

        if(response.getStatus() == FYANResponse.SUCCESS){
            // 此用户没有被限制支付
            // 游戏继续支付流程
        } else {
            // 此用户被限制支付
            // 游戏需结束支付流程
        }
    }

    // 接收实名认证信息回调
    // 当调用 realName 并且系统确定设置实名认证信息完成后回调
    @Override
    public void fyanRealNameCallback(FYANResponse fyanResponse) {

        if(fyanResponse.getStatus() == FYANResponse.FYANResponseSuccess){
            // 表示设置实名认证信息已完成
            // 可以继续执行后续的防沉迷逻辑（防沉迷弹窗、充值限制等）
        } else {
            // 设置实名认证信息失败
            // 失败信息
            String msg = response.getMessage();
            Log.i("xxx", msg);
        }
    }
});

3.参数

无

4.2 接收实名认证信息 realName (必接)

1.说明

• 此接口用来接收实名认证信息，为后续防沉迷做准备，如果此接口没有完成调用，则后续的防沉迷行为不会生效
• 若有接入聚合渠道SDK，必须在聚合渠道SDK的loginCallBack回调和realNameCallBack回调中调用，并将相关的实名信息传进来

2.调用

FYANRealNameInfo info = new FYANRealNameInfo();
info.setUnionId("xxx");
info.setOpenId("xxx");
info.setIdentityBirthday("2015-01-01");
info.setIdentityAge("10");
info.setScene("1"); 
FYAntiAddiction.getInstance().realName(info);

3.参数

参数	说明	是否必传
unionId	渠道维度唯一用户ID	是
openId	游戏维度唯一用户ID	是
identityBirthday	出生日期(1995-10-11)	是
identityAge	年龄	是
scene	调用场景，"1":在登录回调中调用，"2":在实名认证回调中调用，"0":其他地方调用	是

4.回调

• 接收实名认证信息回调 fyanRealNameCallback

4.3 防沉迷弹窗 antiAddiction (必接)

1.说明

• 调用此接口，若用户已达到防沉迷条件，则会弹出防沉迷窗口
• 必须在点击"进入游戏"时调用，然后根据回调判断是否继续进入游戏
• 必须在fyanTimeOutCallback回调中择机调用此接口，以在游戏中及时弹出防沉迷弹窗

2.调用

FYANAntiAddictionInfo info= new FYANAntiAddictionInfo();
info.setScene("1"); 
FYAntiAddiction.getInstance().antiAddiction(info);

3.参数

参数	说明	是否必传
scene	调用场景，"1":在进入游戏时调用，"2":防沉迷时间到达时调用，"0":其他地方调用	是

4.回调

• 防沉迷回调 fyanAntiAddictionCallback

4.4 是否到防沉迷时间 isTimeOut (选接)

1.说明

• 调用此接口可以获取是否到防沉迷时间，以及防沉迷剩余时间
• 此接口会回调 fyanTimeOutCallback

2.调用

FYAntiAddiction.getInstance().isTimeOut();

3.参数

无

4.回调

• 是否到防沉迷时间回调 fyanTimeOutCallback

4.5 限制充值 limitPay (必接)

1.说明

• 调用此接口，若用户已达到充值限制，则会弹出充值限制窗口
• 必须在点击"充值"时调用，然后根据回调判断是否继续充值
• 此接口会回调fyanLimitPayCallback，此接口传入的所有参数会原封不动的从回调中传出

2.调用

FYANLimitPayInfo info = new FYANLimitPayInfo();
info.setPlayerId("xxx");
info.setServerId("1");
info.setOpenId("xxx");
info.setAmount("600");
info.setExtra("xxx");
FYAntiAddiction.getInstance().limitPay(info);

3.参数

参数	说明	是否必传
playerId	角色ID	是
serverId	区服ID	是
openId	游戏维度唯一用户ID	是
amount	金额（分）	是
extra	额外参数	否

4.回调

• 支付限制回调 fyanLimitPayCallback

4.6 生命周期(必接)

• 在游戏界面 Activity 相应的生命周期方法中调用，必须全部都接入。

2.调用

• onStart()

FYAntiAddiction.getInstance().onStart();

• onStop()

FYAntiAddiction.getInstance().onStop();