onestore-web-sdk

ONE store H5 Game SDK の統合

HTML5 ゲーム開発者が ONE store H5 Game SDK を追加し、問題を診断して、リリース前にゲームを確認できるようにします。ONE store アプリ（Android WebView）がゲームページを iframe 内に読み込み、SDK がアプリとの通信をすべて処理します。

重要

ユーザーの言語で回答してください。 このスキルは英語で書かれていますが、ユーザーの多くは韓国語で入力します。ユーザーが入力した言語で回答し、表示する内容はすべて翻訳してください。表の見出し、判定語、記入フォーム、末尾の提案メッセージも翻訳します。構成だけを維持してください。コード識別子、SDK 定数、reason 文字列は変更しないでください。このスキルのメニュー項目は 韓国語のラベル (英語のラベル) の形式で示されています。ユーザーの言語に合うものを使用してください。送信前に、最初の文、表の見出し、最後の提案がユーザーの言語になっていることを確認してください。

このスキルでできること

ユーザーからスキルで何ができるかを尋ねられた場合、または依頼なしでスキルが呼び出された場合は、以下の表を表示し、すぐにステータス確認を実行してください。ユーザーは普段の言葉で依頼できます。手順名を知っている必要はありません。

コマンド	普段の言葉での例	実行する内容
doctor	「ONE store の統合はどこまで進んでいますか？」 / 「지금 어디까지 됐어?」	ステータス確認。 存在するものと不足しているものを表にまとめて報告します。ファイルは編集しません
integrate	「このゲームを公開できるように ONE store SDK を追加してください」 / 「원스토어 SDK 붙여줘」	SDK を読み込み、起動フロー（初期化 → 読み込み → 開始）を接続し、ライフサイクルのリスナーを配置します
ads	「リワード広告を追加してください」 / 「리워드 광고 붙여줘」	requestId と報酬ポリシーを含む広告コードを配置します
iap	「アプリ内課金を追加してください」 / 「결제 붙여줘」	購入コードと商品検索コードを配置し、サーバー側で purchaseToken を検証するためのフックも含めます
embed	「アプリ内でだけ失敗します」 / 「앱에서만 안 떠」	iframe 埋め込み要件を確認します（references/embed-requirements.md）
fix <reason または症状>	「画面が真っ白です」 / 「reason が no_fill です」	診断。 原因、再現方法、修正方法、確認事項を示します（references/diagnose.md）
check	「リリース前のチェックを実行してください」 / 「릴리즈 전에 점검해줘」	リリース前のチェックリスト全体を実行します。ファイルは編集しません

コマンドワード

ユーザーはコマンドワードを使って手順を直接呼び出せます。Claude Code では、形式は /onestore-web-sdk <command>（例：/onestore-web-sdk doctor）で、コマンドワードはスキルの引数として渡されます（ARGUMENTS: doctor）。他のツールではスキルの呼び出し方が異なり、onestore doctor や /원스토어 진단 のようにチャットに入力するだけのユーザーもいます。これらはすべて同じように扱ってください。

• コマンドワードだけが指定された場合は、その手順をすぐに実行してください。 対象ファイルが不明確な場合に限り、確認してください（ルール 3）。
• コマンドワードなしでスキルが呼び出された場合 → ステータス確認を実行し、上記の表を表示します
• 次のステップを提案する際は、どのツールでも使える普段の言葉での依頼を先に示し、その後に Claude Code での形式を追加してください

また、対応範囲も明確にしてください。ゲーム会社のサーバー側の作業（ポストバックの受信、purchaseToken の検証、購入の消費）と ONE store への登録（プレースメント ID、商品、テスト URL）はユーザーの作業であり、このスキルでは ONE store のホスティングページやアプリは扱いません。

ユーザーから取得する必要がある値

4つだけです。3つはONE store側から取得し、1つはゲーム会社のサーバー設計に関するものです。 多くのユーザーは何が必要かわからない状態から始めるため、最初に必要な値を伝え、それぞれの取得先も案内してください。

値	取得先	未取得の場合
SDK version	ユーザーのONE store担当者、またはリリースノート。vで始まります。特に指定がなければ、最新のv1.1.0を推奨してください	v1.1.0で進められます
広告プレースメントID（placementId）	ONEconsoleで申請します：Apps > （ゲーム） > 수익화 > 인앱 광고（収益化 > アプリ内広告）。広告タイプ（リワード、インタースティシャル）ごとに1つ必要です。ONEconsole：인앱 광고（アプリ内広告）を参照してください	すべての広告リクエストがフォールバックなしで失敗します
アプリ内商品ID（productId）	ONEconsole：Apps > （ゲーム） > 수익화 > 인앱 상품（収益化 > アプリ内商品）。管理対象商品に限ります	購入がinvalid_requestで失敗します
requestIdの発行方法	ゲーム会社のサーバー設計です。サーバー側で発行し、ユーザーに紐付けることを推奨します	ポストバックが誰の報酬に関するものか判別できません

値を尋ねるときは、記入用のフォームを提示する

「Xがありません」とだけ伝えても、ユーザーは何をどこから取得すればよいかわかりません。 以下のフォームをそのままユーザーの言語に翻訳して送り、コピーして記入したものを貼り付けてもらってください。

SDK version: (leave blank to use the latest, v1.1.0)
        Fill this in only if ONE store gave you a specific version. It starts with v.
        It goes into the {{version}} part of the CDN URL.

Ad placement ID: (write it here, e.g. rewarded rew_xxxx, interstitial int_xxxx)
        Request it in ONEconsole: Apps > (the game) > 수익화 > 인앱 광고
        (Monetization > In-App Ads). Rewarded and interstitial
        IDs are issued separately, so say which one this is.

In-app product ID: (write it here, e.g. gem_100, gem_1000)
        The product ID registered in ONEconsole under 수익화 > 인앱 상품 (Monetization > In-App Products).
        If there are several, list them all separated by commas. (Managed products only.)

requestId issuing: (server-issued / generated on the client)
        The tracking key for rewarded ad rewards. The postback must tell you which user
        the reward belongs to, so issuing it on your server and mapping it to the user
        is recommended.

• 値の記入欄は空欄のままにしてください。 例の値をあらかじめ入力しておくと、そのままにするユーザーがいます
• 実際の値を例として使わないでください。 プロジェクト内で見つけたIDをフォームに記載しないでください。 すでに把握している値は文章で伝え、フォームは空欄のままにしてください
• まだ登録や発行が済んでいないものがあれば、まずONE store側で対応が必要だと伝えてください
• 値を受け取ったら、それをどのファイルに設定したか伝えてください

値がそろっていなくても連携作業を開始できます。 SDKを読み込み、起動フローを組み込み、リスナーを配置して、値の欄はTODOのままにしてからフォームを提示し、そこで止めてください。値を待つ間、作業を止めないでください。

次のステップがあなたの作業なら、依頼文を用意する

残りの作業があなたの担当なら、ユーザーがすることは依頼するだけです。 作業内容を説明するだけでは、ユーザーは自分で対応しなければならないと思い、先に進めなくなります。作業ではなく、依頼文を提示してください。 コピーして送れる依頼文を、目立つようにコードブロックに入れてください。

Send this next:

  Add a ONE store rewarded ad to the game

I will wire it with the reward policy (show the reward only on rewarded, grant it through
the server postback). In Claude Code you can also send /onestore-web-sdk ads.

After that:

  Run the ONE store pre-release check

• 各依頼に対応する成果を添えてください。 何ができるのかをユーザーが確認し、選べるようにします
• 複数のステップが残っている場合は、すべて順番に列挙してください。 現在のステップだけを示すと、ユーザーは各ステップのたびに再び手詰まりになります
• ユーザー側の作業（ONE storeへの登録、サーバーコード）とあなた側の作業が混在している場合は、分けて列挙してください

基本ルール

1. SDK APIを創作しないでください。 references/sdk-context.md に記載されているメソッド、フィールド、イベント、reason の値のみを使用してください。記載されていない場合は、確認が必要だと伝えてください。似ているように見えても、他のプラットフォームのゲームSDK（Facebook Instant Gamesなど）の名前に対応付けないでください。
2. 統合コードは references/game-template.html.txt から取得してください。 これは、起動フロー、広告、購入、ライフサイクルに関する、公式サンプルに基づく参考コードです。既存のゲームに追加する場合は、該当部分を移してください。ただし、呼び出し順と分岐構造は維持してください。特に、err 分岐、報酬分岐（rewarded のみ）、reason 分岐を維持してください。配置後、適合しない場合は調整してください。
3. 証拠に基づいて対象を決めてください。 ゲームのエントリーHTMLと起動コードの場所を示す証拠がない場合、または候補が複数ある場合は、推測せずに質問してください。
4. 断定するか、質問してください。 「おそらく」や「通常は」などと曖昧にしないでください。判断に必要な情報が不足している場合は、必要な情報を具体的に尋ねてください。
5. 証拠は path:line 形式で示してください。 プロジェクトルートからの相対パスと行番号を使用してください（例：index.html:47）。ツールによってリンクの表示方法が異なるため、この形式ならどこでも読め、多くのツールでクリックできます。絶対パスや file:// リンクは使用しないでください。証拠箇所が示されていない判断は修正してください。詳しく知るためのリンク先には公開ガイドのURLを示してください。参照ファイルはユーザー向けではありません。
6. 次のステップで終えてください。 行ったことの説明で終わらせないでください。ユーザーが行う場合は、その場で実行できるよう具体的に示してください（メニューの経路、完全なコマンドなど）。あなたが行う場合は、ユーザーが送信できる依頼文を示してください。値が不足していて作業を止めた場合は、続行に必要な情報を伝えてください。残作業がない場合は、その旨を伝えてください。「次は何をすればいいですか？」と聞かれたら、このルールに従っていません。
7. 既存ファイルを上書きしないでください。 現状を示して、確認を求めてください。
8. 対象範囲はゲームのクライアントコードです。 ゲーム会社のサーバー側（ポストバックとPNSの受信、purchaseToken の検証、消費処理）については、フックのみを作成し、実装はユーザーが行うと伝えてください。サーバーフレームワークはセットアップしないでください。

まず行うこと：ステータス確認（doctor）

自由形式の依頼（「追加して」「進捗はどう？」「次は何？」など）、スキルを呼び出した際に依頼がない場合、またはプロジェクトの状態がまだ分からない場合は、まずステータス確認を実行してください。統合の途中であっても、記憶に頼らず、ファイルを読んで判断してください。

• references/checks.md の list A に従ってください。
• 読み取りのみとし、ファイルは編集しないでください。
• 使う判定は present / missing / not applicable / needs confirmation の4つのみです。証拠は path:line 形式で示してください（ルール5）。
• 表全体を表示してください。 すでに完了している項目も示すことが目的です（リリース前チェックでは、修正が必要な項目のみを示します）。
• 表の下に、次のステップを示してください（ルール6）。値が不足している場合は、必要な値のみを記入するフォームを提示してください。次のステップがあなたの作業である場合は、送信すべき依頼文を提示してください。
• ユーザーからすでに作業を進めるよう指示されていない限り、ここで止めて選択を待ってください。

統合手順

ステータス確認で missing と判定された項目のみ対応してください。

1. SDK を読み込む

ゲームのエントリー HTML ドキュメントの最上位に、ゲームのスクリプトより前に配置してください。

<script type="module">
  import { createSDK } from "https://h5sdk.onestore.net/lib/v1.1.0/onestore-h5-sdk.min.js";
</script>

• バージョンは v で始まります。ユーザーから指定されたバージョンを使用し、指定がない場合は**最新の v1.1.0**を使用してください。 バージョンが原因で作業を止めないでください
• ゲームが独自に作成する iframe 内では初期化に失敗します。ゲームドキュメントの最上位に配置する必要があります
• ゲームでバンドラー（webpack など）を使用している場合は、ゲームのエントリーの最上部にインポートを配置し、HTML から直接読み込む場合と同じ順序で実行されることを確認してください
• タグの順序だけでは実行順序は保証されません。 type="module" はドキュメントの解析後に実行されるため、通常の <script src> で読み込まれるゲームスクリプトは、タグが後にあっても SDK より先に実行されます。ゲームスクリプトに type="module" または defer を追加して SDK の後に実行し、startGameAsync() が成功してからゲームを開始してください

2. 起動フローとライフサイクル

references/game-template.html.txt のスクリプト部分を、ゲームの起動コードに合わせて配置してください。必須の呼び出し順序とルールは references/sdk-context.md で定義されています。配置した後は、必ずユーザーに次の内容を伝えてください。

• initializeAsync() の前にリスナー（pause / resume / exit）を登録してください。 初期化の直後にイベントが届く場合があります

• exit では、0.5 秒以内に同期的に保存する処理だけを行ってください。 quit() を再度呼び出す必要はありません。ゲーム自体が quit() を呼び出すと exit は発生しないため、その前に保存してください

• onBackPressed は同期関数である必要があります。 アプリは応答を 200 ms 待ちます

• 未対応の環境では、拒否されるのではなく err を含む結果が返されます。if (info.err) の分岐を削除しないでください。この分岐では、SDK なしでもゲームをプレイできるようにし（広告と購入の UI のみを無効にする）、通常のブラウザーでも開発中に動作するようにしてください

• 読み込みの進捗を、実際のアセット読み込みに連動させてください。テンプレート内のデモ用タイマーは仮のものです

• ゲームがオブジェクトをグローバル変数に保持する場合、要素の id と同じ名前を付けないでください。 ブラウザーは id のある要素を、同じ名前の window プロパティとして公開します。<canvas id="game"> の場合、ゲームコードが上書きするまでは window.game がキャンバスを指すため、先に実行される起動コードは window.game.start is not a function というエラーで失敗します。ゲーム名に基づくグローバル変数（たとえば window.StarCatcher）を使用し、起動コードでは呼び出す前にオブジェクトの準備ができていることを確認してください

• SDK のコードとゲームのコードが別々のスクリプトにある場合は、呼び出す前にゲームオブジェクトの準備ができるまで待ってください。 SDK のスクリプトが先に実行されるため、ゲームスクリプトが実行される前に initializeAsync() の結果が返ることがあります（通常のブラウザーでは、ほぼ即座に解決します）。その時点でゲームオブジェクトを呼び出すとエラーが発生し、ゲームが起動しません。SDK コードからゲームへのすべての呼び出し（err 分岐、startGameAsync の後、pause / resume、ringerSilent）を、次のようなヘルパー経由にしてください。

  // Game scripts load with type="module" or defer, so they have all run by DOMContentLoaded
  function whenGame(fn) {
    if (window.MyGame) fn(window.MyGame);
    else document.addEventListener("DOMContentLoaded", () => fn(window.MyGame), { once: true });
  }
  // whenGame((game) => game.start());
  

  この方法は、ゲームオブジェクトがスクリプトの最上位で作成される場合に機能します。アセットの読み込み後など、ゲームが後からオブジェクトを作成する場合は、ゲーム側から独自の「準備完了」シグナルを送信してください

3. 広告

コードを配置する前に、placementId が存在することを確認してください。存在しない場合は、TODO を含めてコードを配置し、フォームから値を送ってもらうよう依頼してください。配置した後は、インシデントの原因となるため、必ず次の3点をユーザーに伝えてください。

• 報酬を表示するのは status === "rewarded" の場合のみです。 dismissed と failed（no_fill を含む）は報酬対象ではありません
• クライアント側の rewarded 結果から報酬を付与しないでください。 報酬の付与は SSV → 検証 → ゲーム会社のサーバーポストバックを通じて確認され、ゲーム側は報酬が付与されたかどうかを自社サーバーに問い合わせます。ポストバックの受信はユーザー側の作業であることを別途伝えてください
• リワード広告には requestId が必要です。 SDK はこれを生成しません。サーバーで発行し、ユーザーに紐付けることを推奨します

ユーザーがまだプレースメント ID を持っていない場合は、ONEconsole で次の順に操作するよう案内してください（出典： ONEconsole: イン앱広告（In-App Ads）、英語版 https://onestore-dev.gitbook.io/dev/eng/docs/apps/product/monetization/iaa）：

両方のメニューは、Apps でゲームを選択した後、ゲームのサイドバーにあります。

1. 상품관리 > Web 상품관리 > 기본정보（商品管理 > Web 商品管理 > 基本情報）で、광고 적용 여부（広告の適用）を 예（はい）に設定します
2. 수익화 > 인앱 광고（収益化 > アプリ内広告）で、各広告タイプの ID 발급 요청（ID 発行をリクエスト）を押します。広告タイプごとに ID は1つです。発行には通常、1営業日ほどかかります
3. リワード広告の場合は、ID の発行後、同じ画面でコールバック URL と API キーを登録します。報酬を確認するサーバーポストバック（SSV）は、その URL に送信されます。インタースティシャル広告のみの場合は不要です
4. テスト用プレースメント ID は提供されていません。ユーザーが必要とする場合は、[email protected] に問い合わせてもらってください

プリロード呼び出し（loadRewarded / loadInterstitial）は、早い段階で、たとえば startGameAsync の成功直後に配置してください。ボタンを押したときに広告がすぐ表示されるようになります。呼び出しがなくても動作しますが、最初の広告の表示に時間がかかります。

このスキルでは、デバイス上で広告サポートのエンドツーエンドの動作確認はまだ行われていません。リリース前にデバイスで広告をテストするようユーザーに伝えてください。

後からユーザーからプレースメント ID が提供された場合

空の ID で広告コードを配置していた場合、ID を受け取ったら、値を1つ埋めるだけでは不十分です。次のすべてを行ってください。

1. ID はそれぞれ専用のスロットに配置します。 リワード ID は loadRewarded / showRewardedAsync で使われる箇所に、インタースティシャル ID は loadInterstitial / showInterstitialAsync で使われる箇所に配置します。ユーザーがどちらの ID を送ったのか不明な場合は、確認してください。2つの ID は別々に発行され、プレースメントタイプが一致しないと invalid_request エラーになります
2. ID が空だったため無効にしていたものを再び有効にします。無効化された広告ボタン、スキップされたプリロード、早期の return、「未設定」というラベルなどが該当します。定数に値を入れるだけでは、ボタンが無効のままになることがよくあります
3. 順序を維持します：初期化後に機能を確認（sdk.ads.isSupported(...)）→ プリロード → ボタンを有効化
4. 変更したファイルと行番号（path:line）を伝えます
5. 確認方法を伝えます：広告は ONE store アプリ内でのみ表示されます（通常のブラウザーでは常に platform_not_supported が返されます）。テスト URL とテスト ID が登録されている必要があります。テスト中に no_fill が返された場合は、現在広告在庫がないことを意味し、連携が壊れているわけではありません

4. 購入

コードを配置する前に、productId が存在することを確認してください。存在しない場合は、TODO を含めてコードを配置し、フォームで値を尋ねてください。配置後は、必ずユーザーに次の内容を伝えてください。

• 成功レスポンスが返っても、アイテムを付与する理由にはなりません。 ゲーム会社のサーバーが purchaseToken を検証して購入を確認します。決済通知（PNS）もサーバーに届くため、サーバーを基準にアイテムを付与してください
• 消費処理はサーバー側で行います。 消費処理を行わないと、同じ商品を再度購入しようとしても already_owned エラーになります
• アイテムの付与に必要な情報を developerPayload に設定してください。 これは任意ですが、非常に重要です。購入結果と PNS 通知はこの値によってユーザーと購入に紐付けられるため、空のままにすると両者を紐付ける手段がなくなります。ゲームの構成に基づいて、設定する値（ユーザー識別子など）を提案してください。ただし、推測で決めないでください
• user_cancelled の場合はエラーポップアップを表示しないでください
• 購入リクエストによって pause（reason: "payment"）イベントと resume イベントが発生します。購入の呼び出し箇所で別途ゲームを一時停止しないでください。1 つの pause リスナーで処理してください
• Web 商品でサポートされるのは管理対象商品のみです（サブスクリプションは対象外です）

5. 埋め込み要件

これらはコードの外にあるため、見落としやすい項目です。references/embed-requirements.md を確認し、サーバー設定（フレーム許可ヘッダー、HTTPS、リダイレクト）は確認が必要な事項として引き継え、確認方法（curl -sI）も伝えてください。フレームの表示を妨げるコードはすべて削除する必要があることもユーザーに伝えてください。

エラーの診断

受け取った内容	最初に確認する場所
reason 文字列またはコンソールログ	references/sdk-context.md の reason 表を調べ、その処理をプロジェクト内で行っている箇所を示してください
「表示されない」などの症状のみ	references/diagnose.md。収集すべき情報と、原因の絞り込み方が記載されています

症状だけをもとにコードの調査を始めないでください。原因はコードの外（サーバーヘッダー、ONE ストアへの登録、アプリのバージョンなど）にあることがよくあります。自分で確認できること（curl -sI、コンソールでの再現）を確認してください。実行できない場合は、コマンドと手順を提示して結果を尋ねてください。推測を答えとして提示しないでください。

原因、再現方法、修正方法（コードを含む）、確認事項を回答してください。コードでは修正できない理由（no_fill、platform_not_supported など）の場合は、その旨を伝え、適切な対応（UI を非表示にする、別の手段を用意する）を示してください。

リリース前チェック

references/checks.md のリスト Bに従ってください。読み取りのみ行います。サーバーまたは ONE ストアへの登録に依存する項目は、コードにフックがあることだけを確認し、それ以外はプロジェクトの範囲外であると伝えてください。

修正が必要な項目のみ列挙してください。 合格した項目は件数で示してください。順序は、ブロッカー → 非ブロッカー → 確認が必要な項目 → 合格件数です。

参照ファイル

必要なものだけを読んでください。

• references/sdk-context.md：公開 API 全体、呼び出し順序、イベント、reason 表、CDN URL、付与ルール（正しい情報源）
• references/game-template.html.txt：参考用の統合コード（__SDK_VERSION__ を置き換え、TODO を埋めてください）
• references/embed-requirements.md：iframe 埋め込み要件（フレームの許可、URL、ストレージ、禁止されている呼び出し、画面）
• references/checks.md：リスト A（ステータスチェック）とリスト B（リリース前チェック）
• references/diagnose.md：症状から問題の原因を絞り込む方法

公開ドキュメント：Web SDK Integration Guide https://onestore-dev.gitbook.io/dev/tools/web-sdk（英語版 https://onestore-dev.gitbook.io/dev/eng/tools/web-sdk）