IAP v4 初始化

如要使用 IAP v4，必須在購買前請求一次 IAP 初始化。請求 IAP 初始化後，應用程式用戶端會將可用的商店資訊作為結果值回傳。

商店資訊¶

商店資訊定義為 IAPV4Type 列舉，欄位說明如下。

字段名稱	描述
APPLE_APPSTORE	蘋果應用商店
GOOGLE_PLAYSTORE	谷歌Play商店
HIVE_LEBI	Lebi商店
ONESTORE	ONE商店
AMAZON_APPSTORE	亞馬遜應用商店（僅在SDK v4中可用）
SAMSUNG_GALAXYSTORE	三星Galaxy商店
HUAWEI_APPGALLERY	華為應用市場
HIVESTORE	PG（支援 Windows 用 Unity、iOS、Android）
ANIMATE_GO	animate Games Online（僅限 Android）
DMM	DMM 點數商店。在 Windows 上透過 DMM GAME PLAYER 執行時使用。

HIVESTORE PG僅支持產品搜索和購買，並且不支持基於客戶端的收據驗證。
DMM 結帳僅在 Windows 上透過 DMM GAME PLAYER 執行時使用，並以 DMM 點數為基礎運作。

即使商店中的應用程式服務終止，現有使用者仍需能夠存取遊戲內貨幣商店以繼續遊玩。因此，應用程式必須將現金結帳商店與遊戲內貨幣商店分開設計。IAP v4 初始化回傳的結果值並非用於存取遊戲內商店，請勿用於其他目的。

DMM 結帳使用前注意事項¶

DMM 結帳僅在 Windows 上透過 DMM GAME PLAYER 執行時使用。本文件中的 DMM 相關內容皆以 Windows 環境為準。請先參閱 DMM 登入以瞭解 DMM 登入與管理權杖的限制。

DMM 結帳是使用者以已儲值的 DMM 點數購買商品的結帳方式。結帳請求與復原流程遵循 IAP v4 的一般購買流程，但同時會運作 DMM 專用的分支，例如確認 DMM 點數餘額、引導儲值點數等。因此在 Windows DMM 環境下，仍會維持既有的 IAP v4 流程，同時一併處理以 DMM 點數為基礎的結帳條件。

事前準備：控制台註冊¶

若要使用 DMM 驗證，請先參閱使用 DMM 登入。

DMM 結帳特色¶

結帳不需要另外的結帳視窗 UI，呼叫 purchase() 後即可立即確定。但依伺服器處理狀況，購買後可能不會立即回傳收據，此時請使用 restore() 重新取得收據。

呼叫 DMM 結帳 API 時，需要有效的管理權杖 onetime_token。有關權杖有效期限、自動更新、過期時的處理方式，請參閱 DMM 登入。

DMM 結帳使用前注意事項¶

DMM 結帳僅在 Windows 上透過 DMM GAME PLAYER 執行時使用。本文件中的 DMM 相關內容皆以 Windows 環境為準。請先參閱 DMM 登入以瞭解 DMM 登入與管理權杖的限制。

DMM 結帳是使用者以已儲值的 DMM 點數購買商品的結帳方式。結帳請求與復原流程遵循 IAP v4 的一般購買流程，但同時會運作 DMM 專用的分支，例如確認 DMM 點數餘額、引導儲值點數等。因此在 Windows DMM 環境下，仍會維持既有的 IAP v4 流程，同時一併處理以 DMM 點數為基礎的結帳條件。

事前準備：控制台註冊¶

若要使用 DMM 驗證，請先參閱使用 DMM 登入。

DMM 結帳特色¶

結帳不需要另外的結帳視窗 UI，呼叫 purchase() 後即可立即確定。但依伺服器處理狀況，購買後可能不會立即回傳收據，此時請使用 restore() 重新取得收據。

呼叫 DMM 結帳 API 時，需要有效的管理權杖 onetime_token。有關權杖有效期限、自動更新、過期時的處理方式，請參閱 DMM 登入。

初始化 IAPv4¶

如要初始化 IAP v4，必須呼叫 IAPV4 類別的 marketConnect() 方法。

以下是初始化 IAP v4 的示例代码。

Unity虛幻引擎C++KotlinJavaSwiftObjective-C

API 参考: hive.IAPV4.marketConnect

using hive;    
    IAPV4.marketConnect((ResultAPI result, List marketIdList) => {    
         if (result.isSuccess()) {    
            // call successful    
        }    
});

#include "HiveIAPV4.h"

FHiveIAPV4::MarketConnect(FHiveIAPV4OnMarketConnectDelegate::CreateLambda([this](const FHiveResultAPI& Result, const TArray<EHiveIAPV4Type>& MarketIds) {
        if (Result.IsSuccess()) {
                // call successful 
        }
}));

API 參考: IAPV4::marketConnect

#include <HIVE_SDK_Plugin/HIVE_CPP.h>    
    using namespace std;    
    using namespace hive;    
    IAPV4::marketConnect([=](ResultAPI const & result, vector const & marketIdList) {    
         if (result.isSuccess()) {    
            // call successful    
         }    
});

API 參考: IAPV4.marketConnect

import com.hive.IAPV4    
    import com.hive.ResultAPI    
    IAPV4.marketConnect(object : IAPV4.IAPV4MarketInfoListener {    
         override fun onIAPV4MarketInfo(result: ResultAPI, iapV4TypeList: ArrayList<IAPV4.IAPV4Type>?) {    
             if (result.isSuccess) {    
                 // call successful    
             }    
         }    
})

API 參考: com.hive.IAPV4.marketConnect

import com.hive.IAPV4;    
    import com.hive.ResultAPI;    
    IAPV4.INSTANCE.marketConnect((result, iapV4TypeList) -> {    
         if (result.isSuccess()) {    
             // call successful    
         }    
});

API 參考: IAPV4Interface .marketConnect

import HIVEService    
    IAPV4Interface.marketConnect() { result, marketIdList in    
        if result.isSuccess() {    
        // call successful    
        }    
}

API 參考: HIVEIAPV4::marketConnect

#import <HIVEService/HIVEService-Swift.h>    
    [HIVEIAPV4 marketConnect: ^(HIVEResultAPI *result, NSArray<NSNumber *> *marketIdList) {    
         if ([result isSuccess]) {    
            // call successful    
         }    
}];

檢查初始化結果¶

使用多個商店時，回呼傳遞的 marketList 中包含 Hive 控制台中設定的商店，並會根據商店初始化是否成功按如下方式區分回呼。

所有商店或僅部分商店連線成功時：ResultAPI 回傳成功，marketList 中僅傳遞連線成功的商店。
所有商店連線失敗時：ResultAPI 回傳錯誤代碼，marketList 回傳無值（null）。

例如，在 Hive 控制台中同時設定了 App Store 和 PG（Hive Store）的應用程式中，如果只有 PG（Hive Store）連線失敗：

ResultAPI：回傳成功
marketList：[APPLE_APPSTORE]（僅傳遞成功的商店）

Warning

若 marketConnect() 方法呼叫失敗，將無法正常進行商品清單查詢與購買。失敗原因如下：

裝置帳號登入異常
Google Play Store、Apple App Store 等商店平台應用程式登入異常
Hive 控制台中 App ID 對應的商店設定異常

即使 ResultAPI 回傳成功，也不代表控制台中設定的所有商店皆已連線。如果控制台中設定的商店數量與 marketList 中的商店數量不同，表示部分商店連線失敗，因此請僅使用回傳的 marketList 中的商店繼續後續結帳流程。

如果 ResultAPI 回傳失敗（全部失敗），應用程式用戶端應自行實作處理邏輯，例如重試直到收到成功回呼，或透過彈窗向使用者提示錯誤狀況（商店不可用）。

相關代碼請參閱 IAP v4 Result API Guide。

初始化注意事項¶

從 Hive SDK v4 Unity Windows 25.8.0 開始，支援 Google Play 的 Windows 應用程式，並且可以使用 GOOGLE_PLAYSTORE 商店。在這種情況下，請在開發過程中注意以下事項：

呼叫 IAPV4.marketConnect 之前，使用者必須先在 PC Google Play Games 應用程式中完成 Google 帳戶登入。
必須準備好 manifest.xml 檔案。

自 Hive SDK v4 iOS 26.3.2 起可使用 PG（HIVESTORE）。

Google Play for native PC 初始化失敗因應（Hive SDK v4 Unity Windows 26.4.2 以上）¶

當 Google Play Games PC SDK 因初始化失敗而需要終止時，系統不會強制終止，而是透過 IAPV4.marketConnect 回呼傳遞結果。這是為了讓應用程式能夠自行控制終止的時機與方式。

當 Google Play Games PC SDK 初始化失敗（kActionRequiredShutdownClientProcess）時，IAPV4.marketConnect 回呼會傳遞 IAPV4PlayStoreActionRequiredShutdown(-6100706) 結果代碼。

收到此結果代碼時，建議盡快終止應用程式處理程序。由於 ResultAPI.needExit() 會傳回 true，因此可透過 needExit() 判斷是否需要終止。終止處理程序後，Google Play Games PC SDK 端會嘗試進行後續動作以協助使用者。