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 等参数值。