GHOME SDK DOC - Payment Center

# Integration

# Android Integration

Follow the GHOME SDK Development Manual for Android | GHOME SDK Documentation - Payment Center (opens new window) to complete the integration of the GHOME SDK.

Copy GHomeBridge.h/cpp to the Classes directory and add compilation in CMakeLists.txt. GHomeBridge.h is the entry point for all calls.

# ...
list(APPEND GAME_HEADER
        Classes/GHomeBridge.h
        )

if(ANDROID)
    list(APPEND GAME_SOURCE
    # ...
         Classes/GHomeBridge.cpp
         )
elseif(LINUX)
1
2
3
4
5
6
7
8
9
10
11

In the Android project, copy GHomeBridge.java to the com.shengqu.cocos.ghome directory. It cannot be placed in any other path and must remain consistent.

# iOS Integration

Complete the GHOME SDK integration for iOS related configurations according to the Mobile Game Expressway SDK Development Manual for IOS | GHOME SDK Documentation - Payment Center (opens new window).

# Basic Features (Mandatory)

# Display Privacy Agreement Functionality via SDK Call

  • Interface: static void DoPrivacyAgreement(std::string appId, const GHomeCallback &callback);
  • Parameter Description
Parameter Description
appId ID obtained from the MobiLink platform for the game
callback Callback object to return execution results; refer to code examples.

Note: If the game implements the privacy agreement related popup functionality itself, there’s no need to call this interface. Otherwise, it is mandatory.

GHOME::GHomeBridge::DoPrivacyAgreement(
    "791000008",
    [=](int code, std::string message,
        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        log("DoPrivacyAgreement callback, code: %d, message: %s, ", code,
            message.c_str());
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            // The SDK's privacy policy functionality has been invoked and consented to; proceed with subsequent game logic
        } else {
            // If the player disagrees with the privacy policy, exit.
            Toast::ShowToast("Player disagree privacy policy");
        }
    });
1
2
3
4
5
6
7
8
9
10
11
12
13

# Check Whether Privacy Agreement Popup Should Be Displayed

  • Interface: static void GetAgreementStatus(std::string appId, bool isForLogin, const GHomeCallback &callback);
  • Parameter Description
Parameter Description
appId ID obtained from the MobiLink platform for the game
isForLogin Query before calling login interface (true), otherwise query at startup (false)
callback Callback object to return execution results; refer to code examples.

Note: If the game implements privacy agreement related popup functionality itself, it must call this interface and should use the Privacy Agreement Result Feedback Interface for confirmation of acceptance.

GHOME::GHomeBridge::GetAgreementStatus(
    "791000008", false, CC_CALLBACK_3(HelloWorld::onAgreementCallback, this));

void HelloWorld::onAgreementCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    auto iter = params->find("status");
    if (GHOME::ERROR_CODE_SUCCESS == code && iter != params->end() &&
        "1" == iter->second) {
        // Game handles the privacy agreement display itself
        auto content = params->find("privacyContent");

        auto size = getContentSize();
        auto dialog =
            CustomPrivacyDialog::create(Color4B::WHITE, size.width * 0.6,
                                        size.height * 0.5, content->second);
        dialog->setAnchorPoint(Vec2::ANCHOR_MIDDLE);
        dialog->setIgnoreAnchorPointForPosition(false);
        dialog->setCallback([=](bool isAgree) {
            if (isAgree) {
                initButton->setEnabled(true);
                GHOME::GHomeBridge::OnUserAgreement(true, true);
            } else {
                GHOME::GHomeBridge::OnUserAgreement(true, false);
                Director::getInstance()->end();
            }
        });
        dialog->setPosition(size / 2);
        addChild(dialog);
    } else {
        Toast::ShowToast("no need show dialog, it's agree");
        initButton->setEnabled(true);
        GHOME::GHomeBridge::OnUserAgreement(false, true);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# Privacy Agreement Result Feedback Interface

  • Interface: static void OnUserAgreement(bool isUserAction, bool isAgreed);
  • Parameter Description
Parameter Description
isUserAction Whether the user actively agrees to the privacy agreement (true for active choice, false otherwise)
isAgreed Whether the user agrees to the privacy agreement

Note: If the game does not have a privacy agreement popup, it needs to configure parameters in the backend and use the SDK’s built-in privacy agreement popup.

GHOME::GHomeBridge::OnUserAgreement(false, true);
1

  • Interface: static void Initialize(std::string gameId, const GHomeCallback &callback);

  • Parameters:

    Parameter Description
    gameId The ID obtained from the direct bus platform for the game.
    callback Callback object used to return execution results; see code examples for details.

  • Notes:

    When starting the game, it is necessary to determine if there is a network connection on the device. If no network connection exists, the game must implement a pop-up prompt for the user.

    Unless otherwise specified, calling any other interfaces before successfully initializing will likely result in errors; ensure that initialization has been completed successfully before calling any other interfaces.

GHOME::GHomeBridge::Initialize(
    "791000008",
    CC_CALLBACK_3(HelloWorld::onGHomeBridgeInitializeCallback, this));

void HelloWorld::onGHomeBridgeInitializeCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {

    if (GHOME::ERROR_CODE_SUCCESS == code) {
        Toast::ShowToast("Initialization successful");
    } else if (GHOME::EVENT_ACCOUNT_LOGOUT == code) {
        // The account has been logged out here. Handle the logic for logging out in your game.
    } else if (GHOME::EVENT_ACCOUNT_CHANGED == code) {
        // Account switch was successful here. Use the obtained userid and ticket to verify login data on the game server.
        // If needed, retrieve information from 'data' after a successful login.
        // 'userid' is the player's user ID in our platform;
        // 'ticket' is the authentication token received for verifying the legitimacy of this login with the platform servers.
    } else if (GHOME::EVENT_ACCOUNT_LOGOUT_ONLY == code) {
        // The account has been logged out here. Handle logout logic only without logging back in.
    } else if (GHOME::EVENT_EXIT_GAME == code) {
        // When exiting through a channel floating window, the game will receive a notification to perform exit operations.
        // No confirmation dialog is required for exiting the game.
    } else {
        Toast::ShowToast("Initialization failed");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Offline Kick Reporting Interface

  • Interface: static void KickOff();
  • Notes: It is recommended to call this interface when a user is kicked offline.
GHOME::GHomeBridge::KickOff();
1

# Client Login Interface

The game client can call the login interface to provide players with a login function. If it is the user’s first time logging in, both the login and registration interfaces will be displayed. If the user has successfully logged in using an account before, they will automatically log in with that same account. (Important: If the game uses its own privacy policy pop-up functionality, the query interface to check whether a privacy policy needs to be shown must be called prior to invoking login. For details on the query interface, see GHOME SDK Development Manual for Android | GHOME SDK Documentation - Payment Center (opens new window))

  • Interface: static void login(const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
callback Callback object for returning execution results, see code examples for details.
GHOME::GHomeBridge::login(CC_CALLBACK_3(HelloWorld::onLoginCallback, this));

void HelloWorld::onLoginCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    if (GHOME::ERROR_CODE_SUCCESS == code) {
        if (params->empty())
            return;
        std::string userId;
        if (params->find(KEY_USER_ID) != params->end()) {
            userId = params->at(KEY_USER_ID);
        }
        UserStorage::setUserId(userId);
        std::string isGuest;
        if (params->find(KEY_IS_GUEST) != params->end()) {
            isGuest = params->at(KEY_IS_GUEST);
        }
        UserStorage::setIsGuest(isGuest);
        std::string ticket;
        if (params->find(KEY_TICKET) != params->end()) {
            ticket = params->at(KEY_TICKET);
        }
        verifyTicket(ticket);
    } else if (GHOME::ERROR_CODE_LOGIN_CANCEL == code) {
        Toast::ShowToast(message);
    } else if (GHOME::ERROR_INIT_NOT_FINISHED == code) {
        GHOME::GHomeBridge::Initialize(
            gameIdBtn->getString(),
            CC_CALLBACK_3(HelloWorld::onGHomeBridgeInitializeCallback, this));
    } else {
        Toast::ShowToast(message);
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

# Client Logout Interface

  • Interface: static void logout(const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
callback Callback object for returning execution results, see code examples for details.
GHOME::GHomeBridge::logout(
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            Toast::ShowToast("Logout successful");
        } else {
            Toast::ShowToast("Logout failed");
        }
    });
1
2
3
4
5
6
7
8
9

# Account Switching Interface

  • Interface: static void SwitchAccount(const GHomeCallback& agreementCallback, const GHomeCallback& onSwitchAccountCallback);
  • Parameter Descriptions
Parameter Name Description
agreementCallback Used to receive privacy policy notifications. When this callback is received, the game will display its own privacy policy based on the status. If using the SDK’s privacy policy feature, pass a null object or omit it.
onSwitchAccountCallback Callback object for execution results; please refer to code examples for details.
GHOME::GHomeBridge::SwitchAccount(
    [=](int code, std::string message,
        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            auto iter = params->find("status");
            if (iter != params->end()) {
                auto status = iter->second;
                if ("1" == status) {
                    // Simulate game's own handling of privacy policy display
                } else {
                    GHOME::GHomeBridge::OnUserAgreement(false, true);
                }
            }
        }
    },
    [=](int code, std::string message,
        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            auto userId = params->find("userid");
            auto iter = params->find("ticket");
        } else {
            Toast::ShowToast("Switching account failed.");
        }
    });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# Client Account Deletion Interface

  • Interface: static void WrittenOff(const GHomeCallback &callback);
  • Parameter Descriptions
Parameter Name Description
callback Callback object for execution results; please refer to code examples for details.
GHOME::GHomeBridge::WrittenOff(
    [=](int code, std::string message,
        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            Toast::ShowToast("Account deletion successful.");
        } else {
            Toast::ShowToast("Code: " + std::to_string(code) +
                             ", Message: " + message);
        }
    });
1
2
3
4
5
6
7
8
9
10

# Client Payment Interface

  • Interface: static void Pay(std::string groupId, std::string orderId, std::string areaId, std::string productId,std::string extend, const GHomeCallback &callback);
  • Parameter Descriptions
Parameter Name Description
groupId Group ID. Leave empty (“”) if no actual data is available.
orderId Game order number; a unique string can be used to identify this order if the game needs to record it.
areaId Area ID.
productId Product ID, typically product code in the payment context.
extend Additional parameters; leave empty (“”) unless required for specific use cases.
callback Callback object for execution results; please refer to code examples for details.

  • Notes on Required Parameters:

    • Payment interface parameter flow (e.g., groupId, areaId): Game APP client → Ghome SDK → payment server → game server → player database.
    • Whether parameters are required and any specific requirements are determined by the payment server and game server teams.
    • Different games may have varying data requirements; for uncertain values, confirm with Ghome SDK and game service development leads.

  • Important Considerations: Due to possible network latency or other factors, client-side payment results might differ from actual outcomes. For final confirmation of successful payments, the platform’s server notification should be used as the primary reference, while client notifications serve as supplementary information.

GHOME::GHomeBridge::Pay(groupId, orderId, areaId, product.productCode, "",
                        CC_CALLBACK_3(PayScene::onPayCallback, this));

void PayScene::onPayCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    isPaying = false;
    if (GHOME::ERROR_CODE_SUCCESS == code) {
        Toast::ShowToast("Payment successful.");
    } else {
        scheduleOnce([=](float time) { Toast::ShowToast("Payment failed."); }, 0.1,
                     "pay");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Client Interface for Retrieving Game Server List

  • Interface: static void GetAreaConfig(const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
callback Callback object to return the execution result, see code examples for more details.
GHOME::GHomeBridge::GetAreaConfig(CC_CALLBACK_3(SelectAreaScene::onAreaCallback,
                                                 this));

void SelectAreaScene::onAreaCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    if (GHOME::ERROR_CODE_SUCCESS == code && !params->empty()) {
        auto data = params->find("data");
        if (data != params->end()) {
            auto areaData = data->second;
            CCLOG("areaData: %s", areaData.c_str());
        }
    } else {
        Toast::ShowToast("Failed to retrieve server list, please try again later.");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Client Interface for Retrieving Game Item List

  • Interface: static void GetProductConfig(const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
callback Callback object to return the execution result, see code examples for more details.
GHOME::GHomeBridge::GetProductConfig(CC_CALLBACK_3(PayScene::onProductCallback,
                                                   this));

void PayScene::onProductCallback(
    int code, std::string message,
    std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    if (GHOME::ERROR_CODE_SUCCESS == code && !params->empty()) {
        auto data = params->find("data");
        if (data != params->end()) {
            auto payData = data->second;
            CCLOG("payData: %s", payData.c_str());
        }
    } else {
        Toast::ShowToast("Failed to retrieve item list, please try again later.");
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

# Client Interface for Retrieving One-Time Token

  • Interface: static void GetOneTimeToken(const GHomeCallback &callback);
  • Parameter Description

No additional parameters required.

GHOME::GHomeBridge::GetOneTimeToken([=](int code, std::string message,
                                        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
    if (code == GHOME::ERROR_CODE_SUCCESS && !params->empty()) {
        auto token = params->find("token");
        if (token != params->end()) {
            CCLOG("One-time token: %s", token->second.c_str());
        }
    } else {
        Toast::ShowToast("Failed to retrieve one-time token, please try again later.");
    }
});
1
2
3
4
5
6
7
8
9
10
11

# Scan QR Code Interface

  • Interface: static void ScanQRCode(std::string extend, const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
extend Extension field that will be returned as-is after scanning the PC side QR code.
callback Callback object to return the execution result, see code examples for more details.

Note: This interface can only be used after successful login.

GHOME::GHomeBridge::ScanQRCode(
    "",
    [=](int code, std::string message,
        std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        std::shared_ptr<std::unordered_map<std::string, std::string>> data =
            std::move(params);
        // Delay execution to avoid interface disorder when returning from Android
        scheduleOnce([=](float time) { onScanCallback(code, message, data); },
                     0.1, "scan");
    });

void GameScene::onScanCallback(
    int code, std::string message,
    std::shared_ptr<std::unordered_map<std::string, std::string>> params) {
    CCLOG("Scan callback, code: %d, message: %s", code, message.c_str());
    switch (code) {
    case GHOME::ERROR_CODE_QR_LOGIN_SUCCESS:
        Toast::ShowToast("Authorization completed for test account 001 on the desktop version.");
        break;
    case GHOME::ERROR_CODE_QR_PAY_SUCCESS:
        Toast::ShowToast("Scan payment successful.");
        break;
    case GHOME::ERROR_PAY_FAILED:
        Toast::ShowToast("Payment failed, please try again later.");
        break;
    case GHOME::ERROR_CODE_QR_RESULT: {
        std::string toast = std::move(message);
        if (!params->empty()) {
            auto iter = params->find("qrdata");
            if (iter != params->end()) {
                toast = iter->second;
            }
        }
        Toast::ShowToast(toast);
    } break;
    case GHOME::ERROR_CODE_QR_CANCELED:
        Toast::ShowToast("Scan canceled.");
        break;
    case GHOME::ERROR_USER_NOT_LOGIN:
        Toast::ShowToast("Please log in first!");
        break;
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

# Client Report Game Area Interface

  • Interface: static void LoginArea(std::string areaId, std::string groupId);
  • Parameter Description
Parameter Name Description
areaId ID of the game region selected by the user.
groupId Group ID; pass an empty string (“”) if there is no actual data.
GHOME::GHomeBridge::LoginArea(area.areaCode, area.groupId);
1

# Client Display/Hide Floating Window Interface

  • Interface: static void ShowFloatIcon(bool show, int position);
  • Parameter Description
Parameter Name Description
show true to display the floating window, false to hide it.
position Position of the floating window (some channels may not support setting the position, so specifying this parameter might have no effect).
GHOME::GHomeBridge::ShowFloatIcon(false, GHOME::FloatPosition::LeftTop);
1

# Third-Party Channel SDK Extension Interface

  • Interface: static void DoExtend(int command, std::unique_ptr<std::unordered_map<std::string, std::string>> params,const GHomeCallback &callback);
  • Parameter Description
Parameter Name Description
command Number of the extension interface (e.g., IGHomeApi.EXTEND_COMMAND_SUBMIT_EXTEND_DATA)
params Request parameters, type Map<String, String>
callback Callback object used to report execution results; see code example for details.
GHOME::GHomeBridge::DoExtend(
    GHOME::EXTEND_COMMAND_EXIT_PAGE, std::move(map),
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            Director::getInstance()->end();
        } else {
            Toast::ShowToast(
                "(demo toast) SDK does not support exit page; please display the exit dialog yourself.");
        }
    });
1
2
3
4
5
6
7
8
9
10
11

# Obtain Primary Channel Number

  • Interface: static std::string GetApplicationSuperChannel();
  • Notes: This can be called before or after initialization.
std::string superChannelCode = GHOME::GHomeBridge::GetApplicationSuperChannel();
1

# Retrieve Secondary Channel Number

  • Interface: static std::string GetCPSChannelCode();
std::string channelCode = GHOME::GHomeBridge::GetCPSChannelCode();
Toast::ShowToast(channelCode);
1
2

# Acquire G Home Device ID

  • Interface: static std::string GetGHomeDeviceId();
std::string gDeviceId = GHOME::GHomeBridge::GetGHomeDeviceId();
Toast::ShowToast("G Home Device ID: " + gDeviceId);
1
2

# Retrieve User Agreement and Privacy Policy (Optional)

  • Interface: static void GetAgreement(std::string appId, const GHomeCallback &callback);
  • Parameter Explanation
Parameter Description
appId Game ID obtained from GPOP application.
callback Callback object to return the execution result
GHOME::GHomeBridge::GetAgreement(
    "791000008",
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            auto iter = params->find("data");
            if (iter != params->end()) {
                auto &content = iter->second;
            }
        }
    });

GHOME::GHomeBridge::GetAgreementContent(
    "791000008",
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            auto iter = params->find("data");
            if (iter != params->end()) {
                auto &content = iter->second;
            }
        }
    });
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# Account Login and Change Bound Phone Number (Optional)

  • Interface: static void ChangeThirdBindPhone(std::string appId, const GHomeCallback &callback);
  • Parameter Explanation
Parameter Description
appId The ID obtained by applying for the game on GPOP.
callback Callback object used to receive execution results, see code examples for details.
GHOME::GHomeBridge::ChangeThirdBindPhone(
    appId,
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            Toast::ShowToast("Association successful");
        } else {
            Toast::ShowToast("Association failed");
        }
    });
1
2
3
4
5
6
7
8
9
10

# Sensitive Word Filtering Interface (Optional, See Notes)

  • Interface: static void FilterSensitiveWord(std::string inputWord, const GHomeCallback &callback);
  • Parameter Explanation
Parameter Description
inputWord User-entered text information.
callback Callback object used to receive execution results, see code examples for details.

# Notes

  1. This interface is merely a placeholder interface; if the game needs to use channel-specific sensitive word interfaces (such as those provided by WeGame), this interface should be called.
  2. The ghome SDK and other channels have no effect (“pass-through”), meaning the original text will be returned without any modifications or filtering.
  3. Games using this interface are generally advised to implement a standalone base package separate from official login or other channel packages, in order to filter out sensitive words where users can enter information (e.g., chat messages and nickname settings) using channel-specific rules (currently only WeGame is supported).
  4. This recommendation represents just one possible implementation strategy; if games have alternative approaches that are more practical, they may opt for those as well. However, in principle, it’s essential to implement sensitive word filtering while recognizing the ghome SDK acts merely as a proxy.
  5. If a game implements its own sensitive word filtering within a WeGame base package, user input will be filtered by the game’s own rules, then passed through the ghome SDK interface proxy before reaching the channel-specific filter.
  6. No usage data is recorded or logged for this interface since it pertains to private and sensitive information. Prior to going live, games utilizing this feature should thoroughly test all scenarios (e.g., chat messages and nickname settings) to ensure proper functionality.
GHOME::GHomeBridge::FilterSensitiveWord(
    word,
    [](int code, std::string message,
       std::unique_ptr<std::unordered_map<std::string, std::string>> params) {
        if (GHOME::ERROR_CODE_SUCCESS == code) {
            auto iter = params->find("resultWord");
            if (iter != params->end()) {
                Toast::ShowToast(iter->second);
            }
        }
    });
1
2
3
4
5
6
7
8
9
10
11

# GShare (Sharing Functionality, Optional)

  • Interface: static void share(int type, int sharePlatform, std::string text, std::string desc,std::unique_ptr<std::vector<std::string>> mediaPaths, const GHomeShareCallback& callback);
  • Parameter Explanation
Parameter Description
type Share type
text Share text
desc Share description
mediaPaths Paths of shared files
callback Share callback
GHOME::GHomeBridge::share(GHOME::TYPE_TEXT, sharePlatform, "Test sharing text", "",
                          nullptr,
                          CC_CALLBACK_3(ShareScene::onShareCallback, this));

void ShareScene::onShareCallback(int result, int platform,
                                 std::string message) {
    log("share callback: result: %d, platform: %d, %s", result, platform,
        message.c_str());
    scheduleOnce([=](float time) { Toast::ShowToast(message); }, 0.1, "share");
}
1
2
3
4
5
6
7
8
9
10
Last Updated: 11/14/2024, 2:31:00 AM

← Unity (PC) →