DMM GAMES 整合指南¶

若要在應用程式中整合 DMM GAMES，必須先簽訂合約。簽約後，請參考以下指南進行實作。

依應用程式執行環境而定，DMM GAMES 整合支援範圍如下。

PC：支援商店發布所需的認證與支付功能。
行動裝置：僅支援 IdP 登入認證方式整合。

事前準備¶

1. 在 DMM Developer Site 核發憑證並確認金鑰值¶

PC：確認從 DMM ClientGame Developer Site 核發的三個金鑰值。
- App ID(アプリID)、Consumer Key(コンシューマーキー)、Consumer Secret(コンシューマーシークレット) - 於 ゲーム管理 > ゲーム情報 > 基本情報 確認
- 在 DMM 控制台註冊應用程式時，支付方式請選擇 API 方式。

行動裝置：核發 DMM 憑證。

請先在 DMM GAMES 開發者控制台登錄套件名稱、應用程式資訊等行動應用程式資訊，然後核發下列憑證。DMM 認證使用 OpenSocial 系列與 AuthSDK 系列兩種憑證。

分類	金鑰	說明
OpenSocial	`appId`	OpenSocial 應用程式 ID。這是 makeRequest 的 `opensocial_app_id` 值，也用於簽章驗證。
OpenSocial	`consumerKey`、`consumerSecret`	用於簽章的 consumer 憑證。註冊應用程式後可在 DMM 控制台確認。
AuthSDK	`clientId`、`clientSecret`、`secretKey`	OAuth2 登入憑證。由裝置端 DMM AuthSDK 使用，不會傳送至 Hive 伺服器。須另行向 DMM 申請後核發。
AuthSDK	`redirectUri`	OAuth2 回呼 scheme。DMM 會將其綁定至 `clientId`，並於申請時一併提供。

2. 準備 App ID¶

在 App Center > App ID Management > New App ID 中，依 OS 與商店建立 App ID。PC 環境下，OS 選擇 Windows，商店選擇 DMM GAMES。
App ID 範例：com.[公司名稱].[專案名稱].windows.dmm

3. 認證設定¶

為強化服務間認證安全性，務必在 Hive Console > App Center > Security Key Settings 中核發安全金鑰。
認證設定所需的商店金鑰註冊與 IdP 顯示設定，請在認證 > 登入設定中進行。

4. 支付設定¶

支付設定所需的商店金鑰註冊，請在 Billing > Payment Settings > Store Settings 中進行。

PC 執行環境整合（DMM GAME PLAYER 執行環境）¶

請參考登入/登出進行實作。

Warning

若不存在執行參數，請勿執行應用程式。

若應用程式並非透過 DMM GAME PLAYER 啟動，且未傳遞執行參數 viewer_id、onetime_token，請不要執行應用程式，並以結束等方式處理。關於參數傳遞方式的詳細內容，請參閱 DMM GAMES Developer Support 中的 DMM GAMES PLAYER 服務政策。

當應用程式執行環境為 PC（DMM GAME PLAYER）時，DMM 登入整合需考量下列事項。

Hive SDK 會接收 DMM GAME PLAYER 啟動器傳遞的執行參數 viewer_id、onetime_token，並處理 DMM 帳號登入，不顯示額外登入 UI，而是隱式登入。因此，應用程式不需為 DMM 執行環境另外實作登入流程，只需連接 DMM 帳號登入流程。
DMM 登入透過隱式登入方法 AuthV4.Helper.signIn 或 AuthV4.signIn(ProviderType.DMM) 進行。登入成功後會儲存自動登入工作階段，之後也可透過 AuthV4.signIn(ProviderType.Auto) 登入。請在登入結果 PlayerInfo 的 DMM provider 資訊中確認基於使用者識別碼 viewer_id 的 providerUserId。
透過 DMM GAME PLAYER 啟動並傳遞啟動器參數時，隱式登入一律以 DMM 帳號運作，不受首次一次性限制，且不使用顯式登入 UI showSignIn。一般 Windows 隱式登入行為請參考隱式登入行為：PC。
管理權杖 onetime_token 依 DMM 政策有效期為 90 分鐘。Hive SDK 會在內部自動更新，因此不需另行實作。但若因網路長時間中斷等原因導致更新失敗，權杖完全過期後，SDK 無法自行恢復。請重新啟動應用程式以取得新權杖。支付等 DMM API 呼叫需要有效的管理權杖。
透過 DMM GAME PLAYER 執行時，請勿使用登出方法 signOut。DMM 以啟動器式自動登入運作，因此也不使用 IdP 選擇 UI showSignIn。

DMM 認證是使用者在 Windows 上透過 DMM GAME PLAYER 執行應用程式時使用的認證方式。它以啟動器式自動登入運作，不會顯示在顯式登入 UI 的 IdP 選擇清單中。

行動裝置執行環境整合¶

行動裝置 DMM 登入與 Google、Apple 等其他 IdP 相同，透過呼叫 AuthV4.signIn(ProviderType.DMM) 使用，DMM SDK 初始化、登入與簽章驗證整合由 provider 在內部處理。

在 hive_config.xml 中設定金鑰¶

請參考下列範例程式碼，在 hive_config.xml 檔案的 providers 標籤中輸入值。Sandbox 與正式(Service)範例中，請僅套用符合使用環境 developmentMode 的一個區塊。

<!-- Sandbox 設定 -->
    <properties>
    <!-- 省略 Hive SDK 共通設定 -->

    <!-- Hive SDK 認證設定: START -->
                <providers>
                        <!-- 使用 DMM 登入 (DMM) -->
                        <dmm appId="123456" developmentMode="sandbox" redirectUri="app-redirect-url" consumerKeySandbox="abcdefghijklmnop" consumerSecretSandbox="abcdefghijklmnopabcdefghijklmnop" />
                    </providers>
                    <!-- Hive SDK 認證設定: END -->
        </properties>

    <!-- 正式(Service)設定 -->
    <properties>
    <!-- 省略 Hive SDK 共通設定 -->

                    <!-- Hive SDK 認證設定: START -->
                <providers>
                                    <!-- 使用 DMM 登入 (DMM) -->
                                <dmm appId="123456" developmentMode="service" redirectUri="app-redirect-url" consumerKey="abcdefghijklmnop" consumerSecret="abcdefghijklmnopabcdefghijklmnop" />
                    </providers>
<!-- Hive SDK 認證設定: END -->
</properties>

hive_config.xml 金鑰清單（Android、iOS）如下。

金鑰	值	必要條件
appId	應用程式識別碼	一律
developmentMode	`sandbox` 或 `service`	一律
consumerKey	consumer key	為 `service` 時
consumerSecret	consumer secret	為 `service` 時
consumerKeySandbox	consumer key	為 `sandbox` 時
consumerSecretSandbox	consumer secret	為 `sandbox` 時
redirectUri	應用程式中設定的 redirect url	一律
adult	true 或 false	iOS 時

關於 secretKey、clientId、clientSecret 設定，需考量下列事項。

請透過 setConfigurations() API 設定 secretKey、clientId、clientSecret 三個設定值。
透過 setConfigurations() API 設定的資訊僅保留於執行階段記憶體中，因此每次啟動應用程式時都必須呼叫。
即使 hive_config.xml 檔案中存在設定值，執行階段透過 setConfigurations() API 設定的值也會優先套用（覆寫）。

setConfigurations() API 的機密金鑰值設定請參考下列範例程式碼。

UnityC++KotlinSwiftObjective-C

using hive;

// HiveConfigType.dmmSecretKey
// HiveConfigType.dmmClientId
// HiveConfigType.dmmClientSecret
Configuration.setConfigurations(HiveConfigType.dmmSecretKey, "***");

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace std;
using namespace hive;

// HiveConfigType::dmmSecretKey
// HiveConfigType::dmmClientId
// HiveConfigType::dmmClientSecret
Configuration::setConfigurations(HiveConfigType::dmmSecretKey, "***");

import com.hive.Configuration

// Configuration.HiveConfigType.dmmSecretKey
// Configuration.HiveConfigType.dmmClientId
// Configuration.HiveConfigType.dmmClientSecret
Configuration.setConfigurations(Configuration.HiveConfigType.dmmSecretKey, "***")

import HIVEService

// HiveConfigType.dmmSecretKey
// HiveConfigType.dmmClientId
// HiveConfigType.dmmClientSecret
ConfigurationInterface.setConfigurations(.dmmSecretKey, "***")

#import <HIVEService/HIVEService-Swift.h>

// HiveConfigTypeDmmSecretKey
// HiveConfigTypeDmmClientId
// HiveConfigTypeDmmClientSecret
[HIVEConfiguration setConfigurations: HiveConfigTypeDmmSecretKey value: @"***"];

Android DMM IdP 設定¶

請參考 Android IdP 新增新增 DMM 登入函式庫。之後依下列順序進行 Android DMM IdP 設定。

redirectUri(scheme) 設定

redirect_uri 是類似 comXXX://auth 的自訂 scheme，必須在申請 clientId 時一併提交並取得 DMM 認證後才能使用。由於此值會綁定至 clientId，若使用未經認證的值，登入時會發生 DMM 錯誤 E210019 (error_redirect_uri_unavailable)。

在 build.gradle 中注入 redirect scheme。
```
manifestPlaceholders += [hiveDmmRedirectScheme: "comXXX"]
```
Gradle 相依性與存放庫設定

在根 settings.gradle 的 dependencyResolutionManagement { repositories } 中新增 DMM Maven 存放庫。由於 Gradle 存放庫宣告不具傳遞性，若未在應用程式建置中宣告，DMM SDK（link-id-sdk、AuthSDK）解析將失敗。
```
maven { url 'https://repos-app.games.dmm.com/' }
```
3. 請參考登入/登出進行實作。

iOS DMM IdP 設定¶

請參考 iOS IdP 新增新增 DMM 登入函式庫。之後請參考登入/登出進行實作。

實作 DMM 支付¶

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

實作步驟¶

請參考 Billing > IAP v4 初始化進行實作。
請參考 Billing > 商品清單查詢與購買進行實作。
請參考收據驗證進行實作。
DMM 登入開發時的注意事項
1. DMM 支付無需額外支付視窗 UI，會立即確認。若購買後未立即回傳收據而處於 Pending 狀態，請呼叫 IAPV4.restore重新取得收據後，再進行驗證與發放處理。購買後收據驗證與商品發放處理的整體流程與其他商店相同。詳情請參考收據驗證。
2. DMM 支付 API 呼叫需要有效的管理權杖 onetime_token。關於權杖有效期、自動更新與過期時處理等，請參考 DMM 登入。
3. DMM 支付也支援多數量購買。請呼叫包含 quantity 參數的 IAPV4.purchase(marketPid, iapPayload, quantity, onIAPV4PurchaseCB)，一次購買多個相同商品。

DMM 點數¶

查詢 DMM 點數餘額¶

呼叫 IAPV4.getBalanceInfo 可查詢使用者可使用的 DMM 點數餘額。可用於購買前主動確認餘額，或在商店畫面顯示餘額。回呼會傳遞 ResultAPI 與整數型餘額 balance。getBalanceInfo 僅可在 PC Windows 環境的 DMM 支付中使用，於其他市場呼叫時會回傳不支援的 NOT_SUPPORTED 結果。

呼叫成功時，balance 中包含目前可使用的 DMM 點數餘額；呼叫失敗時，請透過 ResultAPI 確認失敗原因。

UnityUnreal EngineC++

using hive;

IAPV4.getBalanceInfo((ResultAPI result, int balance) => {
    if (result.isSuccess()) {
        // balance: 可使用的 DMM 點數餘額
    }
});

#include "HiveIAPV4.h"

FHiveIAPV4::GetBalanceInfo(FHiveIAPV4OnBalanceDelegate::CreateLambda([this](const FHiveResultAPI& Result, int32 Balance) {
    if (Result.IsSuccess()) {
        // Balance: 可使用的 DMM 點數餘額
    }
}));

#include <HIVE_SDK_Plugin/HIVE_CPP.h>
using namespace hive;

IAPV4::getBalanceInfo([=](ResultAPI const & result, int balance) {
    if (result.isSuccess()) {
        // balance: 可使用的 DMM 點數餘額
    }
});

DMM 點數不足時引導儲值¶

購買時若點數餘額不足，purchase 回呼會回傳 IAPV4DmmInsufficientPointBalance 結果代碼。此時，請在應用程式中透過瀏覽器顯示 DMM 點數儲值頁面，引導使用者儲值。

DMM 點數儲值頁面 URL 為 https://point.dmm.com/choice/pay?basket_service_type=freegame。

Caution

上述儲值頁面 URL 由 DMM 提供，可能依 DMM 政策變更。請向 DMM 確認最新 URL 以及 basket_service_type 等參數值。