Mobage HTML5 Game Quick Guide

# 道具购买流程概要

本页就理解道具购买流程的整体概念所必要的事项进行说明。
请参看下述图示和图示下方的说明。

# 道具购买流程整体概念

Payment Overview

下述说明编号与图中各步骤的编号相对应。

# 发送订单数据

  1. Game Client 向开发者服务器发送要购买的对象道具ID^1、数量等订单数据。
  2. 开发者服务器通过POST调用 Mobage RESTFul API 的Bank Debit发送订单数据，创建 Mobage Platform 上的交易。
  3. 作为步骤 2 中请求的响应返回 Transaction ID ^2。
  4. 在开发者服务器发行 Order ID^3 ，将从3的响应中获取的 Transaction ID 与 Order ID关联保存。
  5. 开发者服务器向 Game Client 返回 Order ID 和 Transaction ID。

# 调用支付对话框

  1. 通过 JavaScript SDK 执行 mobage.ui.open()，调用支付对话框。
  2. 通过支付对话框读取Mobage Platform 上的 Widget ，显示确认画面。
  3. 待用户确认和支付完成后，便会向 JavaScript SDK 通知结果。
  4. 执行 mobage.ui.open()的回调函数，传递支付结果。

# 交付道具

  1. 将步骤 9 中的支付结果发送给开发者服务器。
  2. 在开发者服务器验证支付结果，并交付道具。
    如果未执行步骤 4 中的 Order ID 发行和 Transaction ID 的关联， 调用 Mobage RESTFul API ，并验证订单数据的一致性。
  3. 开发者服务器是否已正常处理支付的结果返回。
  4. 若已正常处理，调用mobage.bank.clearPaymentBacklog() ，删除客户端上的支付结果。

# 开发步骤

接下来是上述的道具购买流程装载步骤的相关说明。

# 选择道具数据的管理方法

Mobage 支持两种装载方式：事先注册道具数据，以及在开始支付时传递道具数据。

建议使用事先登记道具数据的方法。本页将按照建议的步骤进行说明。

如果要使用在开始支付时传递道具数据的方法，请见支付处理开始--道具未事先注册。

有关事先注册道具数据的方法，其开发步骤如下。

  1. 在Developer Site 上注册道具
  2. 发送订单数据
  3. 调用支付对话框
  4. 交付道具
  5. 道具购买失败时的处理

每个步骤的详细说明如下。

# 在Developer Site 上注册道具

在以下画面中进行 Developer Site 上的道具注册。

  1. 从控制板的左侧选单打开 “应用软件” > “应用软件一览” 画面。
  2. 从 “应用软件一览” 选择开发中的应用软件。
  3. 从控制板的左侧选单中选择 “添加道具” 。
  4. 输入您要注册的道具信息。 Adding Item

可以在 “道具管理” 画面中管理已输入的道具。可从控制板的左侧选单中选择 “道具管理” 来检视道具管理画面。在“道具管理”界面上可以对选中的道具进行更新、删除操作。

# 发送订单数据

# 检查 Mobage 登录状态

用户必须登录进Mobage才能进行道具购买。为了确认“当用户在选好要购买的道具，并按下购买按钮时，是否已经登录进Mobage”，请使用​​JavaScript SDK的 mobage.oauth.getConnectedStatus() 来装载登录状态的确认功能。 确认已登录Mobage后，便会向开发者服务器提交购买请求。

# Mobage Bank Debit API调用

通过POST从开发者服务器调用 Mobage RESTFul API 的Bank Debit，进行订单数据发送。

# URI

各个环境下的 Bank Debit Endpoint 的 URI 如下。

环境 URI
sandbox https://sb-app.mobage.jp/social/api/restful/v2.02
service https://app.mobage.jp/social/api/restful/v2.02
# Post Body

如下列所示，在Request Body中设置JSON对象进行POST。

{
    "items ": [
        {
            "item": {
                "id": "item_001",
            },
            "quantity ": 1
        }
    ],
    "state ": "authorized",
    "comment ": "Sample item x 1个购买数"
}

有关每个参数的补充信息，请参阅以下内容。 此处指定类型名称，是为了更易于解释JSON的层次结构。

参数 类型 说明
items Item[] Item 参数类型是 對象集合。
state string 请指定字符串 authorized 。
comment string 为显示用户购买记录的字符串。请输入表示购买内容的字符串。
# Item
参数 类型 说明
item ItemProperty 道具属性信息
quantity string 购买指定道具的数量
# ItemProperty
参数 类型 说明
id string 为要购买的道具 ID。必须是在Developer Site上注册的ID。

# Transaction ID的记录和Order ID的发行

记录在 Mobage Bank Debit API的响应中收到的 Transaction ID，并发行Order ID，以便在之后确认支付结果的步骤中使用。

Transaction ID和已发行的 Order ID，将作为响应返回给客户端。

# 调用支付对话框

要扣除梦宝币（MobageCoin），请调用JavaScript SDK 的mobage.ui.open() API ，调用支付对话框。

# API

mobage.ui.open(service , params , callback );

# 参数

参数 类型 说明
service string 要调用支付对话框时，请输入固定字符串 payment。
params PaymentParams 包含payment service用参数的 Object
callback function 调用对话框处理完毕后，在关闭UI时调用它。
# PaymentParams
参数 类型 说明
transactionId string 对于收到的支付请求，在Mobage服务器上依各请求分别发行的不重复ID
orderId string 对于发送的支付请求，在开发者服务器上依各请求分别发行的不重复ID

有关其他详细参数， 请参见mobage.ui .open() - payment 。

# Callback Function

参数 类型 说明
error PaymentError 错误对象
result PaymentResult 支付结果

# PaymentError

参数 类型 说明
error Error 错误代码
errorDescription string 错误说明
# PaymentResult
参数 类型 说明
signedResponse string 以JWT格式显示 response 的字符串。通常会把此数值发送到开发者服务器使用。
response Object 设成JWT格式之前的支付结果对象。通常不使用。

# 交付道具

要先验证支付结果，才能在开发者服务器上进行道具交付。 有关验证的装载方法，请参见支付结果验证。

请装载mobage.bank.clearPaymentBacklog 的调用，以便在交付道具后，能删除为恢复处理而保存的支付结果信息。

# 购买道具失败时的处理

在Mobage JS SDK的道具购买流程中，会先扣取梦宝谷币之后再发放道具。因此，如果中断了处理过程，则会变成已扣取梦宝谷币，但道具未交付的状态。

Mobage提供了几种可以从交付遗漏中恢复的方法，但是我们建议使用【批处理】的方式。

有关详细信息，请参阅 以批处理确认。

# 用词相关补充

词汇 说明
道具ID 在Mobage 的 Developer Site 上注册的道具ID
Transaction?ID 在Mobage服务器上依各请求分别发行的不重复ID
Order ID 在开发者服务器上依各请求分别发行的不重复ID

← 验证支付结果 →

MIT Licensed | Copyright © 2020-present DeNA.Co., Ltd. All rights reserved.