GHOME SDK Development Manual for HarmonyOS

Preface

This document serves as a guide for game developers to integrate the GHome SDK for HarmonyOS, including instructions for client-side integration.

Overview of SDK Integration Process

• Obtain Privacy Consent

• Initialize the SDK

• Upon successful initialization, call the relevant account function interfaces

• Other features are under development

Integrating SDK Files into the Game Project

Please follow these steps for integration:

• Import the ghomesdk.har package

  • After dragging the .har file into the libs folder, ensure that it is added to the Library. Add the following code to the project's oh-package.json5:

    "dependencies": {
        "ghomesdk": "file:libs/ghomesdk.har"
    }
    

  • Add the following code to the products section in build-profile.json5:

    "products": [
       {
            ...
            ...
            "buildOption": {
              "strictMode": {
                "useNormalizedOHMUrl": true
              }
            }
        }
    ]
    

Development Environment Requirements:

• HarmonyOS SDK version: 5.0.0(12) or later

• DevEco Studio version:

  • DevEco Studio NEXT Developer Beta1 or later

  • Build Version: 5.0.3.403 or later

Data Structure Explanation

Detailed Explanation of GHomeBaseRet

The GHomeBaseRet is the basic structure for callbacks in the GHomeSDK, with all callback result classes inheriting from it. This class contains some basic information.

Member Variable Name	Type	Description
retCode	int	The return code of the SDK, refer to the GHomeRetCode class for details
retMsg	string	Descriptive information from the SDK
thirdCode	int	Return code from third-party channels
thirdMsg	string	Descriptive information from third-party channels
extraJson	string	Extended fields

Basic Modules (Mandatory Integration)

Privacy and Service Agreement

Based on their needs, integrators can choose to use the privacy and service agreement popup within the SDK or customize their own popup.

Before using specific functions of the SDK, users must agree to the privacy and service agreement.

Using the Internal Privacy and Service Agreement Popup of the SDK

• Interface Declaration

  doPrivacy(appId: string, callback: (ret: GHomePrivacyRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  appId	string	Required, the appId obtained from registering the game in the GHome backend

• Example Code

  GHome.getInstance().doPrivacy('xxx', (v: GHomePrivacyRet) => {
  
  })
  

• Data Structure

  Detailed explanation of GHomePrivacyRet. It inherits from GHomeBaseRet and contains basic information.

  Member Variable Name	Type	Description
  privacyPolicyUrl	string	The URL of the privacy policy, only has a value when the privacy and service agreement popup is required and a custom privacy policy is used
  serviceAgreementUrl	string	The URL of the service agreement, only has a value when the privacy and service agreement popup is required and a custom privacy policy is used
  isShow	boolean	Indicates whether the privacy policy popup is required, only has a value when a custom privacy policy is used

Customizing the Privacy and Service Agreement Popup

If the game uses a custom privacy popup, this interface can be called to obtain privacy policy information.

• Interface Declaration

  Obtain the content of the privacy and service agreement

  doCustomPrivacy(appId: string, scene: GHomePrivacyScene, callback: (ret: GHomePrivacyRet) => void): void
  

  Callback for the result of the privacy and service agreement

  setCustomPrivacyResult(isAgreePrivacy: boolean): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  appId	string	Required, the appId obtained from registering the game in the GHome backend
  scene	GHomePrivacyScene	Required, indicates the scenario: BeforeInit (before initialization) or BeforeLogin (before login)

  Parameter Name	Parameter Type	Description
  isAgreePrivacy	boolean	Required, indicates whether the user agrees to the privacy and service agreement

• Data Structure

  Detailed explanation of GHomePrivacyRet. It inherits from GHomeBaseRet and contains basic information.

  Member Variable Name	Type	Description
  privacyPolicyUrl	string	The URL of the privacy policy, only has a value when the privacy and service agreement popup is required and a custom privacy policy is used
  serviceAgreementUrl	string	The URL of the service agreement, only has a value when the privacy and service agreement popup is required and a custom privacy policy is used
  isShow	boolean	Indicates whether the privacy policy popup is required, only has a value when a custom privacy policy is used

• Notes

  If a custom privacy and service agreement popup is used, the setCustomPrivacyResult method must be called.

  The extraJson field will return complete information related to the privacy and service agreement.

Initialization

Receive the callback for the completion of GHomeSDK initialization, and the game needs to register a callback function to handle it. The game must wait for this callback to complete before invoking other module function interfaces of GHomeSDK.

• Interface Declaration

  init(appId: string, callback: (ret: GHomeBaseRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  appId	string	Required, the appId obtained by registering the game in the GHome backend

• Example Code

  GHome.getInstance().init('xxx', (v: GHomeBaseRet) => {
  
  })
  

Login (Required)

The GHomeSDK login function provides convenient login functionality for games.

• Interface Declaration

  login(callback: (ret: GHomeLoginRet) => void): void
  

• Example Code

  GHome.getInstance().login((v: GHomeLoginRet) => {
  
  })
  

• Data Structure

  Detailed explanation of GHomeLoginRet, which inherits from GHomeBaseRet and contains basic information:

  Member Variable Name	Type	Description
  userId	string	User ID
  ticket	string	Login ticket
  isGuest	boolean	Whether it is a guest login

Obtain Ticket (Required)

Retrieve the ticket.

• Interface Declaration

  getTicket(areaId: string, callback: (ret: GHomeGetTicketRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  areaId	string	Area ID

• Example Code

  GHome.getInstance().getTicket('xxx', (v: GHomeGetTicketRet) => {
  
  })
  

• Data Structure

  Detailed explanation of GHomeGetTicketRet, which inherits from GHomeBaseRet and contains basic information:

  Member Variable Name	Type	Description
  ticket	string	Ticket

Payment

To integrate Huawei's IAP Kit (In-App Payment service), please follow the official documentation (opens new window) to configure your project beforehand.

• Interface Declaration

  pay(productId: string, gameOrderId: string, areaId: string, groupId: string, extInfo: string, callback: (ret: GHomeBaseRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  productId	string	Product ID
  gameOrderId	string	Game Order ID
  areaId	string	Area ID
  groupId	string	Group ID
  extInfo	string	Additional Info

• Example Code

  GHome.getInstance().pay('productId',
                      'gameOrderId',
                      'areaId',
                      'groupId',
                      'extInfo', (v: GHomeBaseRet) => {
  
  })
  

Retrieve Server List Information

• Interface Declaration

  getAreaConfig(callback: (ret: GHomeAreaConfigRet) => void): void
  

• Example Code

  GHome.getInstance().getAreaConfig((v: GHomeAreaConfigRet) => {
  
  })
  

• Data Structure

  Detailed explanation of GHomeAreaConfigRet, which inherits from GHomeBaseRet and contains basic information:

  Member Variable Name	Type	Description
  areaList	Array	Server List

  AreaInfo

  Member Variable Name	Type	Description
  area_code	string	Area Code
  name	string	Area Name
  group_id	string	Group ID
  group_name	string	Group Name

Unregister

• Interface Declaration

  unregister(callback: (ret: GHomeBaseRet) => void): void
  

• Example Code

  GHome.getInstance().unregister((v: GHomeBaseRet) => {
  
  })
  

Logout

• Interface Declaration

  logout(callback: (ret: GHomeBaseRet) => void): void
  

• Example Code

  GHome.getInstance().logout((v: GHomeBaseRet) => {
  
  })
  

Login to Server

• Interface Declaration

  loginArea(areaId: string, groupId: string, callback: (ret: GHomeBaseRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  areaId	string	Area ID
  groupId	string	Group ID

• Example Code

  GHome.getInstance().loginArea(msg.data.areaId, msg.data.groupId, (v: GHomeBaseRet) => {
  
  })
  

Bind Activity Phone

• Interface Declaration

  bindPhone(callback: (ret: GHomeBaseRet) => void): void
  

• Example Code

  GHome.getInstance().bindPhone((v: GHomeBaseRet) => {
  
  })
  

Scan QR Code

• Interface Declaration

  scanQRCode(extendStr: string, callback: (ret: GHomeScanQRCodeRet) => void): void
  

• Parameter Description

  Parameter Name	Parameter Type	Description
  extendStr	string	Additional parameter

• Example Code

  GHome.getInstance().scanQRCode('xxx', (v: GHomeScanQRCodeRet) => {
  
  })
  

• Data Structure

  Detailed explanation of GHomeScanQRCodeRet, which inherits from GHomeBaseRet and contains basic information:

  Member Variable Name	Type	Description
  type	GHomeScanQRCodeType	QR code scan type, either 'pay' for payment or 'login' for login

FAQ

Error Code Reference GHomeRetCode

Error Code	Description	Remarks
-1	Unknown Error
0	Success
1	Cancelled
2	Privacy Policy Declined
3	Not Initialized
4	Initialization Failed
5	User Not Logged In, Please Log In
7	Unstable Network
8	Unable to Decode Content Data
9	All Channels Already Bound
10	Data Is Empty
11	Too Many Requests, Please Try Again Later
12	Window Creation Failed, Please Retry
13	Face Recognition Failed
14	Server Is Full
23	Automatic Login Ticket Expired
32	Account Restricted by Risk Control Policy
711	Personalized Account Not Bound to Security Phone
401	Payment Failed
402	One Unshipped Order Exists and Order Replenishment Failed
403	In-App Purchases Not Supported in Current Environment
404	Product Configuration Error
405	Payment Cancelled