# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://onestore-dev.gitbook.io/dev/chi/tools/webshop.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.