Skip to content

Android Overseas AAB Access Document

Description

  • aab is a resource format for uploading applications to Google Play
  • (must be adapted to Android 14 system version, otherwise it will affect the launch of Google Play)
  • Recommended to export Android Studio project package using Unity
  • If the game is connected for the first time, you must do a good job of full-screen adaptation for Android phones (common adaptation methods are generally displayed in full screen by default. The top notch or camera-related relationship cannot affect the game-related UI functions, otherwise it will affect the rating during cloud testing)
  • Make sure that all interfaces calling the SDK are placed in () call
  • Note that the interface in Unity is called to java needs to be switched to the UI thread and then called the SDK interface.
  • Please be sure to check the document in detail. If you have any questions about some access parts, you can directly communicate with the technical team in the docking group.
  • This document will be updated from time to time. If interface changes are involved, messages will be synchronized within the group. For more updates, please checkAndroid SDK更新
  • Click here to proceedAndroid-AAB-Demo 下载

Access process

Description

    1. Find relevant parameters and configurations for operation application. Currently, access requires three configuration files, google-services.json, access.config and keystore signature files.
    1. Download the Demo sample project, use the file to configure the relevant project structure of the Demo
    1. Configure the remote warehouse configuration and call the relevant interfaces

Parameter configuration ()

project:build.gradle

xml
buildscript {
    repositories {
        maven {
            url 'https://sdk.wdyxgames.com/nexus/repository/sdk-public/'
        }
    }
}

allprojects {
    repositories {
        maven {
            url 'https://sdk.wdyxgames.com/nexus/repository/sdk-public/'
        }
    }
}

Or configure under settings.gradle

xml
pluginManagement {
    repositories {
        maven {
            url 'https://sdk.wdyxgames.com/nexus/repository/sdk-public/'
        }
    }
}
dependencyResolutionManagement {

    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        maven {
            url 'https://sdk.wdyxgames.com/nexus/repository/sdk-public/'
        }
    }
}

app:build.gradle configuration ()

Note: When apk is out of package, only the hoolai-core library can be referenced.

xml
//引入google插件 id 'com.google.gms.google-services'
plugins {
    id 'com.android.application'
    id 'com.google.gms.google-services'
}

//引入依赖库
dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    //hoolai-core(必接)
    implementation 'com.hoolai.access.open:hoolai-core:1.0.4.0-global'
    //access-native(必接)
    implementation 'com.hoolai.access.platform:access-native:0.1.2.1425-global'
    //fangzhou(必接)
    implementation 'com.hoolai.access.open.fangzhou:fangzhou:4.5.16.10'
    //基础功能模块,登录/支付/分享等(必接)
    implementation 'com.hoolai.oversea:hl-oversea-global:1.0.5.0' 
    //aihelp(必接)
    implementation 'com.hoolai.oversea.aihelp:aihelp:1.0.0.1'
    //appsflyer(必接)
    implementation 'com.hoolai.oversea.appsflyer:appsflyer:1.0.0.2'
    //firebase(必接)
    implementation 'com.hoolai.oversea.firebase:firebase:1.0.1.0'
    //facebooklinks(必接)
    implementation 'com.hoolai.oversea.links:facebooklinks:1.0.1.0'
    //openInstall(选接)
    implementation 'com.hoolai.oversea.opins:openInstall:1.0.0.0'
    //crashlytics(⚠️该库已废弃,和firebase类库已合并)
    //implementation 'com.hoolai.oversea.crash:crashlytics:1.0.0.0'
}

AndroidManifest.xml configuration ()

The following configurations are Google Authorized Login, Facebook Authorized Login, and Google Play Games Services v2 Authorized Login configuration. If you do not need it, you can not configure it (verified in the demo here)

javascript
<!--Games Services Sign In v2 如要使用PGS登录必须配置!否则不需要加-->
<meta-data android:name="com.google.android.gms.games.APP_ID"
    android:value="@string/game_services_project_id"/>
<!--Games Services Sign In v2 如要使用PGS登录必须配置!否则不需要加-->

<!--注意需为游戏的启动类 Activity 中配置intent-filter!以下为示例无需 copy!-->
<activity
    android:name="com.hoolai.access.demo.GameActivity"
    android:hardwareAccelerated="true"
    android:launchMode="singleTask"
    android:theme="@style/HlAccountTransparent"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
    </intent-filter>
    
    <!-- SDK内部配置(必须) 其中scheme的value值为accesssdk+channelId-->
    <intent-filter>
        <action android:name="android.intent.action.VIEW"/>
        <category android:name="android.intent.category.BROWSABLE"/>
        <category android:name="android.intent.category.DEFAULT"/>
        <data android:scheme="accesssdk1"/>
    </intent-filter>
    <!-- SDK内部配置(必须) 其中scheme的value值为accesssdk+channelId-->
</activity>
<!--注意需为游戏的启动类 Activity 中配置intent-filter!示例无需 copy!-->

<!--Facebook login share-->
<provider
    android:name="com.facebook.FacebookContentProvider"
    android:authorities="com.facebook.app.FacebookContentProvider1234567890"
    android:exported="true" />

<meta-data
    android:name="com.facebook.sdk.ApplicationId"
    android:value="@string/facebook_app_id" />

<meta-data
    android:name="com.facebook.sdk.ClientToken"
    android:value="@string/facebook_client_token" />

<activity
    android:name="com.facebook.CustomTabActivity"
    android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.VIEW" />

        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />

        <data android:scheme="@string/fb_login_protocol_scheme" />
    </intent-filter>
</activity>
<!--Facebook end-->

The above parameter configuration location is configured in the res/values/strings.xml file, and the following parameters are provided by the operation.

javascript
<string name="facebook_app_id">facebookAppId</string>
<string name="fb_login_protocol_scheme">fbScheme</string>
<string name="facebook_client_token">facebookClientToken</string>
<string translatable="false"  name="game_services_project_id">googleProjectId</string>

Interface Documentation

Lifecycle access

Application access ()

Method 1: Use HLApplication when the game has no custom Application. Refer to the <application name tag attribute configuration in AndroidManifest.xml

Method 2: If the game has a custom Application, you can inherit HLApplication.

Method 3: When the game has a custom Application and cannot inherit HLApplication, the following calls are required during the Application life cycle:

java
public class YourApplication extends YourBaseApplication {

    @Override
    public void onCreate() {
        super.onCreate();
        FastSdk.onApplicationCreate(this);
    }

    @Override
    public void onTerminate() {
        super.onTerminate();
        FastSdk.onTerminate(this);
    }

    @Override
    public void onConfigurationChanged(Configuration newConfig) {
        super.onConfigurationChanged(newConfig);
        FastSdk.onConfigurationChanged(this, newConfig);
    }

    @Override
    protected void attachBaseContext(Context context) {
        super.attachBaseContext(context);
        FastSdk.attachBaseContext(this, context);
    }
}

Activity life cycle access ()

java
@Override
protected void onSaveInstanceState(Bundle outState) {
    super.onSaveInstanceState(outState);
    FastSdk.onSaveInstanceState(outState);
}

@Override
protected void onStart() {
    super.onStart();
    FastSdk.onStart(this);
}

@Override
protected void onResume() {
    super.onResume();
    FastSdk.onResume(this);
}

@Override
protected void onStop() {
    super.onStop();
    FastSdk.onStop(this);
}

@Override
protected void onPause() {
    super.onPause();
    FastSdk.onPause(this);
}

@Override
protected void onRestart() {
    super.onRestart();
    FastSdk.onRestart(this);
}

@Override
protected void onDestroy() {
    super.onDestroy();
    FastSdk.onDestroy(this);
}

@Override
protected void onNewIntent(Intent intent) {
    super.onNewIntent(intent);
    FastSdk.onNewIntent(intent);
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    FastSdk.onActivityResult(this, requestCode, resultCode, data);
}

@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
    super.onRequestPermissionsResult(requestCode, permissions, grantResults);
    FastSdk.onRequestPermissionsResult(requestCode, permissions, grantResults);
}

@Override
public void onConfigurationChanged(Configuration newConfig) {
    super.onConfigurationChanged(newConfig);
    FastSdk.onConfigurationChanged(this, newConfig, getResources());
}

@Override
public void onBackPressed() {
    FastSdk.exit();
}

@Override
public Resources getResources() {
    return FastSdk.getResources(super.getResources());
}
//以下为更新内容
@Override
protected void onRestoreInstanceState(@NonNull Bundle savedInstanceState) {
    super.onRestoreInstanceState(savedInstanceState);
    FastSdk.onRestoreInstanceState(savedInstanceState);
}

@Override
public void onWindowFocusChanged(boolean hasFocus) {
    super.onWindowFocusChanged(hasFocus);
    FastSdk.onWindowFocusChanged(hasFocus);
}

SDK function access

Initialization ()

WARNING

  • During the initialization of SDK, suggestions for solving the black screen of the game: prepare a picture called "unity_static_splash" and copy it to the res/drawable directory.
  • This interface is called first after the game is started. can the hot update/version detection/game initialization/login and other functions be called.
  • The game cannot make subsequent function calls when the initialization callback is not received or onInitFailed is received.
  • If the initialization fails, it is recommended to guide the user to restart the game.
java
//游戏主Activity的onCreate中
//SDK初始化回调
FastSdk.hlSystemListener = new HLSystemListener() {
    @Override
    public void onInitSuccess(InitResult initResult) {
        //gameId,channelId,channel
    }

    @Override
    public void onInitFailed(String reason) {
       
    }

    @Override
    public void onCustomExit() {
        /* demo 只作为参考,游戏应该根据自己所需逻辑实现
         * 渠道没有退出二次确认框
         * 根据需要加二次确认框
         */
        //渠道不存在退出界面,如百度移动游戏等,此时需在此处弹出游戏退出确认界面,否则会出现渠道审核不通过情况
        //游戏实现自己的退出界面 ,实现退出逻辑,请勿直接照搬demo
        //根据需要加二次确认框
        new AlertDialog.Builder(GameActivity.this)
                .setTitle("游戏退出弹窗")
                .setMessage("我是游戏的弹窗界面哦")
                .setNegativeButton("取消", null)
                .setPositiveButton("确定", (dialog, which) -> onExitSuccess(s))
                .setCancelable(false).show();
    }

    @Override
    public void onExitSuccess(String result) {
        //如果渠道有退出界面,点击渠道退出后会触发该回调用于释放游戏资源,也有可能此时程序已被kill不会执行到此处,可预留处理一些资源释放操作
        //处理退出逻辑
        moveTaskToBack(true);
        finish();
        //建议游戏按照下面代码逻辑,退出程序兼容性最好,否则可能会造成oppop、vivo等渠道退出不彻底,导致再次点击启动应用黑屏。
        Intent intent = new Intent(Intent.ACTION_MAIN);
        intent.addCategory(Intent.CATEGORY_HOME);
        intent.setFlags(Intent.FLAG_ACTIVITY_CLEAR_TOP);
        startActivity(intent);
        android.os.Process.killProcess(android.os.Process.myPid());
    }

    @Override
    public void onUpdate(String data) {
        //版本升级
    }
};

//SDK账号回调
FastSdk.hlAccountListener = new HLAccountListener() {
    @Override
    public void onRefreshUser(LoginResult result) {
         //小号切换,此回调中之需要游戏验证用户合法性问题,无小号可忽略
         //如果游戏不支持内部切换玩家信息,游戏需要调用登出,再重新登录(不需要重新初始化)
    }

    @Override
    public void onLoginSuccess(LoginResult result) {
         
    }

    @Override
    public void onLoginFailed(String reason) {
    
    }

    @Override
    public void onLogout(Object... var1) {
       
    }
};

//SDK支付回调
FastSdk.hlPaymentListener = new HLPaymentListener() {
    @Override
    public void onPaySuccess(String result) {
        
    }

    @Override
    public void onPayFailed(String reason) {

    }
    
    
    @Override
    public void onQuerySuccess(List<GoodsInfo> list) {
        //海外游戏必须处理,获取商品列表用于展示
    }
};

//SDK分享回调
FastSdk.hlShareListener = new HLShareListener() {
    @Override
    public void onShareSuccess() {

    }

    @Override
    public void onShareFailed(String reason) {

    }
};

//SDK初始化,此方法需要在启动游戏时的隐私权限回调方法中调用
//后面的所有SDK功能都需要在初始化回调成功之后调用
//注意:调用onCreate之前需要将以上用到的接口先进行实例化
FastSdk.onCreate(this);

Log in ()

WARNING

  • When calling this method, make sure that the "game_init_result" event has been executed. For more details, please refer to 游戏自定义报送
  • Initialization does not receive a callback or the login interface is prohibited when initialization fails
java
FastSdk.login();

User Center ()

java
//调用时机必须在登录成功之后
FastSdk.openAccountCenter(activity);

Obtain product list information ()

java
//调用时机,必须在确认登录成功之后使用!
//必须在登录成功之后或商品详情界面展示之前调用,注意查询成功后会通过FastSdk.hlPaymentListener接口中将所有商品信息回调回来
//注意由于商品信息获取为异步获取,如登录成功之后由于网络等原因无法获取到商品信息或获取为空,请在打开游戏商城界面时或下次支付之前增加判断再次获取
//如果始终无法获取到商品信息,请使用游戏内默认配置的商品信息展示支付,注意要和 SDK 管理台中配置的商品信息保持一致
FastSdk.queryGoodsInfo();

Payment ()

java
//调用支付之前需要先进行基础事件的报送,比如创角,进服,升级等
PayParams payParams = new PayParams();
payParams.setItemId("item60");//商品ID,必传
payParams.setItemName("60钻石");//商品名称,必传
payParams.setAmount(100);//商品金额,必传,单位:分
payParams.setNotifyUrl("");//支付回调地址,非必传,如不设置可不写
//扩展信息,回调时原样返回,因为各渠道回调参数限制不一致。
//回调参数暂时只支持长度255。callBackInfo中不要使用这些符号:“|”、“=”、“+”、“/”。
payParams.setCallbackInfo("支付扩展信息,游戏透传参数");
payParams.setCurrency("USD");//币种通过商品信息接口查询获取,必传
FastSdk.pay(activity, payParams);

Data reporting ()

Note (the basic data must be reported before payment)

When reporting data for Chuangjiao, server entry, upgrade and other events, roleId, roleName, serverId, and serverName parameters cannot be empty and must be transmitted, otherwise it will affect the payment function! ! 其他必接数据请查看

java
//eventType取值:
//创角: EventType.CreateRole
//进服: EventType.EnterServer
//升级: EventType.LevelUp
//前三种是必须上报,下面这种根据运营需求进行自定义事件上报
//自定义点:EventType.CustomerEvent,设置自定义点位后必须设置setExtendAction("game_init"),setPhylum("14")等

PlayerInfo playerInfo = new PlayerInfo();
playerInfo.setRoleId("32424");//角色唯一标识id,必传
playerInfo.setRoleName("昵称");//必传,String
playerInfo.setRoleLevel("6");//必传,注意字符串必须是数字,比如"123"
playerInfo.setZoneId("1");//必传,没有可传默认值"1",注意字符串中的值必须为数字
playerInfo.setZoneName("华东大区");//必传,没有可传默认值,比如"1区"等
playerInfo.setServerId("1");//必传,没有可传默认值"1",注意字符串中的值必须为数字
playerInfo.setServerName("区名称");//必传,没有可传默认值,比如"1区"等
playerInfo.setBalance("66");//必传,获取不到时传""
playerInfo.setVip("5");//必传
playerInfo.setPartyname("帮派名称");//非必传

//新增内容: extra必须携带数据,参考客户端数据报送特殊数据报送
//扩展信息,格式:key:value,key:value
playerInfo.setExtra("a:arm,b:bom,gameResourceUrl:xxx,gameLoginServerUrl:xxx");
playerInfo.setClassField("");//事件结果,可不填
//playerInfo.setPhylum("");//扩展数据报送时需要按照提供的事件编号填写,如:1
//playerInfo.setExtendAction("点位名称"); //基础打点不传,自定义打点传
FastSdk.report(EventType.EnterServer, PlayerInfo playerInfo);

DANGER

  • Students who need to access the CLS network detection function should pay attention! ! ! 点击查看规则详情
  • Please submit this function as soon as possible after the SDK is initialized. You can submit it separately or report it with other points.
  • The detection address can be a domain name or IP
  • Replace colons in the detection address with @ to avoid format errors
  • The following three fields must be used for the detection address: gameResourceUrl, gameLoginServerUrl, gameServerUrl

如:playerInfo.setExtra("key:value,gameResourceUrl:http@xxx/open/init, gameServerUrl:tcp@111.222.333.6@8888");

** event type **

Parameter nameDescriptionRequired
EventType.CreateRoleCreate RoleYes
EventType.EnterServerGames into serverYes
EventType.LevelUpRole UpgradeYes
EventType.CustomerEventCustomYes

PlayerInfo

Parameter nameTypeDescriptionRequired
roleIdStringRoleid idYes
roleNameStringRole NameYes
roleLevelStringLevelYes
zoneIdStringRegion id, no serverIdYes
zoneNameStringRegion name, no serverNameYes
serverIdStringServeridYes
serverNameStringServer NameYes
balanceStringBalanceYes
vipStringvip levelYes
partyNameStringGuild NameNo
appVersionStringApplication Version NumberYes
appResVersionStringGame Resource Version NumberYes
extendActionStringEvent NameYes
roleCreateTimeStringRoleCreateTimeYes
phylumStringEvent id, refer to the "Client Data Reporting" documentYes
classFieldStringEvent result, ok/failNo
extraStringExtended information (note: this field is used by the cls report point)No

Customer service call (select)

java
FastSdk.openService(activity);

System sharing and Facebook sharing (optional connection)

java
ShareParams params = new ShareParams();
params.setTitle("标题");
params.setContent("内容");
params.setPicPath("picPath");//本地或网络图片链接
params.setShareUrl("http://xx.com");

//FACEBOOK
params.setBmp(bmp); 

FastSdk.share(ShareType.FACEBOOK, ShareType.ChildType.WX_CHAT, params);

Ark SDK reporting interface (selected)

Additional game data reporting, such as certain special levels, data, etc. in the game, if access is not required, you may not be connected.

java
String action = "game_xxx";
Map<String, Object> hashMap = new HashMap<>();
hashMap.put("xxx", 123);
hashMap.put("ooo", "321");
FastSdk.gameDataReport(action, hashMap);

Appsflyer (optional)

appsflyer deep chain configuration. If other appsflyer reporting functions are integrated, the SDK will automatically introduce relevant configurations to take effect by default.

xml
<!--appsflyer 深度链接(选接,非必接),此处参数配置由运营直接在appsflyer后台查看获取,需添加到游戏入口启动类中-->
  <intent-filter  android:autoVerify="true">
      <action android:name="android.intent.action.VIEW" />
      <category android:name="android.intent.category.DEFAULT" />
      <category android:name="android.intent.category.BROWSABLE" />
      <data android:scheme="https"android:host="xxxx-brand.onelink.me"android:pathPrefix="xxx" />
  </intent-filter>
  <!--appsflyer 深度链接 end-->

Firebase (optional)

Only the firebase dependency library needs to be added, the functions are automatically integrated on the SDK side and can be used directly

Aihelp (select)

Only need to add the aihelp dependency library, which can be called through the customer service interface

Import the above dependency library and add callback interface listening

java
//_TODO:Facebook DeepLink回调,该接口选接_
_//使用时必须在初始化之前配置,如需使用该功能需要先去Facebook后台填写游戏的启动Activity,且需要在游戏入口类配置scheme启动<intent-filter>_
//具体可参考https://developers.facebook.com/docs/applinks/add-to-content
FastSdk.hlDeepLinkListener = new HLDeepLinkListener() {
    @Override
    public void onDeepLinkSuccess(String jsonStr) {
        //返回内容可参考https://developers.facebook.com/docs/applinks/navigation-protocol?locale=zh_CN
    }
};

openInstall(选接

Import dependencies for interface monitoring

xml
<meta-data android:name="com.openinstall.APP_KEY" android:value="OPENINSTALL_APPKEY"/>

<!--AndroidManifest.xml 游戏主Activity-->
<activity android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTask">
        <intent-filter>
            <action android:name="android.intent.action.VIEW"/>
            <category android:name="android.intent.category.DEFAULT"/>
            <category android:name="android.intent.category.BROWSABLE"/>
            <data android:scheme="OPENINSTALL_SCHEME"/>
        </intent-filter>
</activity>

WARNING

WillOPENINSTALL_APPKEYReplace with openinstall assigned to the applicationappkey,WillOPENINSTALL_SCHEMEReplace with the real scheme parameter, provided by the operation here

The user shares and opens it after installation. After logging in, the user will successfully callback in the SDK. UserInfo. The key is added to getMap. openInstall_channelCode 与 openInstall_appData You can obtain relevant data here for processing the corresponding logic

Firebase Crashlytics(选接

  1. Build.gradle configuration in the root directory of the project
xml
plugins {
    //Make sure that you have the AGP plugin 8.1+ dependency
    id 'com.android.application' version '8.1.4' apply false
    //...

    //Make sure that you have the Google services Gradle plugin 4.4.1+ dependency
    id 'com.google.gms.google-services' version '4.4.2' apply false

    //Add the dependency for the Crashlytics Gradle plugin
    id 'com.google.firebase.crashlytics' version '3.0.2' apply false
}
  1. Build.gradle configuration under the app module
xml
plugins {
        id 'com.android.application'
        //Make sure that you have the Google services Gradle plugin
        id 'com.google.gms.google-services'
        //Add the Crashlytics Gradle plugin
        id 'com.google.firebase.crashlytics'
}

//引入依赖库
dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    ...
    implementation 'com.hoolai.oversea.crash:crashlytics:1.0.0.0'
}
  1. If you need to add other additional functional configurations, there are already examples of Demo, please refer to demo to access.官方文档

Catappult Payment

The build.gradle configuration in the root directory of the project is replaced by the following dependency implementation 'com.hoolai.oversea:hl-oversea-global:1.0.5.0'

xml
//引入依赖库
dependencies {
    implementation fileTree(include: ['*.jar'], dir: 'libs')
    //如需接入catappult支付渠道请引用下面这个依赖,注意与com.hoolai.oversea:hl-oversea-global:${version}两个依赖同时只能引入一个
    implementation 'com.hoolai.oversea:hl-oversea-global-catappult:1.0.5.1'
    //access-native 1.0.2.1426版本及以上版本
    implementation 'com.hoolai.access.platform:access-native:0.1.2.1426'
}

Q&A

Initialization failed and a "non-authentic application" prompt appears. How to deal with it?

The signature file is incorrect. If there is no signature file, you can contact the operation classmate.

Don't have an account when logging in with account secret?

The account password login method does not have a registration function, and the operation classmate needs to provide an account/password.

How to test sandbox environment payment?

Confirm with the operation classmates to ensure that the sandbox environment is turned on and that the account has been added to the test whitelist.

Can't get payment?

Check whether the event of a creator or server entry is reported when entering the game.

Payment successfully cannot be paid?

  1. Check whether the provided payment callback url is correct.

  2. Check the payment interface, whether setNotifyUrl(url) is called in the payment parameters, and if it is called, this url will be called first.

The floating ball is not hidden when logging out of the game in the channel package

Fastsdk.logout() is not called in the game. It is recommended that the game "Settings" interface make two buttons: "Switch Server" and "Switch Account", and call logout when executing "Switch Account".

Hoolai Access SDK