客户端接入指南

本文档面向 Android开发者，描述的接入方式适合运营在 4399 平台的独代游戏。

SDK 说明

用户信息与隐私策略

SDK 中使用的用户信息及隐私策略参考：4399 通行证用户服务协议

功能描述

为4399独家代理的游戏提供的SDK，提供游戏激活、礼包、更新等服务，和游戏官方消息官方活动、论坛等丰富而优质的游戏内容

若游戏有被静态修改后二次打包的情况，SDK 对此类破解提供了一些解决方案，详见 服务端文档

SDK 组成

客户端 SDK

客户端支持的编译配置 android:minSdkVersion >= 16。
从SDK 3.2.0开始，优先支持aar接入方式，发布结构遵循 Android Studio（as） 规范
若游戏只能以 jar+res 方式接入，请参考 jar+res 依赖引入

服务端 API

服务端支持额外的功能，参考 SDK 服务端接入文档

集成流程

准备

首次接入 SDK，要在 4399 开放平台 注册应用，主要是提交游戏包、游戏素材等信息。
完成后，开发者将得到 SDK 的基础参数：game key或GameKey，游戏在 4399 平台的运营标识

引入依赖

repositories {
    maven {
        // 4399 SDK 开放仓库：正式
        url 'https://mvn.4399doc.com/repository/maven-releases'
    }
    maven {
        // 4399 SDK 开放仓库：快照
        url 'https://mvn.4399doc.com/repository/maven-snapshots'
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
    
    // 运营 SDK：建议使用最新版本，可通过浏览仓库地址或向运营咨询版本
    implementation "cn.m4399.sdk:operate:3.2.0"
    
    // volley 和 support 是 SDK 使用的外部依赖，若接入方已有，可忽略
    implementation 'com.android.volley:volley:1.2.0'
    //noinspection GradleCompatible
    implementation "com.android.support:support-v4:28.0.0"
}

operate/libs/volley-v1.2.0.jar
operate/libs/support-v13-23.2.1.jar

Gradle 文件中注意添加本地依赖

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar','*.aar'])
}

abi 适配与 so 库

若游戏不需要支持所有 abi ，可以按需选用

android {
    defaultConfig {
        ndk {
            // 根据游戏需要选择
            abiFilters "armeabi", "armeabi-v7a", "x86", "arm64-v8a"
        }
    }
}

jar+res依赖引入 比较繁琐，但是完成后，后续接口调用仍然是一样的。

AndroidManifest 额外配置

在游戏项目的AndroidManifest.xml中，需要注册存储权限和渠道标识

<!-- 接入方应在调用接口前，申请好运行时权限 -->
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    
<application ....>       
    <!-- 渠道标记，4399官方渠道为‘4399’，其他渠道可与运营确认 -->
    <meta-data android:name="FTNN_CHANNEL_ID" android:value="4399"/>
</application>

接入方应在调用接口前，申请好运行时权限，可以使用EasyPemissions 第三方类库快速处理

接口调用：初始化（必须）

SDK 初始化后才能正确调用其他接口，建议在游戏Activity的开始处如 onCreate方法中进行。 此接口内部自动完成“更新、激活、防沉迷”等流程。

public class MainActivity extends Activity
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        // ....
        // 初始化 SDK
        // 配置全局属性，如横竖屏配置
        OperateConfig operateConfig = new OperateConfig.Builder(this)
                // 设置调试模式，可选，true时打开，默认false,发布前必须设置为false或删除该行
                .setDebugEnabled(false)
                // 设置游戏运营 key，此参数需要在原创开放平台注册应用后得到
                .setGameKey(GAME_KEY)
                // 设置SDK页面方向，应与游戏方向一致，部分第三方页面需要在AndroidManifest中设置
                .setOrientation(GameSettings.ORIENTATION)
                // 设置游戏是否兼在高于Android 9.0版本系统容全面屏，默认不兼容
                .compatNotch(GameSettings.COMPACT_NOTCH)
                .build();
        ExclusiveAgent.init(this, operateConfig, new ExclusiveAgent.OnInitGlobalListener() {            /*
             * 激活状态回调
             *
             * code 激活禁用 1:激活成功 2:已激活过
             * msg  状态说明
             */
            @Override
            public void onActivationState(int code, @NonNull String msg) {
            }

            /*
             * 初始化完成，玩家在此处可以安全进入游戏
             */
            @Override
            public void onInitFinished() {
            }
        });
    }
}

接口调用：游戏盒跳转（推荐）

初始化之后，可以调用游戏盒跳转接口，这些接口可以大大丰富游戏内容、补充游戏功能。

使用活动码

/*
 使用活动码
 your_activity_id: 活动ID，向运营获取
 your_activity_code: 活动码，用户输入
*/
ExclusiveAgent.useActivityCode("your_activity_id", 
    "your_activity_code", 
    new OpeResultListener() {
    @Override
    public void onResult(int code, @Nullable String message) {
        // code 0:成功 3:失败 5:异常中止
    }
});

使用礼包码

/*
 使用礼包码
 your_gift_id: 礼包ID，向运营获取
 your_gift_code: 礼包码，用户输入
*/
ExclusiveAgent.useGiftCode("your_gift_id", 
    "your_gift_code", 
    new OpeResultListener() {
    @Override
    public void onResult(int code, @Nullable String message) {
        // code 0:成功 3:失败 5:异常中止
    }
});

游戏盒跳转

原有的游戏盒跳转，即礼包、活动、论坛、游戏盒详情接口，迁移为通用跳转接口，开发应需要向运营获取跳转参数，跳转方式参考下文通用跳转接口

接口调用：通用跳转（推荐）

游戏可能需要更多形式的跳转，为此 SDK 对此进行支持。具体实现为：

// 先判断是否支持key的协议
OperateAction.support(key, new OpeResultListener() {
        @Override
        public void onResult(int code, @Nullable String msg) {
            // 使用key进行跳转，0为支持，其他不支持
            if (code == 0) { 
                OperateAction.perform(key);
            }
        }
    });

极少数跳转需要传递额外参数，如图片分享，此时要使用另一个接口

// 入口 key
// 跳转intent，intent的内部是键值对
OperateAction.perform(key, intent);