10/22/2024 16:10:38

Android Access Guide

[info] Version Notes
minSdkVersion : 15
targetSdkVersion : 28+

I. Project Configuration

1.1 File List

1.2 AndroidManifest Configuration

<!--TDM begin-->
<!-- Network Communication-->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Get network status -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<!-- Get MAC address -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<!--TDM end-->

<application>
    <!-- TDataMaster configuration -->
    <meta-data android:name="GCloud.TDM.AppId" android:value="@string/tdm_AppId" />
    <meta-data android:name="GCloud.TDM.AppChannel" android:value="@string/tdm_AppChannel" />
    <meta-data android:name="GCloud.TDM.Protocol" android:value="@string/tdm_Protocol" />
    <meta-data android:name="GCloud.TDM.Test" android:value="true"/>
</application>

You need to notice this when accessing TDM components. As for TDataMaster's configuration description, please refer to TDM Channel Documentation.

Modify the launch mode, launchmode, of the main Activity of the game to singleTask. The demo configuration is as follows:

<activity
    android:name=".StartupActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:launchMode="singleTask"
    android:taskAffinity="com.tencent.itop.example">
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
</activity>

II. Frame Operation Example

2.1 Initialization

It is needed to invoke UI thread

MSDKPlatform.initialize(this);

2.2 The Key Points of the Lifecycle

It is needed to mark onActivityResult, onNewIntent and onRequestPermissionsResult
The other cycle functions of Activity have been actively hooked, and games do not need to handle them

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

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

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

2.3 C++ access [optional]

Place the header file into project/app/src/main/cpp folder:

In CMakeLists.txt, add .so file. For example:

ADD_LIBRARY(libMSDKCore.so SHARE IMPORTED)
SET_TARGET_PROPERTIES(
    libMSDKCore.so
    PROPERTIES IMPORTED_LOCATION
    ${CMAKE_CURRENT_SOURCE_DIR}/libs/${ANDROID_ABI}/libMSDKCore.so
)

[warning] If the third-party library libThird.so calls the interfaces of libMSDKCore.so, it is needed to call MSDK to initialize it at first

Otherwise, the "undefined linked" error will be reported. The correct approach should be:

MSDKPlatform.initialize(this);
System.loadLibrary("Third");

2.4 Interface Calling Method

When starting activity, call MSDKPlatform.initialize() initialize MSDK SDK

  @Override
  protected void onCreate(@Nullable Bundle savedInstanceState) {
      super.onCreate(savedInstanceState);
      ...
      // All initialization entrances are placed here
      MSDKPlatform.initialize(this);
      ...
    }

2.5 Create a callback listener

Take the login as an example. Implement MSDKLoginObserver interface and create a listener instance, as follows:

private class LoginObserver implements MSDKLoginObserver{

        @Override
        public void onBaseRetNotify(MSDKRet baseRet) {
            MSDKLog.d("onBaseRetNotify, result = " + formatString(baseRet));
            handleLoginResult(baseRet);
        }

        @Override
        public void onLoginRetNotify(MSDKLoginRet loginRet) {
            MSDKLog.d("onLoginRetNotify, result = " + formatString(loginRet));
            handleLoginResult(loginRet);
        }
        private void handleLoginResult(MSDKRet baseRet){
            switch (baseRet.retCode) {
                case MSDKErrorCode.SUCCESS:
                    showResult ("Login succeeds", formatString (baseRet));
                    break;
                case MSDKErrorCode.LOGIN_ACCOUNT_REFRESH:
                    showResult ("Account inconsistency: Refresh token via URL", formatString (baseRet));
                    break;
                case MSDKErrorCode.LOGIN_URL_USER_LOGIN:
                    showResult ("Account inconsistency: Log in successfully with URL", formatString (baseRet));
                    break;
                case MSDKErrorCode.LOGIN_NEED_SELECT_ACCOUNT:
                    showDiffLogin ();
                    break;
                case MSDKErrorCode.LOGIN_NEED_LOGIN:
                    showResult ("Account inconsistency: It is needed to enter the login page", formatString (baseRet));
                    break;
                case MSDKErrorCode.NEED_NAME_AUTH:
                    // Real name authentication
                    break;
                default:
                    showResult ("Login notification  (unknown message) ", formatString (baseRet));
                    break;
            }
        }
    }

If login succeeds, the system will return SUCCESS; if login fails, the system will return the corresponding error code, and you can process the error according as you need.

2.6 Set callback listener

Set listener through MSDKLogin class's setLoginObserver, as shown as follows:

//init observer
MSDKLogin.setLoginObserver (new LoginObserver ());

2.7 Call the special information control interface

Since MSDK5.20 version, the special information switch and special information setting-related capabilities are controlled by the game side itself. Before the switch is turned on, MSDK itself as well as Beacon, QQ OpenSDK and Bugly components cannot obtain special information; the game side needs to actively turn on MSDK's special information switch and actively set the relevant special information to MSDK after the user agrees to the relevant terms of the Tencent Game User Agreement; otherwise, this will affect the data acquisition of MSDK and the data acquisition and data statistics of the Beacon component.

2.7.1 Special information switch

1) Interface declaration

// Set whether to allow the collection of special information
MSDK_EXPORT_UE static void SetCouldCollectSensitiveInfo (bool couldCollect);

2) Demo code

MSDKSensitive:: SetCouldCollectSensitiveInfo (true);

3) Warning

• The game side must actively call the interface after the user agrees to the relevant terms of the Tencent Game User Agreement; otherwise, this will affect the relevant information acquisition of MSDK and Beacon components. In addition, QQ OpenSDK3.5.7 (corresponding to MSDK5.20.001) has updated permissions-related functions. The accessing party cannot use various functions of QQ OpenSDK before calling SetCouldCollectSensitiveInfo to make authorization. The log will report an error like "The user is not authorized and is temporarily unable to use QQ login as well as Sharing and other functions".
• Before the game engine is started or MSDK is initialized, the Android side can call the Java interface MSDKSensitive.setCouldCollectSensitiveInfo (true) ; in the Java layer in advance to turn on the switch.
• After MSDK is initialized, the switch can be controlled only via C++ interfaces. Please do not use the Java interface to control it.
• Multi-process scenes are not explicitly supported. It is recommended that all calls for the component's special information switch interface be placed in the main process, or the child process can call the component's special information switch interface by itself.

2.7.2 Special information settings

1) interface declaration

// Set the special information field to each component SDK in the form of json; currently support {"AndroidID": "xxx","WiFiMacAddress": "xxx","Imei": "xxx"}
MSDK_EXPORT_UE static void SetSensitiveInfo (const String &jsonInfo) ;

2) Demo code

char *jsonInfo = "{\"AndroidID\": \"xxx\", \"WiFiMacAddress\": \"xxx\", \"Imei\": \"xxx\"}";
MSDKSensitive: : SetSensitiveInfo (jsonInfo) ;

3) Warning

• The game side must actively call the interface to set the `AndroidID` field (`AndroidID` needs to be obtained by the game itself) after the user agrees to the relevant terms of the Tencent Game User Agreement; otherwise, the data statistics of the Beacon component will be affected.
• Since MSDK5.28.001(GCloud2.2.10.1), the smartphone model must be passed to OpenSDK, otherwise authorization cannot be made. If APP does not set the `Model` field, MSDK will obtain and process it internally. If all of the above measures fail, APP will not be able to use the related functions of QQ-Connect OpenSDK. In addition, not passing in the `Model` value can affect the effect of Beacon's mid-stage algorithm.
• Before the game engine is started or MSDK is initialized, the Android side can call Java interface MSDKSensitive.setSensitiveInfo (jsonInfo) ; in the Java layer in advance to set relevant special information.
• After MSDK is initialized, the relevant special information can be set only via C++ interfaces. Please do not use the Java interface to set it.

2.8 AndroidID & Apn collection configuration

Starting from MSDK5.23.001, the code switch and configuration switch for the collection of AndroidID & Apn for individual fields have been added. Games can configure whether these fields are allowed to be collected according to their needs.

Preconditions: V5.20 and above, and SetCouldCollectSensitiveInfo is set to true.

Description of collection switch priority:

• Both the code and the configuration have values: the code switch shall prevail;
  
• Both the code and the configuration are empty: default collection;
  
• Either the code or configuration has a value: the value obtained shall prevail.
  

2.8.1 Code switch interface declaration

// Set the special information single-field switch in json form; currently support setting AndroidID and Apn; A parameter example: {"AndroidID":true,"Apn":true}
// `value` in the parameter is the code switch situation of the corresponding field. It can be collected when the switch is set true
MSDK_EXPORT_UE static void SetCollectSensitiveInfo(const String &jsonInfo);

2.8.2 Demo code of the code switch

char *jsonInfo = "{\"AndroidID\":true,\"Apn\":true}";
MSDKSensitive::SetCollectSensitiveInfo(jsonInfo);

2.8.3 Configuration switch

The configuration switch is located in MSDKConfig.ini, and the corresponding configuration item is MSDK_DENIED_COLLECT_LIST. This configuration item is a list of special fields that are not allowed to be collected. Currently, the special fields are AndroidID and Apn. The configuration example is as follows:

//The configuration item is located in MSDKConfig.ini. By default, the list of special fields that are not allowed to be collected is empty. Multiple fields shall be connected with English commas.
MSDK_DENIED_COLLECT_LIST =

2.8.4 Warning

• Before the game engine is started up or before MSDK is initialized, the Android side can invoke the Java interface, MSDKSensitive.setCollectSensitiveInfo(jsonInfo), at the Java layer in advance; set the code switch for single-field collection in advance;
  
• After MSDK is initialized, the code switch can only be controlled through the C++ interface. Please do not use the Java interface to control it;
  
• Multi-process scenes are not explicitly supported. It is recommended to place the setting interface invocation of the code switch in the main process or to invoke the interface by the sub-process itself.
  

2.9 Call API

The MSDK interfaces are designed by different modules. Before calling them, please find the corresponding module, such as Login, Friend, WebView, etc. Taking Login as an example, the call example is as follows:

// Log in the channel according to the channel settings
permissions = getChannelTestPermissions (mSelectedChannel);
//Log in mSelectedChannel channel
MSDKPlatform.Login.login (permissions, mSelectedChannel, mSelectedSubChannel, "");

Note:

• Different modules have their own Observer, their return codes are not the same, but their call methods are similar
• One module has only one Observer. The last one takes effect after multiple settings
• In case of account inconsistency, Observer set by the login module needs to be between the onCreate and onResume lifecycles of the entry Activity

III. MSDKPolicy Access

3.1 Overview

MSDKPolicy is a universal Android data permission policy process implementation solution. It integrates the user agreement and permission authorization process, and provides games with quick access through configuration. Reference document for the user agreement update:https://docs.qq.com/doc/DSnlkYU5SZWhPYmNR

The application process of MSDKPolicy is as follows:

3.2 Access steps

3.2.1 Involved documents

It is used to configure the content of the agreement. A default agreement reviewed by the legal department has been provided

It is used to configure the list of permissions required for App and instructions for their uses. The current content is for Demo display. The business needs to modify it according to the actual situation of its own App. The necessary permissions need to be placed in front places and should be marked with (necessary) to highlight the prompt

It is used to configure the necessary permissions for polling in the permission application process. During the polling process, the necessary permissions will be applied for from the user

3.2.2 Configuration guidelines

(1) Introduce MSDKPolicy

Important: Introduce MSDKPolicy by adding the following configuration in AndroidManifest.xml

<activity 
    android:name="com.tencent.gcloud.msdk.core.policy.MSDKPolicyActivity"
    android:configChanges ="keyboard|keyboardHidden|screenLayout|screenSize"
    android:launchMode="singleTask"
    android:theme="@style/MSDKPolicyTheme">
    <!-- Set MSDKPolicy as the main activity, and display it once it starts -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN" />
        <category android:name="android.intent.category.LAUNCHER" />
        <category android:name="android.intent.category.LEANBACK_LAUNCHER" />
    </intent-filter>
    <!-- MSDK_POLICY_TARGET_ACTIVITY is used to specify the activity (the first activity of the app or game) to skip to -->
    <meta-data android:name="MSDK_POLICY_TARGET_ACTIVITY" android:value="{your_main_acitivity}" />
    <!-- Open MSDKPolicy's Debug, which is the user's debugging output log -->
    <meta-data android:name="MSDK_POLICY_DEBUG" android:value="true"/>
    <!-- In order to comply with the latest process requirements, the MSDK_RESULT_FILE_NAME configuration is closed by default since MSDKCoreV5.17 version; -->
    <!-- After removing this configuration, if the user has not agreed to the protocol before, the protocol will be popped up in the case of overwriting installation, no matter whether the user has logged in App before the overwriting the installation; -->
    <!-- If your game newly accesses MSDKPolicy, it is also recommended that you should comment out the following MSDK_RESULT_FILE_NAME configuration to meet the latest requirements. -->
    <!-- <meta-data android:name="MSDK_RESULT_FILE_NAME" android:value="itop_login.txt"/> -->
    <!-- It is used to mark the agreement version. Once the agreement is updated, the number shall be added with 1. Please fill in an integer value -->
    <meta-data android:name="MSDK_POLICY_VERSION" android:value="1" />
</activity>

Warning:

MSDK_POLICY_TARGET_ACTIVITY is used to specify App's Activity or the first Activity of the game to be skipped to at the end of the process, and the value of the MSDK_POLICY_TARGET_ACTIVITY parameter needs to be adjusted to the startup Activity of the game.
Please keep the remaining parameters consistent with the example.
Please configure the screen orientation of MSDKPolicyActivity to be the same as your game or app through android: screenOrientation to get a better experience.

Important: After adding the above configuration, you need to delete the LAUNCHER and MAIN tags of the mainactivity in your game

<activity
    android:name=".StartupActivity"
    android:configChanges="orientation|screenSize|keyboardHidden"
    android:launchMode="singleTask"
    android:taskAffinity="com.tencent.itop.example">
    <!-- Comment out MAIN and LAUNCHER in intent-filter, because the activity is no longer the first activity started -->
    <!-- <intent-filter>-->
    <!-- <action android:name="android.intent.action.MAIN" />-->
    <!-- <category android:name="android.intent.category.LAUNCHER"/>-->
    <!-- <category android:name="android.intent.category.LEANBACK_LAUNCHER" />-->
    <!-- </intent-filter>-->
</activity>

(2) MSDKPolicy is divided into two parts

User Agreement:

When the user clicks the App icon to start the game, the user agreement will be initiated (as shown in the figure above). The content of the agreement in the figure can be configured. Currently, a default agreement is provided for games. If you want to modify it, please contact the legal affairs department to make the risk assessment. The content of the agreement can be configured in the resource file msdk_policy_content.html, which only supports basic html tags. If you want to make your chess & card game access MSDK, please contact the legal affairs department to confirm the agreement and link address for the chess & card game by yourself, and make corresponding adjustments.

<!doctype html>

<head>
    <meta charset='UTF-8'>
    <meta name='viewport' content='width=device-width initial-scale=1'>
    <title></title>
</head>

<body>
<p>Before you use our (Tencent) services, please read carefully and fully understand the clauses of
    <a href='http://game.qq.com/contract.shtml'>Tencent Game License and Service Agreement</a>,
    <a href='http://game.qq.com/privacy_guide.shtml'>Tencent Game Privacy Protection Guidelines</a>,
    <a href='https://game.qq.com/privacy_guide_children.shtml'>Tencent Game Children's Privacy Protection Guidelines</a> and
    <a href="https://game.qq.com/zlkdatasys/privacy_SDK.html">The Third-party Information Sharing List</a>. <strong>At the same time, you should pay special attention to the clauses in the aforementioned agreements that exempt or limit our liabilities, the clauses that restrict your rights, and the clauses that stipulate the resolution modes and legal jurisdiction of disputes. </strong>If you have carefully read and agreed to
    <a href='http://game.qq.com/contract.shtml'>Tencent Game License and Service Agreement</a>,
    <a href='http://game.qq.com/privacy_guide.shtml'>Tencent Game Privacy Protection Guidelines</a>,
    <a href='https://game.qq.com/privacy_guide_children.shtml'>Tencent Game Children's Privacy Protection Guidelines</a> and
    <a href="https://game.qq.com/zlkdatasys/privacy_SDK.html">The Third-party Information Sharing List</a>, please click "Agree" to start using our services.</p>
</body>

</html>

Required permission application process:

After the user clicks to agree, enter the permission description page and start the necessary permission application process, as shown in the figure below.

The content in the permission description page can be configured. Game developers need to sort out all the permissions of their App and list them in the configuration. Among them, the necessary permissions need to be clearly marked as shown in the above figure. The configuration file is msdk_permission_content.html. It only supports basic html tags.

<p>In order to ensure your gaming experience, we will apply for the following permissions during your use of our service. By then, you can choose to agree or refuse to open the relevant permissions. If you refuse, this will affect some functions: </p>
<br/>
<p><strong>Storage permission </strong></p>
<p>Cache images/videos to reduce traffic consumption</p>
<br/>
<p><strong>Mobile phone/phone permission</strong></p>
<p>Verify IMEI&IMSI code to prevent account theft</p>
<br/>
<p><strong>Location permission </strong></p>
<p>Get your location information, so that you can play with nearby players</p>
<br/>
</ul>

When the user clicks the "Confirm" button on the permission description page, he or she starts to apply for necessary permissions.

During this process, the user will be polled to obtain the necessary permissions. Business needs to configure the necessary permissions required in their own App to the msdk_permission_list of values/values.xml, for example.

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <array name="msdk_permission_list">
        <item>android.permission.ACCESS_FINE_LOCATION</item>
    </array>
</resources>

The necessary permissions are configured in this configuration. Then in the above diagram, a pop-up box will pop up for the user to apply for configuring the necessary permissions (if not authorized).
The location permission configured above is only an example. Games can configure permissions according to their own needs.Please note: When there are multiple permissions, it is recommended to leave array blank and apply for permissions from the user as needed.

Starting from MSDK5.23.001, the MSDKPolicy plugin permission description page has supported configuration.
If msdk_permission_content.html is set empty or is deleted, the permission description page will not be popped up. After the user clicks the "Agree" button on the agreement page, he or she can directly enter the game.

3.3 Warning

1. After the user clicks "Agree" on the agreement page, TDM will be opened to report the in-app event tracking data and the device information. You can contact MSDK Assistant to assist in verification;
   
2. The necessary permissions in the msdk_permission_list of values.xml need to be consistent with the permissions highlighted (necessary) in msdk_permission_content.html;
   
3. After the access is completed, you must do a critical path test. Paths such as login & relationship & sharing & game center start & account inconsistency must be covered in the test.