05/15/2024 15:19:45

The Client's Channel Access Rules

The overall architectural logic of the MSDK client is as follows

The interface layer and the Core layer are the common logic for all channels and are provided by MSDK as components. Developers only need to implement the newly accessed channel code according to the MSDK open platform's access rules.

I. Channel naming rules

1.1 Android Platform

A new channel added to the Android platform is named in the project directory: Channel name, where the channel name is made of lowercase English letters, such as: garena,qq, google Channel package name (package name) rules: com.tencent.gcloud.msdk.channel, such as: com.tencent.gcloud.msdk.garena

1.2 iOS Platform

A new channel added to the iOS platform is named under the project directory as follows: MSDK + channel, where the channel name is case sensitive For example: MSDKGarena, MSDKQQ, MSDKGameCenter

II. Version number rules

The version number is divided into two types: string version number and numeric version number

2.1 String version number, which is divided into four sections from front to back:

• Major version number, fixed to 5
• Feature version number, which must be consistent with MSDK Core version number
• Plugin version number, 3 digits in length, incremented when the logic changes

• Build version number, which can take SVN or GIT version mark

  Example: "5.0.010.123"

2.2 Numeric version number

Take the first three sections of the string version number For example: When the string version number is "5.0.010.123", the numeric version number is 50010

2.3 View method:

• Android Platform
  In Android's build plugin jar package, BuildConfig file content, for example:

   package com.tencent.gcloud.msdk.garena;
  
   public final class BuildConfig
   {
      // Numeric version number
      public static final int VERSION_CODE = 50010;
      // String version number
      public static final String VERSION_NAME = "5.0.010.123";
   }
  

• iOS Platform iOS places the following content in the header file in the way of macro definition, for example:

   // String version number
   #define MSDKGarena_Version_String "5.0.010.2280"
  
   // Numeric version number
   #define MSDKGarena_Version_Int 50010
  

III. Code development rules

3.1 Singleton mode

MSDK plugins are all in the singleton mode

• In the Android platform, the singleton mode is supported by the MSDK Core package and does not require any plugin processing
• In the iOS platform, the singleton mode needs to be completed by the plugin

Precautions:

• In the Android platform, the constructor is called only once
• In the iOS platform, there are two ways to implement singletons:
  • Define it by the singleton macro provided by MSDK, add SYNTHESIZE_SINGLETON_FOR_CLASS_HEADER (class name) to the interface of the class, and add SYNTHESIZE_SINGLETON_FOR_CLASS (class name) to the `implementation' of the class
  • If the channel plugin needs to make some processing during initialization, please refer to the way shown in MSDKPushXG to perform some initialization operations while guaranteeing the singleton case

3.2 Lifecycle Processing

MSDK provides a unified lifecycle processing mechanism. It is recommended that the lifecycle in the plugin be handled according to the general rules of MSDK. The implementation way is:

• Android Platform
  1. Create a channel name (case sensitive) + LifeCycleObserver class, which implements the ILifeCycle interface to handle the lifecycle of the app
  2. In the MSDKConfig.ini configuration file, add the channel name (case sensitive, separated by commas) in the MSDK_LIFECYCLE_OBSERVERS configuration item, so that the channel's lifecycle is monitored when the app starts
• iOS Platform
  In MSDKApplicationDelegate, the game can autonomously implement the required functions in the system's listening function

3.2.1 Android LifeCycleObserver class

The LifeCycleObserver class is often used in case that the channel SDK needs to handle the lifecycle. It can be optionally implemented.

• Package naming rule: fixed as com.tencent.gcloud.msdk
• Class naming rules: channel name (case sensitive) + LifeCycleObserver, such as:GarenaLifeCycleObserver
• Must implement the ILifeCycle interface

3.2.2 iOS MSDKApplicationDelegate class extension

The MSDKApplicationDelegate class extension is often used in case that the channel SDK needs to handle the lifecycle. It can be optionally implemented.

• File naming rules: MSDKApplicationDelegate + channel, such asMSDKApplicationDelegate+Garena.mm
• Class naming rule: MSDKApplicationDelegate (channel), such as: MSDKApplicationDelegate (Garena)
• List of supported lifecycle processing functions:

3.3 Report the plugin's version number

It is recommended to report the corresponding plugin version numbers of all the plugins that accesses MSDK. Such reporting can be used for version monitoring and statistics. MSDK has provided the function interface for version reporting. It is only needed to call the corresponding method in the plugin.

1. Android Platform

   /* MSDK plugin reporting function
   * It is recommended that each plugin report the plugin information through MSDK's reporting interface
   * - pluginVer plugin version number, which is recommended to get from BuildConfig. For rules, please refer to the description of the version number definition in plugin's build.gradle file
   * - sdkName plugin name, which is usually the channel name, such as: Garena
   * - sdkVer channel SDK version, which is generally obtained from the channel SDK, such as: GGPlatform.GGGetSDKVersion(). If not available, it can be empty
   * - seqID is the calling sequence ID. It is alright to directly return the ID passed by function to it. If not available, it can be empty
   * - extra is extension information. It is allowed to pass in the user-defined JSON structure string to it. If not required, it can be empty
   */
   IT.reportPlugin(BuildConfig.VERSION_NAME, "Garena",GGPlatform.GGGetSDKVersion(), seqID, "{}");
   

2. iOS Platform

   /** MSDK plugin reporting function
      * It is recommended that each plugin report the plugin information through MSDK's reporting interface
      * The function is the implementation of the macro definition mode. The prototype:
      * - REPORT_PLUGIN(pluginName, pluginVer, sdkName, sdkVer, seqID, extraJson)
      *   - pluginName plugin name, which is usually MSDK + channel, such as: MSDKGarena
      *   - pluginVer plugin version number string
      *   - sdkName plugin name, which is usually the channel name, such as: Garena
      *   - sdkVer channel SDK version, which is generally obtained from the channel SDK, such as: GG::GGPlatform::GetInstance()->GGGetSDKVersion(). If not available, it can be empty
      *   - seqID is the calling sequence ID. It is alright to directly return the ID passed by function to it. If not available, it can be empty
      *   - extraJson is extension information. It is allowed to pass in the user-defined JSON structure string to it. If not required, it can be empty
      */
   REPORT_PLUGIN("MSDKGarena", MSDKGarena_Version_String ,"Garena",
                  GG::GGPlatform::GetInstance()->GGGetSDKVersion().c_str(),"", "{}");
   

3.4 Callback description

After the processing of most plugins' interfaces is completed, the plugin processing results need to be called back to MSDK Core to further process the data. For example, after successful login, the login results need to be passed to MSDK Core. MSDK Core will sned the request to the server for login authentication. The callback's parameters include: ObserverID, MethodID, and seqID

Description of related fields:

3.4.1 Observer ID: ObserverID

Each ObserverID corresponds to a processing method in MSDK Core. These processing methods are used to further process the processing result of the plugin after the plugin is called back.

Note:

• There may be a method corresponding to multiple ObserverID (for example, Android Login method has the callback MSDK_LOGIN_OBSERVER_LOGIN_PLUGINin case of success and has the callbackMSDK_LOGIN_OBSERVER_LOGIN_RET in case of error)
• It is also possible that multiple methods correspond to an ObserverID (for example, the share and sendMessage methods of Android's Friend module both correspond to MSDK_FRIEND_OBSERVER_DELIVER_MESSAGE). For details, please refer to the specific module development documentation

3.4.2 Method ID - MethodID

Generally, each method has a MethodID, the same as ObserverID. But if MethodID is different, the corresponding processing logic is also different.

Note: There are multiple MethodID for the Login method of the Login module. So when making a callback, the plugin developer tries to choose the MethodID passed in from the method to make a callback, so as to ensure that the callback is correct

[info] Special case
For some functions, the plugin needs to actively call back the result to MSDK Core. For example, after the Push module receives a push message, it needs to actively call back it to MSDK Core

3.4.3 Return struct - Ret

The return struct is used to preserve the processing result of the plugin, including the following fields:

• methodNameID: MethodID, which is the function ID defined by MSDK, used for the definition of the callback method
• retCode: MSDK error code. Common error code definitions can be found in the MSDKErrorCode class or assets/MSDKRetMsg.json error information configuration file. Instructions on the use of common error codes are as follows:
  • SUCCESS: return successfully
  • CANCEL: operation is cancelled. It is recommended to return this value when the channel operation is canceled
  • THIRD: channel error, which is returned when the channel operation fails. At this time, thirdCode must be assigned with a value
• retMsg: MSDK's error information, filled in as appropriate
• thirdCode: channel error code, which is returned according to the channel error code definition
• thirdMsg: channel error information, filled in by following the channel error information
• extraJson: extension information, which can be used by the plugin to pass the user-defined parameter. It is a JSON string

3.4.4 Callback function description

1. Android Platform
   Use the unified callback processing method IT.onPluginRetCallback Function prototype:

   public static native void onPluginRetCallback(int observerID, MSDKRet ret, String seqID);
   

   • observerID callback function ID
   • ret return struct must be a subclass of MSDKRet
   • seqID is the call sequence's ID, which can be directly filled in with the sequence ID passed in by the function

2. iOS Platform
   The unified callback processing method MSDKInnerObserverHolder<T>::CommitToTaskQueue, where the generic parameter T needs to be the same as the type RetType of the return struct ret Function prototype:

   static void CommitToTaskQueue(const RetType &ret, const unsigned int observerID, const String &seqID)
   

   • ret return struct
   • observerID callback function ID
   • seqID is the call sequence's ID, which can be directly filled in with the sequence ID passed in by the function

IV. Channel plugin packaging rules

4.1 Android Platform

It is recommended to package the release version as aar, then unpack aar and organize it into the ADT project directory structure, and then package the directory structure and place the package into the game

• The folder and jar package naming rules are unified as: msdk-channel, such as:msdk-garena
• Pay attention to organizing AndroidManifest.xml and the files in the 'res' directory

4.2 iOS Platform

[info] Packaging environment
The packaged version of iOS Framework must be C11, otherwise cross-library issues may exist

The package can be named as the same with the plugin, that is "Framework", and then unveil the corresponding plugin function header file. For example: