> 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/ai/web-sdk-skill.md).

# Web SDK SKILL

The second skill introduced in Launch on ONEstore with AI. This page covers actual usage only.

**Web SDK SKILL** is a tool that lets an AI coding agent integrate the ONE store H5 Game SDK into your HTML5 web game for you. Just install it, then tell your usual AI tool what you want in plain language — from loading the SDK to purchase and ad integration and the pre-release check.

<table><thead><tr><th width="223.716796875">Skill</th><th>When to use</th></tr></thead><tbody><tr><td><code>onestore-web-sdk</code></td><td>To add the ONE store SDK to an HTML5 web game, integrate <strong>in-app purchase and in-app ads</strong>, and check it before release</td></tr></tbody></table>

#### Install

{% stepper %}
{% step %}
**Before you start**

You'll need an HTML5 web game project with an entry HTML file — a vibe-coded game is fine too. The default install uses `npx`, so you'll need Node.js 22 or later. If you can't use Node.js, use the bash install script instead: macOS/Linux works out of the box; on Windows you'll need WSL or Git Bash.
{% endstep %}

{% step %}
**Install it**

**Repo**: [github.com/ONE-store/onestore\_web\_sdk\_skills](https://github.com/ONE-store/onestore_web_sdk_skills)

{% tabs %}
{% tab title="Tell your agent" %}
Copy the text below and paste it into your agent.

```
Run npx skills add ONE-store/onestore_web_sdk_skills in [my game project path]
to install the ONE store Web SDK SKILL.
Let me know the result in one line when done.
```

{% endtab %}

{% tab title="Run it yourself" %}

```bash
cd <my game project path>
npx skills add ONE-store/onestore_web_sdk_skills
```

It detects the agents used in your project and installs the skill for them. To target a specific agent, pass `-a claude-code`, for example.
{% endtab %}

{% tab title="Without Node.js" %}

```bash
git clone https://github.com/ONE-store/onestore_web_sdk_skills.git
cd onestore_web_sdk_skills
./install.sh <my game project path>
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Confirm it's installed**

Ask "check the ONE store web game SDK integration status." If you get a status table back, you're set.
{% endstep %}
{% endstepper %}

#### Where it runs

| Supported tools          |
| ------------------------ |
| Claude Code              |
| Cursor                   |
| GitHub Copilot (VS Code) |
| Gemini CLI               |
| OpenAI Codex             |
| Grok Build               |

#### What it can do

| Task              | Nature            | By hand                                                                   | With this skill                                                                                    |
| ----------------- | ----------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| Diagnose status   | 🟢 Read-only      | Not sure where to start, so you read through the whole guide              | Reads your project and shows a table plus what to do next (each finding points to the file)        |
| SDK integration   | 🟡 Modifies files | Working out SDK load placement, script execution order, and init by hand  | Wires init → loading → start and pause/resume/exit handling for you, in the same order             |
| In-app purchase   | 🟡 Modifies files | Granting items from the success response alone, discovered as a bug later | Adds purchase and product lookup code, plus the connection point for server-side verification      |
| In-app ads        | 🟡 Modifies files | Granting rewards without being sure the ad was watched to the end         | Adds rewarded and interstitial ad code, with branches that leave reward confirmation to the server |
| Embedding check   | 🟢 Read-only      | The screen fails only inside the app, and you can't tell why              | Points out the server and code requirements for the game to load inside the ONE store app (iframe) |
| Diagnose errors   | 🟢 Read-only      | Search the error value and cross-reference the guide, guessing            | Explains the cause, how to reproduce it, the fix, and what to verify                               |
| Pre-release check | 🟢 Read-only      | Go through a checklist by hand, top to bottom                             | Surfaces blockers first, and collapses everything that passed into a count                         |

#### Try it — natural language prompts

Copy these straight into your agent.

| Prompt                                                   | Result                                                                                                                                                                  |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `What can the ONE store web game skill do?`              | Lays out everything this skill can help with, then checks your integration status right away                                                                            |
| `What should I do next?`                                 | Re-checks current status and tells you what to ask for next                                                                                                             |
| `Check my ONE store web game SDK integration status`     | Shows what's done, what's left, and what to do next                                                                                                                     |
| `Add the ONE store SDK`                                  | Walks through loading the SDK, the init → loading → start flow, and pause/resume/exit handling in order                                                                 |
| `Add ONE store in-app purchase`                          | Adds purchase and product lookup code, and the connection point for verifying purchases on your server                                                                  |
| `Add a rewarded ad`                                      | Shows the reward only when the ad was watched to the end, and leaves the actual grant to your server                                                                    |
| `The screen is blank only inside the app`                | This is usually a server setting, not code. Narrows it down step by step, starting with the game URL's response headers (whether iframe embedding is allowed)           |
| `Check why I'm getting this error` (paste the error log) | For example, if a purchase returns `already_owned`, it means "you bought an unconsumed product again." It explains the cause, and that consumption is your server's job |
| `Run the pre-release check`                              | Surfaces only what could block release; everything else is marked as passed                                                                                             |

#### Call it with a command word

To pick a task directly, add a command word after the skill name. In Claude Code, type `/onestore-web-sdk doctor`, for example. In other tools, use that tool's way of invoking a skill, or ask in plain language like the prompts above.

| Command                  | What it does                                          |
| ------------------------ | ----------------------------------------------------- |
| `doctor`                 | Checks the current integration status (no file edits) |
| `integrate`              | SDK load, boot flow, lifecycle handling               |
| `iap`                    | In-app purchase and product lookup                    |
| `ads`                    | Rewarded and interstitial ads                         |
| `embed`                  | iframe embedding checks                               |
| `fix <error or symptom>` | Cause and fix for an error                            |
| `check`                  | Pre-release check (no file edits)                     |

#### FAQ

<details>

<summary>Is there anything this skill can't do?</summary>

* **Your game server**: purchase verification (`purchaseToken`), receiving payment notifications (PNS) and ad postbacks, and consumption are your server's job. The skill only wires up the connection point in the code.
* **ONEconsole registration**: registering in-app products, requesting ad placement IDs, and registering the test URL and test ID happen in ONEconsole.
* **Changing server settings**: for settings like iframe-allow headers and HTTPS, it tells you what to check and how, and stops there.
* **ONE store's hosting page and app**: it only covers your game's client code.

</details>

<details>

<summary>What version is this built against?</summary>

Built against ONE store H5 Game SDK `v1.1.0` and the web game integration guide revised September 18, 2026. It integrates using reference code based on the official sample, and if the skill and the integration guide disagree, it follows the guide.

The ad integration hasn't been verified on a real device yet. If you use ads, test them on a device before release.

</details>

<details>

<summary>What should I have ready before integrating?</summary>

There are 4 values you'll need.

| Value                     | Where to find it                                                                                                                                                     |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDK version               | Your ONE store contact or the [release notes](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/releasenote) — if you weren't told otherwise, it uses the latest |
| In-app product ID         | ONEconsole → Apps → (your game) → Monetization → In-App Products (managed products only)                                                                             |
| Ad placement ID           | ONEconsole → Apps → (your game) → Monetization → In-App Ads, requested per ad type — if you use ads                                                                  |
| How `requestId` is issued | Your server design — if you use rewarded ads. Issuing it on your server and mapping it to the user is recommended                                                    |

Even without these, code placement proceeds, and you'll be asked for anything missing with a form to fill in.

</details>

<details>

<summary>How do I get an ad placement ID?</summary>

Pick your game in ONEconsole, then:

1. Under Product Mgmt. → Web App Mgmt. → Main Info, set **use ads** to **Yes**.
2. Under Monetization → In-App Ads, press **request ID** for each ad type. You get one ID per type, and issuance takes about one business day.
3. For rewarded ads, once the ID is issued, register the callback URL and API key on the same screen. The server postback that confirms rewards goes to that URL.

No test placement IDs are provided. If you need one, contact <devhelper@onestore.net>. See [In-App Ads](https://onestore-dev.gitbook.io/dev/eng/docs/apps/product/monetization/iaa) for details.

</details>

<details>

<summary>The screen is blank only inside the app</summary>

This is usually your game server's settings, not the code. The ONE store app loads your game page in an iframe, so it won't show if the game URL's response headers include `X-Frame-Options: DENY` or `SAMEORIGIN`, or if CSP `frame-ancestors` doesn't include the ONE store domains. An HTTP URL, a redirect to another domain, or leftover frame-busting code can also cause it.

Ask "the screen is blank only inside the app" and it narrows it down step by step. For how to allow embedding, see [02. Pre Preparations](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/pre).

</details>

<details>

<summary>Purchases and ads don't work in the browser</summary>

That's expected. Purchases and ads only work inside the ONE store app. In a regular browser you get `platform_not_supported`, and the game is set up to stay playable with just the purchase and ad buttons turned off. To test inside the ONE store app, register a test URL and a test ID in ONEconsole. See [07. Runtime and Test Environment](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/test).

</details>

<details>

<summary>I watched the ad to the end, but the reward didn't arrive</summary>

Rewards are confirmed on your game server, not from the client response. Even when the ad result is `rewarded`, don't grant from that — grant after your server receives and checks the postback ONE store sends. If the code is right, check that the callback URL is registered and that `requestId` lets you tell whose reward it is.

`no_fill` during testing means there's no ad inventory right now, not that the integration is broken.

</details>

<details>

<summary>Buying the same product again fails</summary>

That's `already_owned`. A purchased product can't be bought again until it's consumed. Consumption happens on your game server after verifying `purchaseToken`, so check your server-side handling. Web games support managed products only (no subscriptions).

</details>

<details>

<summary>Are there install options?</summary>

With `npx skills add`, you can pick the agent to install for, like `-a claude-code`. The install script (`install.sh`) has 6 options.

| Option      | What it does                                                                  |
| ----------- | ----------------------------------------------------------------------------- |
| `--dry-run` | Shows what would be copied where, without changing anything                   |
| `--user`    | Installs to your home directory so it's available in every project            |
| `--all`     | Also installs to `.cursor/`, `.github/`, `.gemini/`, `.codex/`, and `.junie/` |
| `--pull`    | Pulls the latest version before installing                                    |
| `--force`   | Overwrites your install even if you've modified it                            |
| `--offline` | Skips the remote check                                                        |

You can also skip the script and copy the `skills/onestore-web-sdk` folder straight into your tool's skill path.

| Tool                                                | Project path      |
| --------------------------------------------------- | ----------------- |
| Claude Code                                         | `.claude/skills/` |
| Cursor · OpenAI Codex · Gemini CLI · GitHub Copilot | `.agents/skills/` |
| Grok Build                                          | `.grok/skills/`   |

</details>

<details>

<summary>I'd rather integrate manually, without the skill</summary>

The existing web game integration guide works fine on its own. This skill is built off the same public guide and official sample, so you can switch to manual work partway through and pick up right where you left off.

</details>

<details>

<summary>I reinstalled and nothing changed</summary>

Files you've modified yourself are never overwritten — you'll be told which ones. Merge them by hand and run it again, or pass `--force` if you really want to overwrite them.

</details>

<details>

<summary>My agent isn't using the skill</summary>

Ask "list the skills available right now" first.

* **Not in the list** — that's an install path issue. Double-check your tool reads from the right path, then restart your session after installing.
* **In the list but not being used** — try mentioning "ONE store" or "web game" in your request. If it still tries to write the code itself, add "use the skill for this."

</details>

<details>

<summary>Will it answer in my language?</summary>

Yes. The agent answers in the language you write in. Only code identifiers and SDK values (such as `reason`) stay as they are.

</details>

<details>

<summary>Where can I learn more?</summary>

* [Web game integration guide (H5 Game SDK)](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk)
* [H5 Game SDK release notes](https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk/releasenote)
* [ONEconsole: In-App Ads](https://onestore-dev.gitbook.io/dev/eng/docs/apps/product/monetization/iaa)
* [ONEconsole](https://dev.onestore.net/dev/)
* [Skill bugs and suggestions (GitHub Issues)](https://github.com/ONE-store/onestore_web_sdk_skills/issues)

</details>