> For the complete documentation index, see [llms.txt](https://onestore-dev.gitbook.io/dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onestore-dev.gitbook.io/dev/chi/tools/webshop.md).

# Webshop 联动指南

<figure><img src="/files/24EDDroLE5FUZhvOiFb0" alt=""><figcaption></figcaption></figure>

### 1. 用户信息联动

<a href="/pages/bqIVJxZUhS4mSwvVfNSN" class="button primary">查看规格</a>

<mark style="color:$info;">**\[Optional]**</mark> 游戏内可以展示跳转至 ONE webshop 的路径。

若跳转 URL 中包含用户的游戏 ID 和服务器信息，进入 Webshop 时会自动应用 ONE store 登录状态及购买输入信息，用户即可直接完成购买。

<details>

<summary><strong>Example</strong></summary>

<figure><img src="/files/NiySuOE50BRG2Tsd3EX2" alt=""><figcaption></figcaption></figure>

</details>

{% hint style="warning" %}
若根据游戏的隐私政策，游戏 ID 属于个人信息，则可能需要追加第三方个人信息提供同意流程
{% endhint %}

### 2. 服务器列表联动 <a href="#id-2" id="id-2"></a>

<a href="/pages/KrW624KPu4Qbf0xBDqiY" class="button primary">查看规格</a>

<mark style="color:$primary;">**\[Required]**</mark> 当用户进入 ONE webshop 详情页时，Webshop 会实时查询并展示游戏服务器列表。

{% hint style="info" %}
若道具需发放至特定服务器，开发者必须提供服务器列表查询 API。\
该 API 会在 Webshop 详情页中实时调用，用户选择服务器并完成购买后，所选服务器信息将一并通过 PNS 发送。

仅当在标题注册中将以下字段设置为：\
`Developer Center > Webshop > Main Info > Purchase Input Information` = `Purchase Identifier + Server`时，服务器列表才会向用户显示。
{% endhint %}

<details>

<summary><strong>Example</strong> </summary>

<figure><img src="/files/b4aMK1BTBmE7aRMxBh85" alt=""><figcaption></figcaption></figure>

</details>

### 3. 有效性验证 <a href="#id-3" id="id-3"></a>

<a href="/pages/7B3LSYnBQqJrHvpRVtNR" class="button primary">查看规格</a>

<mark style="color:$primary;">**\[Required]**</mark> 用于验证用户输入的游戏 ID 和服务器信息是否有效，并检查该道具是否可以购买。

* 游戏 ID 是用于标识最终接收道具的对象（用户或角色）的值。在网页商店中，该值以 `serviceUserId` 的形式传递。*<mark style="color:$info;">(根据游戏结构，该值可作为 UID 或角色 ID 使用。)</mark>*

### 4. PNS (Payment Notification Service)

<a href="/pages/iGxotgWabxTdtY3eHuPV#pns" class="button primary">查看规格</a>

<mark style="color:$primary;">**\[Required]**</mark> 用户完成支付后，Webshop 会通过 PNS 通知将支付结果及相关支付信息发送至游戏服务器。

PNS 支持 商用环境 和 Sandbox 环境。

### 5. 购买确认 <a href="#id-5" id="id-5"></a>

<a href="/pages/iGxotgWabxTdtY3eHuPV#purchase" class="button primary">查看规格</a>

<mark style="color:$primary;">**\[Required]**</mark> 为确保道具正确发放，必须执行 购买确认 流程。

根据需求，可使用两种 API 之一进行购买确认。

<table><thead><tr><th width="203.41845703125">API</th><th>Description</th></tr></thead><tbody><tr><td>consumePurchase</td><td><ul><li>常用于执行购买确认。</li><li>处理完成后，用户可以再次购买相同道具。</li></ul></td></tr><tr><td>acknowledgePurchase</td><td><ul><li>用于一次性道具。</li><li>处理完成后，用户将无法再次购买相同道具。</li></ul></td></tr></tbody></table>

{% hint style="warning" %}
**注意事项**

* 道具发放后必须执行购买确认。
* 若购买确认在 3 天内未完成，该购买将被视为发放失败并自动取消。
* 在购买确认完成之前，用户无法再次购买相同道具。
  {% endhint %}

{% hint style="success" %}
**可通过 `getUnconfirmedPurchases` API 查询尚未完成购买确认的记录。**

建议使用该 API 以确保稳定的支付处理。

* 详细说明请参考 [getUnconfirmedPurchases](/dev/chi/tools/billing/v21/serverapi.md#getunconfirmedpurchases) 文档。
  {% endhint %}

### TIP. Webshop 实施指南

{% hint style="warning" %}
完成 ONE webshop 接入后，请务必确认实际服务应用中的**商店布局**、**进入路径**、**用户体验（UX）及运营注意事项**。

* [应用内购商店与 Webshop 的正确布局](https://onestore-dev.gitbook.io/dev/chi/tools/pages/x8WOQcllG2hARcn672QY#id-2.-correct-placement-of-iap-store-and-webshop)
* [进入 Webshop 时的正确导航路径](https://onestore-dev.gitbook.io/dev/chi/tools/pages/x8WOQcllG2hARcn672QY#id-3.-correct-navigation-when-entering-the-webshop)
* [用户体验（UX）优化建议](https://onestore-dev.gitbook.io/dev/chi/tools/pages/x8WOQcllG2hARcn672QY#id-4.-ux-optimization-tips)
* [Webshop 详情页使用方式](https://onestore-dev.gitbook.io/dev/chi/tools/pages/x8WOQcllG2hARcn672QY#id-5.-utilizing-the-webshop-detail-page)
* [购买次数限制处理](https://onestore-dev.gitbook.io/dev/chi/tools/pages/x8WOQcllG2hARcn672QY#onewebshopintegrationguide-english-6.handlingpurchaselimits)
  {% endhint %}