คู่มือการเชื่อมต่อ DMM GAMES¶

หากต้องการเชื่อมต่อ DMM GAMES กับแอป ต้องทำสัญญาล่วงหน้าก่อน หลังจากทำสัญญาแล้ว โปรดอ้างอิงคู่มือนี้เพื่อดำเนินการติดตั้งใช้งาน

ขอบเขตการรองรับการเชื่อมต่อ DMM GAMES ตามสภาพแวดล้อมการเรียกใช้แอปมีดังนี้

PC: รองรับทั้งการยืนยันตัวตนและการชำระเงินสำหรับการเปิดให้บริการบนสโตร์
มือถือ: รองรับเฉพาะการเชื่อมต่อวิธีการยืนยันตัวตนสำหรับเข้าสู่ระบบด้วย IdP

การเตรียมความพร้อม¶

1. ออกข้อมูลรับรองและตรวจสอบค่าคีย์ใน DMM Developer Site¶

PC: ตรวจสอบค่าคีย์ 3 รายการที่ออกให้จาก DMM ClientGame Developer Site
- App ID(アプリID), Consumer Key(コンシューマーキー), Consumer Secret(コンシューマーシークレット) - ตรวจสอบที่ ゲーム管理 > ゲーム情報 > 基本情報
- เมื่อลงทะเบียนแอปใน DMM Console ให้เลือกวิธีชำระเงินแบบ API

มือถือ: ออกข้อมูลรับรอง DMM

ลงทะเบียนข้อมูลแอปมือถือ เช่น ชื่อแพ็กเกจและข้อมูลแอป ใน DMM GAMES Developer Console ก่อน จากนั้นจึงออกข้อมูลรับรองด้านล่าง การยืนยันตัวตน DMM ใช้ข้อมูลรับรอง 2 ประเภท ได้แก่ OpenSocial และ AuthSDK

ประเภท	คีย์	คำอธิบาย
OpenSocial	`appId`	OpenSocial App ID เป็นค่า `opensocial_app_id` ของ makeRequest และใช้ในการตรวจสอบลายเซ็น
OpenSocial	`consumerKey`, `consumerSecret`	ข้อมูลรับรอง consumer สำหรับการลงลายเซ็น ตรวจสอบได้ใน DMM Console หลังจากลงทะเบียนแอป
AuthSDK	`clientId`, `clientSecret`, `secretKey`	ข้อมูลรับรองการเข้าสู่ระบบ OAuth2 ใช้งานโดย DMM AuthSDK ฝั่งอุปกรณ์ และไม่ถูกส่งไปยัง Hive Server ต้องยื่นคำขอแยกกับ DMM เพื่อออกข้อมูล
AuthSDK	`redirectUri`	Scheme สำหรับ callback ของ OAuth2 DMM จะผูกค่านี้กับ `clientId` และมอบให้พร้อมกันเมื่อยื่นคำขอ

2. เตรียม App ID¶

ใน App Center > App ID Management > New App ID ให้สร้าง App ID ให้ตรงกับ OS และสโตร์ สำหรับสภาพแวดล้อม PC ให้เลือก OS เป็น Windows และเลือกสโตร์เป็น DMM GAMES
ตัวอย่าง App ID: com.[ชื่อบริษัท].[ชื่อโปรเจกต์].windows.dmm

3. ตั้งค่าการยืนยันตัวตน¶

เพื่อเสริมความปลอดภัยของการยืนยันตัวตนระหว่างบริการ ต้องออก Security Key ใน Hive Console > App Center > Security Key Settings
สำหรับการตั้งค่าการยืนยันตัวตน ให้ลงทะเบียน Store Key และตั้งค่าการแสดง IdP ใน Authentication > Login Settings

4. ตั้งค่าการชำระเงิน¶

สำหรับการตั้งค่าการชำระเงิน ให้ลงทะเบียน Store Key ใน Billing > Payment Settings > Store Settings

การเชื่อมต่อสภาพแวดล้อม PC (สภาพแวดล้อม DMM GAME PLAYER)¶

ติดตั้งใช้งานโดยอ้างอิง เข้าสู่ระบบ/ออกจากระบบ

Warning

อย่าเรียกใช้แอปหากไม่มีพารามิเตอร์การเรียกใช้

หากไม่ได้เรียกใช้ผ่าน DMM GAME PLAYER และไม่ได้รับพารามิเตอร์การเรียกใช้ viewer_id, onetime_token อย่าเรียกใช้แอปและให้จัดการโดยการปิดแอป เป็นต้น สำหรับรายละเอียดเกี่ยวกับวิธีส่งพารามิเตอร์ โปรดดูนโยบายบริการ DMM GAMES PLAYER ใน DMM GAMES Developer Support

เมื่อสภาพแวดล้อมการเรียกใช้แอปเป็น PC (DMM GAME PLAYER) ให้พิจารณารายการต่อไปนี้สำหรับการเชื่อมต่อการเข้าสู่ระบบ DMM

Hive SDK รับพารามิเตอร์การเรียกใช้ viewer_id, onetime_token ที่ DMM GAME PLAYER Launcher ส่งมา และดำเนินการเข้าสู่ระบบบัญชี DMM โดยไม่มี UI เข้าสู่ระบบแยกต่างหาก ดังนั้นแอปไม่จำเป็นต้องติดตั้งใช้งาน flow เข้าสู่ระบบเฉพาะสำหรับสภาพแวดล้อม DMM แต่ให้เชื่อมต่อกระบวนการเข้าสู่ระบบบัญชี DMM
การเข้าสู่ระบบ DMM ดำเนินการด้วยเมธอดเข้าสู่ระบบแบบ implicit AuthV4.Helper.signIn หรือ AuthV4.signIn(ProviderType.DMM) เมื่อเข้าสู่ระบบสำเร็จ เซสชันเข้าสู่ระบบอัตโนมัติจะถูกบันทึก และสามารถเข้าสู่ระบบภายหลังด้วย AuthV4.signIn(ProviderType.Auto) ได้เช่นกัน ตรวจสอบ providerUserId ตามตัวระบุผู้ใช้ viewer_id ในข้อมูล DMM provider ของผลลัพธ์การเข้าสู่ระบบ PlayerInfo
หากเรียกใช้ผ่าน DMM GAME PLAYER และได้รับพารามิเตอร์จาก Launcher การเข้าสู่ระบบแบบ implicit จะทำงานด้วยบัญชี DMM เสมอโดยไม่มีข้อจำกัดเฉพาะครั้งแรก และไม่ใช้ showSignIn ซึ่งเป็น UI เข้าสู่ระบบแบบ explicit สำหรับพฤติกรรมการเข้าสู่ระบบแบบ implicit ทั่วไปบน Windows โปรดดูพฤติกรรมการเข้าสู่ระบบแบบ implicit: PC
โทเคนจัดการ onetime_token มีอายุ 90 นาทีตามนโยบาย DMM Hive SDK จะต่ออายุโดยอัตโนมัติภายใน จึงไม่จำเป็นต้องติดตั้งใช้งานแยกต่างหาก อย่างไรก็ตาม หากการต่ออายุล้มเหลว เช่น เครือข่ายขาดการเชื่อมต่อเป็นเวลานานจนโทเคนหมดอายุโดยสมบูรณ์ SDK จะไม่สามารถกู้คืนได้ด้วยตนเอง ให้เริ่มแอปใหม่เพื่อรับโทเคนใหม่ การเรียก DMM API เช่น การชำระเงิน จำเป็นต้องมีโทเคนจัดการที่ยังใช้งานได้
เมื่อเรียกใช้ผ่าน DMM GAME PLAYER อย่าใช้เมธอดออกจากระบบ signOut เนื่องจาก DMM ทำงานด้วยการเข้าสู่ระบบอัตโนมัติผ่าน Launcher จึงไม่ใช้ showSignIn ซึ่งเป็น UI เลือก IdP เช่นกัน

การยืนยันตัวตน DMM เป็นวิธีการยืนยันตัวตนที่ใช้เมื่อผู้ใช้เรียกใช้แอปผ่าน DMM GAME PLAYER บน Windows โดยทำงานเป็นการเข้าสู่ระบบอัตโนมัติผ่าน Launcher และไม่แสดงในรายการเลือก IdP ของ UI เข้าสู่ระบบแบบ explicit

การเชื่อมต่อสภาพแวดล้อมมือถือ¶

การเข้าสู่ระบบ DMM บนมือถือใช้งานด้วยการเรียก AuthV4.signIn(ProviderType.DMM) เช่นเดียวกับ IdP อื่น ๆ เช่น Google, Apple โดย provider จะจัดการการเริ่มต้น DMM SDK การเข้าสู่ระบบ และการตรวจสอบลายเซ็นภายใน

ตั้งค่าคีย์ใน hive_config.xml¶

อ้างอิงโค้ดตัวอย่างด้านล่างและกรอกค่าในแท็ก providers ของไฟล์ hive_config.xml จากตัวอย่าง 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 มีดังนี้

ให้ตั้งค่า secretKey, clientId, clientSecret ทั้งสามค่าผ่าน API setConfigurations()
ข้อมูลที่ตั้งค่าด้วย API setConfigurations() จะคงอยู่เฉพาะในหน่วยความจำ runtime จึงต้องเรียกใช้ทุกครั้งที่เปิดแอป
แม้จะมีค่าที่ตั้งไว้ในไฟล์ hive_config.xml ค่าที่ตั้งผ่าน API setConfigurations() ขณะ runtime จะมีลำดับความสำคัญสูงกว่าและเขียนทับค่าเดิม

สำหรับการตั้งค่าคีย์ลับผ่าน API setConfigurations() โปรดดูโค้ดตัวอย่างด้านล่าง

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¶

เพิ่มไลบรารีเข้าสู่ระบบ DMM โดยอ้างอิง เพิ่ม Android IdP จากนั้นตั้งค่า Android DMM IdP ตามลำดับด้านล่าง

ตั้งค่า redirectUri(scheme)

redirect_uri เป็น custom scheme เช่น comXXX://auth และต้องส่งพร้อมกับการสมัคร clientId เพื่อรับการรับรองจาก DMM ก่อนใช้งาน เนื่องจากค่านี้ผูกกับ clientId หากใช้ค่าที่ไม่ได้รับการรับรอง จะเกิดข้อผิดพลาด DMM E210019 (error_redirect_uri_unavailable) ขณะเข้าสู่ระบบ

ใส่ redirect scheme ใน build.gradle
```
manifestPlaceholders += [hiveDmmRedirectScheme: "comXXX"]
```
ตั้งค่า Gradle dependencies และ repository

เพิ่ม DMM Maven repository ใน dependencyResolutionManagement { repositories } ของ settings.gradle ที่ root เนื่องจากการประกาศ Gradle repository ไม่ส่งต่อกัน หากไม่ได้ประกาศในการ build ของแอป การ resolve DMM SDK (link-id-sdk, AuthSDK) จะล้มเหลว
```
maven { url 'https://repos-app.games.dmm.com/' }
```
3. ติดตั้งใช้งานโดยอ้างอิง เข้าสู่ระบบ/ออกจากระบบ

การตั้งค่า iOS DMM IdP¶

เพิ่มไลบรารีเข้าสู่ระบบ DMM โดยอ้างอิง เพิ่ม iOS IdP จากนั้นติดตั้งใช้งานโดยอ้างอิง เข้าสู่ระบบ/ออกจากระบบ

การติดตั้งใช้งานการชำระเงิน DMM¶

DMM เป็นวิธีชำระเงินที่ผู้ใช้ซื้อสินค้าด้วย DMM Point ที่เติมไว้ การขอชำระเงินและ flow การกู้คืนจะเป็นไปตาม flow การซื้อทั่วไปของ IAP v4 แต่มีเงื่อนไขเฉพาะของ DMM เช่น การตรวจสอบยอด DMM Point และการแนะนำให้เติม Point ทำงานร่วมด้วย ดังนั้นในสภาพแวดล้อม Windows DMM ต้องคง flow IAP v4 เดิมไว้พร้อมจัดการเงื่อนไขการชำระเงินแบบ DMM Point

ขั้นตอนการติดตั้งใช้งาน¶

ติดตั้งใช้งานโดยอ้างอิง Billing > การเริ่มต้น IAP v4
ติดตั้งใช้งานโดยอ้างอิง Billing > การสอบถามรายการสินค้าและการซื้อ
ติดตั้งใช้งานโดยอ้างอิง การตรวจสอบใบเสร็จ
ข้อควรพิจารณาเมื่อพัฒนาการเข้าสู่ระบบ DMM
1. การชำระเงิน DMM จะยืนยันทันทีโดยไม่มี UI หน้าต่างชำระเงินแยกต่างหาก หากหลังซื้อแล้วอยู่ในสถานะ Pending โดยไม่ได้รับใบเสร็จ ให้เรียก IAPV4.restore เพื่อรับใบเสร็จอีกครั้ง แล้วดำเนินการตรวจสอบและมอบสินค้า flow โดยรวมของการตรวจสอบใบเสร็จและมอบสินค้าหลังซื้อเหมือนกับสโตร์อื่น ๆ รายละเอียดโปรดดู การตรวจสอบใบเสร็จ
2. การเรียก DMM billing API ต้องใช้โทเคนจัดการ onetime_token ที่ยังใช้งานได้ สำหรับอายุโทเคน การต่ออายุอัตโนมัติ และการจัดการเมื่อหมดอายุ โปรดดู การเข้าสู่ระบบ DMM
3. การชำระเงิน DMM รองรับการซื้อหลายจำนวนเช่นกัน ให้เรียก IAPV4.purchase(marketPid, iapPayload, quantity, onIAPV4PurchaseCB) พร้อมพารามิเตอร์ quantity เพื่อซื้อสินค้ารายการเดียวกันหลายชิ้นพร้อมกัน

DMM Point¶

สอบถามยอด DMM Point¶

เรียก IAPV4.getBalanceInfo เพื่อสอบถามยอด DMM Point ที่ผู้ใช้สามารถใช้ได้ ใช้เมื่อต้องการตรวจสอบยอดล่วงหน้าก่อนซื้อหรือแสดงยอดในหน้าร้านค้า callback จะส่ง ResultAPI และยอดคงเหลือชนิดจำนวนเต็ม balance กลับมา getBalanceInfo ใช้ได้เฉพาะกับการชำระเงิน DMM ในสภาพแวดล้อม PC Windows หากเรียกใน Market อื่น จะส่งคืนผลลัพธ์ไม่รองรับ NOT_SUPPORTED

เมื่อเรียกสำเร็จ balance จะมีจำนวน DMM Point ที่ใช้งานได้ในปัจจุบัน หากเรียกล้มเหลว ให้ตรวจสอบสาเหตุด้วย ResultAPI

UnityUnreal EngineC++

using hive;

IAPV4.getBalanceInfo((ResultAPI result, int balance) => {
    if (result.isSuccess()) {
        // balance: ยอด DMM Point ที่ใช้ได้
    }
});

#include "HiveIAPV4.h"

FHiveIAPV4::GetBalanceInfo(FHiveIAPV4OnBalanceDelegate::CreateLambda([this](const FHiveResultAPI& Result, int32 Balance) {
    if (Result.IsSuccess()) {
        // Balance: ยอด DMM Point ที่ใช้ได้
    }
}));

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

IAPV4::getBalanceInfo([=](ResultAPI const & result, int balance) {
    if (result.isSuccess()) {
        // balance: ยอด DMM Point ที่ใช้ได้
    }
});

แนะนำให้เติมเงินเมื่อ DMM Point ไม่เพียงพอ¶

หากยอด Point ไม่เพียงพอขณะซื้อ callback ของ purchase จะส่งคืน result code IAPV4DmmInsufficientPointBalance ในกรณีนี้ ให้แสดงหน้าเติม DMM Point ผ่านเบราว์เซอร์จากแอปและแนะนำให้ผู้ใช้เติม Point

URL หน้าเติม DMM Point คือ https://point.dmm.com/choice/pay?basket_service_type=freegame

Caution

URL หน้าเติมเงินด้านบนเป็นค่าที่ DMM ให้มา และอาจเปลี่ยนแปลงได้ตามนโยบาย DMM โปรดตรวจสอบ URL ล่าสุดและค่าพารามิเตอร์ เช่น basket_service_type จาก DMM