API リファレンス
作者の手元・CI・エディタ拡張から、ゲームの作成と設定変更・サムネイルとビルドのアップロード・ランキングの宣言・アナリティクスの取得・ゲーム内アイテムの商品の登録を行う HTTP API です。
ゲームの中から呼ぶ API(ランキングへの投稿・公開プレイヤー状態・リアルタイムマルチプレイ)は SDK ガイド を見てください。
1. はじめに
API はすべて https://gamerush.jp/api/ の下にあります。本文は JSON で送り、応答も JSON で返ります。成功は 200 です(商品の作成だけ 201)。
認証は、Studio の API トークン で発行したトークンを Authorization: Bearer に載せるだけです。発行のしかた・権限の選び方・置き場所の注意は SDK ガイドの API トークン にあります。
export GRUSH_TOKEN="grush_pat_..."
curl "https://gamerush.jp/api/games" \
-H "Authorization: Bearer $GRUSH_TOKEN"トークンをゲームのビルドへ入れないでください。ここにある API は、作者の手元・CI・エディタ拡張から呼ぶためのものです。
- トークンで呼べるのは、このページに載っている API だけです。アカウントの操作・コメント・フォローなどは、トークンでは
401になります。 - トークンから新しいトークンは発行できません。
- 運営の管理権限はトークンには乗りません。管理者が発行したトークンでも、触れるのは本人がオーナーか共同制作者のゲームだけです。
エラーの形
失敗すると、error(英語の説明文)と code(機械で読める識別子)の片方か両方を持つ JSON が返ります。code には params が添えられることがありますが、付かないこともあります。details が付くこともあります。
{ "error": "API token is missing the games:write scope." }
{ "code": "build.tooManyFiles", "params": { "limit": 2000 } }
{ "error": "This feature is temporarily unavailable.", "code": "service.featureDisabled", "params": { "feature": "uploads" } }| HTTP | よくある原因 |
|---|---|
| 400 | リクエストの形が違う(必須の項目が無い、ビルドのファイル一覧の形が違う、パスのゲーム・ビルド・ランキングの id が UUID の形でない など) |
| 401 | トークンが無い・形が違う・期限切れ・失効済み |
| 403 | トークンに必要な権限が無い。規約や素材の権利への同意が無い。アカウントがゲームの投稿を止められている(post.banned) |
| 404 | ゲームが無い。トークンの対象ゲームに入っていない。自分がオーナーでも共同制作者でもない |
| 409 | 状態がぶつかった(審査の途中で変わった、同じ key が既にある など)。作成の冪等キーで先の要求が終わっていない(operation.inProgress。少し待って同じキーで送り直す) |
| 410 | 作成の冪等キーで先に作ったものが消されたか、ビルドが失敗している(operation.gone。新しいキーで作り直す) |
| 422 | アップロードしたビルドの中身の検査で弾かれた。作成の冪等キーを違う本文で使った(operation.bodyMismatch) |
| 503 | サービス全体を止めている(service.suspended)か、アップロードの機能を止めている(service.featureDisabled、params.feature が uploads)。ビルドの完了の一時的な失敗でも返る |
アップロードの機能を止めている間に 503 になるのは、ゲームの作成(POST /api/games)、ビルドの作成(POST /api/games/:id/builds)と完了(POST /api/builds/:id/complete)、サムネイルなど画像の項目を含む PATCH /api/games/:id です。読み取りと、画像を含まない設定の変更は通ります。
止めているときの 503 の応答には Retry-After: 300 が付きます。止めている間は何度呼んでも同じなので、すぐに再試行せず、Retry-After の秒数だけ待ってから呼び直してください。Retry-After の無い 503 は一時的な失敗で、少し待てば呼び直せます。
対象ゲームを絞ったトークンを他のゲームへ向けたときは、存在を漏らさないために 403 ではなく 404 になります。
2. ゲーム
| API | 権限 | 内容 |
|---|---|---|
GET /api/games | games:read | 自分のゲームと、共同制作者として加わっているゲームの一覧 |
GET /api/games/:id | games:read | ゲーム1本と最新ビルド |
POST /api/games | games:create | ゲームの新規作成 |
PATCH /api/games/:id | games:write | タイトル・説明・遊び方とそれらの言語と訳・元 URL・サムネイル・実況ポリシー・公開設定の変更 |
GET の応答は { games: [...] } / { game } です。各ゲームには id・title・visibility・review_status・requested_visibility・streaming_policy・thumb_url・thumb_wide_url・thumb_tall_url・play_count などと、最新ビルドの latestBuild が入ります。public のゲームで最新ビルドが審査待ちか差し戻しのあいだは、配信中の承認済みのビルドが publishedBuild に入ります(それ以外は null)。latestBuild と publishedBuild に、ビルドのファイルの一覧(file_manifest)は入りません。approved_build_id は承認済みのビルドの id です。leaderboard_manifest_build_id は、grush.json のランキングの定義を承認の時点まで繰り延べているビルドの id で、繰り延べていなければ null です。title と description から読んだハッシュタグは、全角と半角などの互換の違いと大文字・小文字をそろえ # を外した形で、タイトル、説明の順に hashtags に入ります。hashtags はタイトルか説明を書くときに書くので、タイトルや説明に # があっても hashtags に無いタグを持つ作品があり、タイトルか説明を保存し直すと入ります。既定の文面を書いた言語は source_locale に、言語ごとの訳は localizations に入ります(訳を書く)。entryUrl は、最新ビルドが ready のときのその入口の HTML の URL で、それ以外は null です。viewerRole は呼んだ人の立場(owner か collaborator)、viewerCanAdminister はオーナーにだけできる操作(ゲームの削除・オーナーの譲渡・共同制作者の管理)ができるかです。
ゲームを作る
curl -X POST "https://gamerush.jp/api/games" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"title": "ねこジャンプ",
"description": "タップで跳ぶだけのショートゲーム。迫ってくる壁のすき間をくぐり抜け、どこまで遠くへ進めるかを競います。進むほどスピードが上がり、壁の形も変わっていきます。ランキングで友だちと記録を比べたり、毎日のチャレンジでコインを集めたりできます。#ねこ",
"howToPlay": "画面のどこかをタップすると、ねこが少しだけ跳びます。長押しすると高く跳べます。壁のすき間に合わせてタイミングよく跳び、壁にぶつかるとゲームオーバーです。ときどき出てくる魚を取るとシールドが付き、1回だけ壁に当たっても続けられます。",
"visibility": "public",
"streamingPolicy": "allowed",
"acceptTerms": true,
"confirmAssetRights": true,
"declareAllAges": true
}'| フィールド | 内容 |
|---|---|
title | 必須。120 文字まで。改行は空白になる。#パズル のように書いた語はゲームのハッシュタグになり、検索の #パズル で完全一致で見つかる。ハッシュタグは description と合わせて5個まで(同じタグは1つと数える)で、超えると 400(title.tooManyHashtags)。PATCH でも同じだが、保存済みのタイトルと説明が合わせて上限を超えているときに、どちらも変えない要求(同じ値を送るか、送らない)は、400 にせず、タイトルと説明を書かずにほかの項目を書く |
description | 必須。100 文字以上 2000 文字まで(前後の空白を除いた文字数)。足りないと 400(description.tooShort)。#パズル のように書いた語は title と同じくハッシュタグになる。URL の中の # はハッシュタグにならない |
howToPlay | 必須。遊び方(操作やルール)。100 文字以上 2000 文字まで(前後の空白を除いた文字数)。足りないと 400(howToPlay.tooShort) |
sourceLocale | title・description・howToPlay を書いた言語。ja / en / ko / zh-Hans / zh-Hant / id / fil / vi / th のどれか。省略するか null なら未設定(既定の文面の言語) |
localizations | 言語ごとの訳。形と検証は PATCH と同じ(訳を書く)。空の項目と、title などの既定の文面と同じ訳は保存されない。sourceLocale を指定したときは、保存した後にその言語の訳が残る要求は 400(localizations.sourceLocale)。既定と同じ文面か空の項目だけなら、正規化で落ちて残らないので通る(既定の文面の言語) |
visibility | public / unlisted / private。unlisted と private は指定した可視性で作られる。public を指定したゲームは原則 private で始まり、最初のビルドが完了した時点で審査に積まれる(オーナー本人が審査免除の作者か管理者なら審査を経ずに public で作られる)。省くか、ほかの値(Public のような打ち間違いを含む)を送ると、エラーにはならず private で作られる(PATCH ではほかの値は 400) |
sourceUrl | 元の配布ページなど。http / https で 500 文字まで |
streamingPolicy | 実況ポリシー。下の表を参照 |
streamingPolicyNote | conditional のときだけ保存される条件の説明。500 文字まで |
officialFeatureOptOut | GameRush 公式の特集記事や SNS での紹介を断るなら true。省略すると false(紹介してよい)。真偽値でなければ 400 |
acceptTerms | 必須。利用規約 と ゲーム掲載ポリシー に同意するなら true |
termsVersion | 任意。同意した利用規約の版(2026-10-07 のような施行日の文字列)。送ると作成の時点で施行中の版と照合し、違えばゲームを作らずに 409(terms.versionMismatch。施行中の版を details.termsVersion に入れる)を返す。文字列でなければ 400(terms.versionRequired)。省略するか null なら照合しない |
confirmAssetRights | 必須。画像・音・コードなどの素材をすべて自分で作ったか、使う権利を持っているなら true。true でなければゲームを作らずに 403(rights.confirmRequired) |
declareAllAges | visibility が public / unlisted なら必須。ゲームが全年齢向けに適した内容であることを申告するなら true。申告した時刻と申告した人をゲームに記録する(private で送っても記録する)。public / unlisted で false か省略ならゲームを作らずに 403(ageRating.declarationRequired)。private なら省略しても作れ、公開へ変えるときに求められる。真偽値でなければ 400 |
thumbnail | サムネイルを同時に上げるとき(16:9 の thumbnailWide、9:16 の thumbnailTall も同じ)。サムネイル を参照 |
応答は { game, mediaUploads } です。本文に冪等キー operationId(1〜100 文字の文字列)を付けると、応答が失われた後に同じキーと同じ本文で送り直しても2つ目のゲームはできず、先に作ったゲームが返ります。mediaUploads には、まだ上がっていないサムネイルの URL だけが、ゲームが一度も審査を経ておらず審査待ちでもない間だけ入ります。キーはアカウントごとに区別し(同じアカウントのトークンと Studio で共有します)、24 時間保持します。termsVersion だけが違う再送は同じ本文として扱います。同じキーで本文が違えば 422(operation.bodyMismatch)、先の要求が終わっていなければ 409(operation.inProgress。少し待って同じキーで送り直します)、先に作ったゲームが消されていれば 410(operation.gone)、今はそのゲームを管理できなければ 403 を返します。作成が途中で失敗したときは、本文を直して同じキーで送り直せます。operationId を付けない作成は再試行するたびに別のゲームを作るので、機械的に再試行せず、応答が失われたら GET /api/games で作られたかを確かめてからやり直します。
トークンでゲームを作るスクリプトや CI も、visibility に public / unlisted を指定するときは declareAllAges: true を送る必要があります。無ければ 403 になり、ゲームは作られません。private で作る要求は declareAllAges が無くても作れます(confirmAssetRights: true はどちらでも必須です)。
対象ゲームを絞ったトークンではゲームを作れません(まだ無いゲームは対象に入れられないため)。
設定を変える
PATCH は送ったフィールドだけを変えます。Studio の保存ボタンと同じ処理を通るので、審査やホールドの扱いも画面と同じです。
curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"streamingPolicy": "conditional",
"streamingPolicyNote": "収益化した配信ではクレジットを表示してください",
"visibility": "unlisted",
"declareAllAges": true
}'| streamingPolicy の値 | 意味 |
|---|---|
allowed | 実況・動画投稿を許可する |
conditional | 条件付きで許可する(条件は streamingPolicyNote) |
prohibited | 実況・動画投稿を許可しない |
unspecified | 未設定(既定) |
実況ポリシーの意味と、プレイヤーにどう見えるかは ゲーム実況ポリシー にあります。officialFeatureOptOut も PATCH で切り替えられ、真偽値でなければ 400 になります。sourceUrl に null か空文字を送ると消えます。
PATCH の description と howToPlay は、保存されている値から変える項目にだけ、POST と同じ100文字以上を求めます。保存されている値と同じ値を送る要求と、送らない要求は、100文字に届かない値のままでも通ります。null や空文字で消す要求は、100文字に届かないので 400(description.tooShort / howToPlay.tooShort)になります。既定の文面の言語を入れ替えて既定の説明と遊び方を変えるときも、新しい既定の説明と遊び方に100文字以上が要ります。
title か description を送ると、ハッシュタグも書いた後のタイトルと説明から読み直して書きます。変えた結果が合わせて5個を超えると 400(title.tooManyHashtags)です。上限ができる前に保存した、タイトルだけで上限を超えるゲームでは、タイトルを変えずに説明だけを変える要求は、説明を書き、タイトルとハッシュタグは書きません。
全年齢の申告(declareAllAges)の記録が無いゲームは、PATCH で declareAllAges: true を送ると申告を記録できます。公開設定とは関係なく、private のままでも送れます。記録が無いゲームを private から public / unlisted へ変えるときは必須です(公開設定と審査)。申告は一度記録したら変わらず、記録済みのゲームに送っても何も起きません。公開設定を上げない要求では、ほかのトークンや別の要求が同時に申告していても失敗せず、同じ要求のほかの変更もそのまま保存されます。private から上げる要求では、申告は公開設定の変更と一緒に保存され、別の要求が先に申告していたときは公開設定も変えずに 409 review.stateChanged になります。false を送っても記録は消えず、何も起きません。真偽値でなければ 400 になります。
streamingPolicy に表に無い値("Allowed" のような打ち間違いを含む)を送ると、エラーにはならず unspecified として保存されます。title / description / howToPlay / streamingPolicyNote は上限を超えた分が切り詰められます。description / howToPlay / streamingPolicyNote の改行は LF に揃い、制御文字(タブを含む)は空白に、行末の空白は削られます。応答の game で保存された値を確かめてください。
訳を書く
title・description・howToPlay は作品の既定の文面です。これとは別に、言語ごとの訳を POST と PATCH の localizations で書けます。プレイヤーの表示言語の訳があればそれを、無い言語と空の項目には既定の文面を出します。
curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"localizations": {
"en": { "title": "Cat Jump", "howToPlay": "Tap to jump." },
"ko": null
}
}'| localizations に送る値 | 内容 |
|---|---|
| キー | 言語。ja / en / ko / zh-Hans / zh-Hant / id / fil / vi / th のどれかを、この綴りのまま書く。en-US・zh-TW のような地域付きの形、zh-hans のような大文字小文字の違う形、ほかの言語は 400 |
{ "title", "description", "howToPlay" } | その言語の訳。送った項目だけを変え、送らなかった項目は今の訳を残す。上限と正規化は既定の文面と同じ |
null | その言語の訳をすべて消す |
項目に null か "" | その項目の訳を消す(既定の文面に戻る) |
応答と GET の localizations は、{ "en": { "title": "...", "description": "...", "how_to_play": "..." } } の形で、保存されている訳だけが入ります。遊び方のキーは how_to_play です。既定の文面と同じ訳は保存されないので、title と同じ文字列を en の title に送ると、en の title は消えます。
訳は今の値に重ねて保存します。読んでから保存するまでの間に、Studio やほかのトークンが同じゲームの訳か sourceLocale を変えていたときは、保存せずに 409 localizations.changed を返します。GET /api/games/:id で最新の訳を読んでからやり直してください。
既定の文面の言語
sourceLocale は、title・description・howToPlay を書いた言語です。値は localizations のキーと同じく ja / en / ko / zh-Hans / zh-Hant / id / fil / vi / th のどれかを、この綴りのまま送ります。null は未設定です。ほかの値(en-US・zh-hans など)は 400 です。POST で省略すると未設定、PATCH で省略すると今の値のまま、PATCH で null を送ると未設定に戻ります。localizations を送らない PATCH で今と同じ値を送ったときは、省略したときと同じです(毎回送っても、ほかの変更の保存には影響しません)。GET と応答の source_locale で今の値を確かめられます(未設定は null)。
指定したゲームでは、この言語の閲覧者に既定の文面を出し、ゲームの紹介ページはこの言語の版で検索に載ります。英語で書いたゲームは sourceLocale を en にしてください。未設定のゲーム(sourceLocale を送らずに作ったゲームを含む)は、既定の文面を日本語の版として扱い、ja を含むどの言語の訳も書けて、閲覧者の言語の訳があればそれを出します。
sourceLocale を指定したゲームは、その言語の訳を持てません。保存した後の localizations に sourceLocale の言語の訳が残る要求は、何も保存せずに 400 localizations.sourceLocale を返します。未設定から指定するときと、別の言語に変えるときに、その言語の訳が残っているときも同じです。既定と同じ文面か空の項目だけを送った言語は、正規化で落ちて残らないので通ります。その言語の訳を消す null は送れます。
既定の文面と訳を入れ替えるときは、1回の PATCH に新しい sourceLocale・その言語の既定の文面・新しい言語の訳を消す null・前の言語の文面を訳として送ります。既定の文面は3項目(title・description・howToPlay)をすべて送ってください。送らなかった項目は前の言語の文面のまま既定に残り、新しい言語のその項目の訳は null で消えます。前の言語の訳にも、3項目をすべて送ります。下の例は、日本語で書いて英語の訳を持つゲームを、英語の既定の文面と日本語の訳に入れ替えます。
curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"sourceLocale": "en",
"title": "Cat Jump",
"description": "Tap to jump through the gaps in the walls that keep coming. The farther you go, the faster it gets. Compare records on the leaderboard.",
"howToPlay": "Tap anywhere to make the cat jump a little, and hold to jump higher. Time your jumps to the gaps; hitting a wall ends the run.",
"localizations": {
"en": null,
"ja": {
"title": "ねこジャンプ",
"description": "タップで跳ぶだけのショートゲーム。迫ってくる壁のすき間をくぐり抜け、どこまで遠くへ進めるかを競います。進むほどスピードが上がり、壁の形も変わっていきます。ランキングで友だちと記録を比べたり、毎日のチャレンジでコインを集めたりできます。",
"howToPlay": "画面のどこかをタップすると、ねこが少しだけ跳びます。長押しすると高く跳べます。壁のすき間に合わせてタイミングよく跳び、壁にぶつかるとゲームオーバーです。ときどき出てくる魚を取るとシールドが付き、1回だけ壁に当たっても続けられます。"
}
}
}'公開設定と審査
privateへの変更はすぐに反映され、審査待ちがあれば取り消されます。unlistedへの変更は、審査を経ずにすぐに反映されます。審査待ちがあれば取り消されます。publicへの変更は、最新ビルドが審査済みならすぐに反映されます。そうでなければrequested_visibilityに希望が入り、review_statusがpendingになります。visibilityは、unlistedのゲームならunlistedのまま、承認済みのビルドを配信しているpublicのゲームならpublicのまま、それ以外はprivateのままです。publicのゲームが配信するのは、審査で承認されたビルドです。新しいビルドが審査を待つ間と差し戻された後も、承認済みのビルドの配信が続きます。- ビルドがまだ無いゲームは
publicにもunlistedにもできません(409review.buildRequired)。 - 素材の権利をまだ確認していないゲームを公開へ変えるときは、
confirmAssetRights: trueを一緒に送ります。無ければ403rights.confirmRequiredになります。 - 全年齢の申告の記録が無いゲームを
privateからpublic/unlistedへ変えるとき(公開の審査の申請を含む)は、declareAllAges: trueを一緒に送ります。無ければ403ageRating.declarationRequiredになり、同じ要求のほかの変更も保存されません。審査免除の作者と管理者、トークンからの変更も同じです。publicとunlistedの間の変更と、privateへの変更では求めません。 - ホールド中のゲームは公開設定を変えられません(
403hold.locked)。 - ホールド中のゲームで
descriptionかhowToPlay(どちらかの訳を含む)の内容を変えると、一般公開の審査に積まれます。 - 審査待ち(
review_statusがpending)のゲームでtitle・description・howToPlay・それらの訳・サムネイル・sourceUrlの内容を変えると、運営は新しい内容で審査し直します。審査の順番は、変えた時点で申請したものとして後ろへ回ります。 - 変更の途中で審査の状態が変わったときは
409review.stateChangedになります。最新の状態を読んでからやり直してください。
審査を飛ばせるのは、オーナー本人が運営の認めた審査免除の作者か管理者のときだけです。その場合はトークンからでも Studio と同じく即時に反映されます。共同制作者の立場では審査を飛ばせません。審査免除の作者の場合、運営が最後に差し戻したゲームは審査に回ります。全年齢の申告の記録が無いゲームの申請も、審査を飛ばさずに審査に回ります。
3. サムネイル
サムネイルは2段で上げます。まず POST /api/games か PATCH /api/games/:id にファイルの名前と大きさだけを送り、返ってきた mediaUploads の url へ画像そのものを PUT します。確定の呼び出しはありません。
サムネイルは露出面ごとに3種類あります。正方形の thumbnail は「お気に入りのゲーム」などに使う基本の1枚で、ホームの横長カード(オススメ・話題の新作・人気・特集棚)には 16:9 の thumbnailWide を出します。フィードではカードの形に合わせ、PC ブラウザなどでカードが横長のときは 16:9 の thumbnailWide、スマホなどで縦長のときは 9:16 の thumbnailTall を出します。16:9 と 9:16 は任意で、形に合う方が無ければその面でも正方形を使います。3種類とも GIF とアニメーション WebP を使え、その面でアニメーションします。
SIZE=$(wc -c < thumb.png)
curl -X PATCH "https://gamerush.jp/api/games/$GAME_ID" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"thumbnail\":{\"fileName\":\"thumb.png\",\"size\":$SIZE,\"contentType\":\"image/png\"}}" \
> patch.json
UPLOAD_URL=$(jq -r '.mediaUploads[] | select(.kind == "thumbnail") | .url' patch.json)
curl -X PUT "$UPLOAD_URL" --data-binary @thumb.png| フィールド | kind | 受け付ける形 |
|---|---|---|
thumbnail | thumbnail | png / jpg / webp / gif、1MB まで。これが無いと下の4つ(Small / Compact / Large / Og)も無視される |
thumbnailSmall | thumbnail-small | 長辺 512px の webp / jpg、1MB まで。GIF のときは無視 |
thumbnailCompact | thumbnail-compact | thumbnailSmall を長辺 288px に縮めたもの(一覧の小さな枠向け)。thumbnailSmall と同じ形式の webp / jpg、1MB まで。thumbnailSmall が無いか形式が違えば無視 |
thumbnailLarge | thumbnail-large | 長辺 1920px の webp / jpg、1MB まで。GIF のときは無視 |
thumbnailOg | thumbnail-og | SNS の共有カード用の静止 jpg、1MB まで。GIF と WebP のときだけ使い、png / jpg では無視 |
thumbnailWide | thumbnail-wide | 横長の 16:9(ホームのカードと、横長に表示したフィード)。推奨 1280×720 の png / jpg / webp / gif、1MB まで |
thumbnailTall | thumbnail-tall | 縦長の 9:16(縦長に表示したフィード)。推奨 1080×1920 の png / jpg / webp / gif、1MB まで |
- 各フィールドは
{ fileName, size, contentType }です。形式はfileNameの拡張子で決まります。 urlの期限は 1 時間です。切れたら同じPATCHをやり直して新しいurlを取ります。- ゲームのサムネイルの URL は
PATCHの時点で新しいものへ切り替わります。PUTを終えるまでは画像が出ないので、続けて上げてください。 thumbnailWide/thumbnailTallはthumbnailと独立しています。片方だけ送っても構いませんし、正方形を差し替えても 16:9・9:16 は残ります。- アニメーション WebP の
thumbnailにthumbnailSmallを送らなければ、一覧向けの縮小版をアニメーションを保ったままサーバが後から作ります。GIF と違いthumbnailSmall/thumbnailLargeは無視されず、送った派生はそれを使う面でそのまま出ます。 - 16:9・9:16 を外して正方形へ戻すときは、
PATCHにclearThumbnailWide: true/clearThumbnailTall: trueを送ります。同じ呼び出しでファイルも送った場合はファイルが優先されます。
4. ビルドのアップロード
ビルドは3段で上げます。権限はどれも builds:write で、最上位に grush.json を含むビルドでは leaderboards:write も要ります。Unity なら Editor 拡張 が同じ手順とプレイヤーの組み立てを持っているので、自分で書く必要はありません。
| 段 | API | 内容 |
|---|---|---|
| 1 | POST /api/games/:id/builds | ファイルの一覧を送り、ファイルごとの送り先を受け取る |
| 2 | PUT <uploadUrls[].url> | 各ファイルの中身をそのまま送る |
| 3 | POST /api/builds/:buildId/complete | 中身を検査して、ゲームの最新ビルドにする |
{
"engine": "godot",
"files": [
{ "path": "__grush-player.json", "size": 112 },
{ "path": "index.js", "size": 301224 },
{ "path": "index.wasm", "size": 35651584 },
{ "path": "index.pck", "size": 2097152 }
]
}curl -X POST "https://gamerush.jp/api/games/$GAME_ID/builds" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d @manifest.json > build.json
jq -c '.uploadUrls[]' build.json | while read -r ticket; do
path=$(echo "$ticket" | jq -r '.path')
url=$(echo "$ticket" | jq -r '.url')
curl -X PUT "$url" -H "If-None-Match: *" --data-binary @"build/$path"
done
BUILD_ID=$(jq -r '.build.id' build.json)
curl -X POST "https://gamerush.jp/api/builds/$BUILD_ID/complete" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'作成の応答は { build, uploadUrls, entryUrl } です。build は作ったビルド(id を complete に使う)、uploadUrls は送ったファイルごとの { path, key, url, headers }(path は一覧に書いた名前、key は保存先の識別子、url と headers は送り先)、entryUrl はこのビルドの入口の HTML の URL です。complete の 200 の応答は { build, entryUrl } で、build は ready になったビルドです。
ファイルの一覧で決まること
engineはunity/godot/gdevelop/phaser/webのどれかです。ほかの値はエラーにならず、null(エンジン未指定)で保存されます。- ルートに
index.htmlか、ロード設定の__grush-player.jsonのどちらか一方が要ります。無ければ400build.missingEntry、両方あれば400build.conflictingEntryです。HTML は圧縮せずに送ってください。ロード設定は 64KB までです。 - ファイル数は 2000 まで、合計は 50MB までです(目安は 15MB 以下で、30MB 以上は危険です)。
sizeはそのまま送るバイト数を書きます。 - 使えるファイルの種類は Studio からのアップロードと同じで、拡張子で決まります(大文字小文字は問わず、後ろに
.br/.gzが付いた名前は、その前の拡張子で決まります)。ほかの拡張子のファイルが1つでもあると、作成が400build.unsupportedExtension(params.pathに原因のファイル)になります。ソースマップ(.js.map)もこれに当たるので、含めないでください。 - Unity の
Build/x.wasm.brのように、書き出した時点で.br/.gzが付いたファイルはその名前のまま送ります。自分で圧縮したファイルを送るときは、元の名前のpathに"encoding": "gzip"か"encoding": "br"を添え、sizeは圧縮後の大きさにします。ただし HTML はencodingを付けても.gz/.brの名前でも受け付けず、400build.compressedHtmlになります。grush.jsonは"encoding": "br"を受け付けません(下)。 - 最上位の
grush.jsonはランキングの定義として読みます(書式は SDK ガイドのランキング)。トークンにleaderboards:writeが無ければ403です。grush.jsonは 64KB までで、圧縮しないか"encoding": "gzip"で送ります。"encoding": "br"は作成の時点で400build.leaderboardManifestCompressed、圧縮せずに送る 64KB 超のファイルは400build.leaderboardManifestTooLargeです。gzip で送ったものの大きさは展開してから確かめ、64KB を超えれば complete が422を返します。
使える拡張子は次のとおりです。.html・.js・.wasm・.data・.json・.png・.jpg・.jpeg・.gif・.bmp・.css・.unityweb・.pck・.ico・.svg・.webp・.mp3・.m4a・.aac・.ogg・.wav・.mp4・.txt・.csv・.xml・.yml・.yaml・.ttf・.woff・.woff2・.webmanifest・.bytes・.bundle・.assetbundle・.bin・.dat・.bank・.ress・.resource・.fnt・.atlas・.skel・.glsl・.frag・.vert・.tmx・.tsx・.tmj・.tsj・.otf・.webm・.ktx・.pvr・.ktx2・.basis・.glb・.ldtk
Studio の画面から上げて Unity か Godot と判別されたビルドと、Unity v1.14.0 以降の Editor 拡張から上げた Unity のビルドは、GameRush がプレイヤーを組み立て、ローディングバーと起動に要るファイルの優先読み込みを付けます。それより古い Editor 拡張と API から上げたビルドは判別を通らず、index.html を送ればそれがそのまま使われます。
Godot のビルドを API から GameRush のプレイヤーで起動するには、上の例のように index.html の代わりにロード設定を送ります。中身は次の形です。executable は .pck / .wasm / .js に共通の名前です。fileSizes は展開後の大きさで、省くとローディングバーが進みません。
{
"kind": "godot",
"executable": "index",
"fileSizes": { "index.wasm": 35651584, "index.pck": 2097152 }
}
ファイルを送る
uploadUrls[].headersに入っているヘッダーは、そのまま付けて送ってください(いまはIf-None-Match: *です)。- 同じファイルは1度しか書けません。2度目は
412になるので、送信済みとして扱って構いません。途中で止まったときは、残りのファイルだけ送り直せます。 urlの期限は 1 時間です。
完了させる
complete は、送ったファイルの大きさ・中身の形式・HTML の内容を検査してから、ゲームの最新ビルドに切り替えます。
| 応答 | 意味 | 次にすること |
|---|---|---|
| 200 | ビルドが ready になり、ゲームの最新ビルドになった | — |
| 403 | 最上位に grush.json を含むビルドで、トークンに leaderboards:write が無い。ビルドには触れない | leaderboards:write を持つトークンで呼ぶ |
409(details.missing 付き) | 送っていないファイルがある。アップロード中のビルドは失敗扱いになる | ビルドの作成からやり直す |
409(details なし、ゲームの状態が変わった) | アップロード中に、ほかの操作でゲームの状態が変わった | 同じ complete をもう一度呼ぶ |
409(details なし、ビルドが失敗済み・破棄済み) | 前の complete で既に失敗したか、ビルドが破棄された | ビルドの作成からやり直す |
| 422 | 中身の検査で弾かれた(params.path に原因のファイル)。アップロード中のビルドは消える | ファイルを直してから作成し直す |
422(code が build.leaderboardManifest で始まる) | grush.json を読めないか、反映できない宣言がある(下の表)。アップロード中のビルドは消える | grush.json を直してから作成し直す |
| 503 | 一時的に処理できなかったか、アップロードの機能を止めている(エラーの形) | Retry-After があればその秒数だけ待ってから、同じ complete をもう一度呼ぶ |
| `grush.json` の 422 の `code` | 原因 |
|---|---|
build.leaderboardManifestInvalidJson | JSON のオブジェクトとして読めない |
build.leaderboardManifestUnknownField | 知らない項目がある(params.field) |
build.leaderboardManifestInvalidField | 値が正しくない(params.field) |
build.leaderboardManifestDuplicateKey | key が重複している(params.key) |
build.leaderboardManifestTooMany | 定義が 21 個以上ある |
build.leaderboardManifestTooLarge | 64KB を超える |
build.leaderboardManifestSemanticsLocked | スコアが投稿済みの枠の sort・valueType・aggregation・period を変えようとした(params.key) |
build.leaderboardManifestLimit | すでにある枠と合わせて 1 ゲーム 20 個を超える |
grush.json を含むビルドの 200 の応答には leaderboards: { applied, unchanged, failed } が付きます。applied は作成か更新をした key、unchanged は同じ内容で何も書かなかった key です。検査の後に投稿が割り込むなどで書けなかった定義は、ビルドを最新にしたまま failed: [{ key, code }] に載ります。grush.json に書かなかった key の枠は、消えも止まりもしません。public のゲームで審査を待つビルドは、grush.json の検査だけを complete で行い、定義は審査で承認されて配信される時点で反映します。このときの応答には leaderboards の代わりに leaderboardsDeferred: true が付きます。
既に ready になったビルドへ complete をもう一度呼んで 400・409・422 が返ったときは、ビルドは ready のまま残り、配信も続きます。失敗扱いにも削除にもならないので、作成からやり直す必要はありません。
public のゲームに審査前のビルドを完了させると、ゲームは public のまま、新しいビルドが審査に積まれます(review_status が pending)。審査の間は前に承認されたビルドの配信が続き、承認されると新しいビルドに差し替わります。差し戻されたときは、新しいビルドは配信されず、承認済みのビルドの配信が続きます。新しいビルドは Studio の試遊で確かめられます。オーナー本人が運営の認めた審査免除の作者か管理者なら、審査を経ずにすぐ差し替わります。unlisted のゲームは審査を経ずに、unlisted のままビルドが差し替わります。
POST /api/games/:id/builds の本文に冪等キー operationId(1〜100 文字の文字列)を付けると、同じキーでの再送は2つ目のビルドを作らず、先に作ったビルドと出し直した uploadUrls を返します。応答が失われたときや、presigned URL の期限が切れて PUT が 403 になったときは、同じキーと同じ本文で作成を送り直し、返った URL で続きを送ります。キーはアカウントとゲームごとに区別し(同じアカウントのトークンと Studio で共有します)、24 時間保持します。先に作ったビルドが ready なら uploadUrls は空です。同じキーで本文が違えば 422(operation.bodyMismatch)、先の要求が終わっていなければ 409(operation.inProgress。少し待って同じキーで送り直します)、先に作ったビルドが消されたか失敗していれば 410(operation.gone)を返します。作成が途中で失敗したときは、本文を直して同じキーで送り直せます。operationId を付けない作成は再試行するたびに別のビルドを作るので、機械的に再試行しないでください。
5. ランキングの定義
ゲームから投稿するランキングの枠を宣言します。ゲーム側からの投稿と取得は SDK の役目で、ここにあるのは作者の手元から枠を管理する API です(SDK ガイドのランキング)。
API を使わずに、ビルドの最上位に置いた grush.json で同じ定義を宣言することもできます(書式は SDK ガイドのランキング、アップロードでの扱いは 4. ビルドのアップロード)。grush.json に書いた key の枠は、grush.json を含むビルドが最新になるたびにファイルの中身で書き換わります。public のゲームで審査を待つビルドの定義は、そのビルドが承認されて配信される時点で反映されます。ここの API で title・値域・enabled を変えても、そのようなビルドを次に上げたときにファイルの値へ戻ります。投稿のある枠の sort / valueType / aggregation / period を API で変えたときは、grush.json も合わせてください。食い違ったままのビルドは 422 で失敗します。
| API | 権限 | 内容 |
|---|---|---|
GET /api/games/:id/leaderboards | leaderboards:read | 定義の一覧(停止中も含む) |
PUT /api/games/:id/leaderboards/:key | leaderboards:write | key での冪等な作成・更新。定義を丸ごと置き換える。スクリプトから流すならこれ |
POST /api/games/:id/leaderboards | leaderboards:write | 作成。同じ key があれば 409 |
PATCH /api/games/:id/leaderboards/:leaderboardId | leaderboards:write | 送ったフィールドだけ更新 |
DELETE /api/games/:id/leaderboards/:leaderboardId | leaderboards:write | 削除。投稿済みのエントリも消える |
GET /api/games/:id/leaderboards/anomalies | leaderboards:read | 不審な投稿として印が付いたエントリの一覧 |
| フィールド | POST / PUT | 値 |
|---|---|---|
key | POST は必須。PUT はパスで渡す(本文に書くならパスと同じ値) | 英数字と . _ : - で 64 文字まで |
title | 必須 | 60 文字まで。改行は空白になる |
sort | 必須 | desc(大きいほど上)/ asc |
valueType | 必須 | int / float / duration_ms |
aggregation | 必須 | best / last / sum |
period | 必須 | all_time / daily / weekly / monthly |
minValue / maxValue | 任意(投稿を受けるには要る) | 受け付ける値域。両方そろえて指定し、minValue は maxValue より小さくする(そうでなければ 400)。省くと値域なし |
enabled | 任意 | false で投稿を止める。省くと true |
値域を宣言していない枠は、ゲームからの投稿をすべて拒みます。投稿を受ける枠には、必ず minValue と maxValue を指定してください。
PUT は、本文の内容で定義を丸ごと置き換えます。省いたフィールドは今の値を残さず、minValue / maxValue は null(値域なし)に、enabled は true に戻ります。止めている枠や値域を持つ枠を PUT で流すときは、enabled: false や minValue / maxValue も毎回送ってください。一部のフィールドだけを変えるなら PATCH を使います。PATCH で値域を変えるときも、minValue と maxValue を両方送ります。
DELETE は枠と一緒に、その枠に投稿されたエントリもすべて消します。元に戻せません。投稿を止めるだけなら PATCH か PUT で enabled: false にしてください。
一覧の応答は { leaderboards: [...] }、作成・PUT・PATCH の応答は { leaderboard }、DELETE の応答は { deleted: true } です。定義には上の表のフィールドに加えて id・gameId・createdAt・updatedAt が入ります。PATCH と DELETE の :leaderboardId は、この id です(key ではありません)。
anomalies の応答は { anomalies: [...] } で、印の新しい順に 200 件までです。各項目は entryId・leaderboardKey・leaderboardTitle・pseudoId(プレイヤーの仮名の id)・value・status(visible / hidden)・reason(印を付けた理由)・flaggedAt を持ちます。印は記録だけで、エントリは自動では隠れません。
1ゲームあたり 20 枠までです。投稿が1件でもある枠では sort / valueType / aggregation / period を変えられません(409)。コマンドの例と注意は SDK ガイドの API トークン にあります。
6. アナリティクス
GET /api/analytics/games/:id で、Studio のアナリティクス画面の「概要」と「パフォーマンス」と同じ数字をゲーム1本ぶん取れます。「プレイ時間と離脱」の数字は下の GET /api/analytics/games/:id/engagement で、「ファネル」の数字は GET /api/analytics/games/:id/funnels で、「カスタムイベント」の数字は GET /api/analytics/games/:id/events で、「エコノミー」の数字は GET /api/analytics/games/:id/economy で取ります。権限はどれも analytics:read です。
curl "https://gamerush.jp/api/analytics/games/$GAME_ID?period=7d" \
-H "Authorization: Bearer $GRUSH_TOKEN"period は 24h / 7d / 28d(既定)/ 90d / all です。
| フィールド | 内容 |
|---|---|
game | validPlays(有効プレイ数)・uniquePlayers・totalSessions・avgDurationSec・opens・skips・likeCount・commentCount・retention(翌日の再訪率と 7 日後の再訪率) |
series | bucket ごとの plays / sessions / durationSec。期間に応じて1時間・6時間・1日で区切る |
performance | 端末で測った load(ロード時間。samples・players・avgMs・minMs・p95Ms(95% の読み込みが収まる時間)・outcomePlayers・outcomes・abandoned・abandonRate(途中離脱率))と fps(フレームレート。sessions・players・sampledSec・avgFps・p10Fps・lowFpsShare)。標本が少ないうちは件数だけを返し、各値が null になる。load は、ロード時間の人数(players)が 3 人未満なら avgMs・minMs・p95Ms を、途中離脱の人数(outcomePlayers)が 3 人未満なら outcomes・abandoned・abandonRate を null にする。load と fps は、集計に失敗すると source が failed か unavailable になり、ほかの値を持たない |
surfaces | 面ごとの数。{ source, feed, home, external, feature, search, browseSince, series } の形で、feed は landings(着地数)・plays(1秒以上遊ばれた数)・minutePlays(1分以上遊ばれた数)・validPlays、home は clicks(クリック数)・plays・minutePlays・validPlays・impressions(カードの表示数。取れないときは null)・impressionsSince(表示数を記録し始めた時刻。まだ記録が無ければ null)、external(プラットフォームの外から作品に直接着地した回)は landings・plays・minutePlays・validPlays と入口ごとの byEntry(share(シェアリンク)/ sharePage(ゲームが作った共有のページ。集計できないときは null)/ direct / embed(ほかのサイトに置いた埋め込み。plays・minutePlays も持つ。集計できないときは null)/ other ごとの landings・validPlays)、feature(特集タブ)と search(検索の結果)はどちらも impressions(カードの表示数)・impressionsSince(その面の表示数を記録し始めた時刻。まだ記録が無ければ null)・clicks(その面から遊び始めた数)・validPlays・countedClicks(clicks のうち impressionsSince より後に始まった数)で、集計できないときは null。feed・home・external はどれも、フィードの閲覧モードの browseViews(カードが画面に出た数)・browseClicks(そこからプレイへ移った数)・clickedValidPlays(そのうち有効プレイになった数)も持つ。browseSince は閲覧モードの表示を記録し始めた時刻で、まだ記録が無ければ null。series は bucket ごとの feedLandings・feedValidPlays・homeClicks・homeValidPlays・homeImpressions・externalLandings・externalValidPlays・homePlays・feedPlays・externalPlays・homeMinutePlays・feedMinutePlays・externalMinutePlays と、面ごとの homeBrowseViews・homeBrowseClicks・homeClickedValidPlays・feedBrowseViews・feedBrowseClicks・feedClickedValidPlays・externalBrowseViews・externalBrowseClicks・externalClickedValidPlays で、記録のある区切りだけを持つ。閲覧モードの数と plays・minutePlays は、集計できないときは null。source が unavailable / failed のときは数を返さない |
engagementSeries | { source, series, d1Days } の形で、series は bucket ごとの uniquePlayers / opens / likes / comments / follows(その作品の画面から付いたフォローの数。集計の無い DB では null)。d1Days は初めにプレイした UTC の日(day)ごとの 1日後 リテンションの対象の人日(cohort)と、そのうち翌日も遊んだ人日(retained)で、翌日が終わった日だけを持ち、集計の無い DB では null。source が unavailable / failed のときは series と d1Days を持たない |
period / generatedAt | 集計の期間と、集計した時刻 |
ホーム・特集タブ・検索の表示数は記録を始めた時刻から後だけを数えます。期間の始まりが impressionsSince より前のときは、表示数は期間の一部しか数えておらず、期間の全部を数えたクリック数と割り合わせると率が高く出ます。特集タブと検索の CTR は countedClicks を表示数で割ってください。
閲覧モードの browseViews・browseClicks・clickedValidPlays も、記録を始めた時刻(browseSince)から後だけを数えます。期間の始まりが browseSince より前のときは、3つとも期間の一部しか数えていません。数はどれもセッションの開始時刻で期間と区切りを切るので、browseClicks は browseViews を、clickedValidPlays は browseClicks を超えません。
有効プレイは、遊び始めてから 1 分(60 秒)以上続いたプレイだけを数えます。ユニークプレイヤー数は 10 秒以上遊んだ人を数えます。ロード時間の数字は ゲームの最適化ガイド の効き目を確かめるのに使えます。
GET /api/analytics/games/:id/engagement で、Studio の「プレイ時間と離脱」と同じ数字を取れます。プレイヤーがどこで遊ぶのをやめるかを、経過時間ごとの割合で返します。period は上と同じです。
curl "https://gamerush.jp/api/analytics/games/$GAME_ID/engagement?period=7d" \
-H "Authorization: Bearer $GRUSH_TOKEN"| フィールド | 内容 |
|---|---|
engagement | sessions・firstSessions・players と、sessionCurve・firstSessionCurve・playerCurve(edgesSec の各秒の時点でまだ遊んでいた割合)・p50Sec / p75Sec / p90Sec(1回のプレイ時間)・avgPlayerSec・funnel(opened → revealed → played1s → played10s)。標本が少ないうちは件数だけを返し、値は null |
series | { source, points } の形で、points は bucket ごとの sessions / players / durationSec / medianSec。区切りは上の series と同じ |
edgesSec | 曲線の横軸の秒。60 分以上は最後の点にまとめる |
scope | 数えた範囲。作者・共同制作者・運営のプレイは含まない |
曲線・分位・平均と series が数えるのは、プレイモードでゲームの表示を待ち始め、その回のうちに読み込みが終わった回だけです。待ち始めた後で閲覧モードへ戻った回は入り、閲覧モードで通り過ぎただけの回は入りません。funnel.opened だけは、表示の前に離れた回も数えます。engagement と series は、集計に失敗すると source が failed か unavailable になり、ほかの値(series では points)を持ちません。
GET /api/analytics/games/:id/funnels で、Studio の「ファネル」と同じ数字を取れます。ゲームが SDK から送ったファネルのステップを、ステップごとの到達と離脱で返します。period は上と同じです。funnel は onboarding か recurring: に続けたファネルの名前で、省くか、一覧に無い値なら一覧の先頭のファネルを返します。
curl "https://gamerush.jp/api/analytics/games/$GAME_ID/funnels?period=28d&funnel=recurring:Shop" \
-H "Authorization: Bearer $GRUSH_TOKEN"| フィールド | 内容 |
|---|---|
list | hasEvents(期間を問わず、数える範囲のイベントが届いたことがあるか)・hasAnyEvents(作者・共同制作者・運営のものも含めて届いたことがあるか)・funnels(funnel・units・players)・other(一覧に入れなかったファネルの funnels と players。無ければ null) |
report | 選んだファネルの funnel・units・players・steps・biggestDropStep(前のステップからの率がいちばん低いステップ)。期間に始めた回のあるファネルが無ければ source が none |
playersBasis | 人数の数え方。period は期間の中で重なりを除いた人数、peak は期間の人数の下限(下の注記)。recurring のファネルの players に効き、onboarding は peak でも重なりの無い人数 |
report.steps | step・name・reached・reachedPlayers・fromStartRate・fromPreviousRate・dropped。onboarding は playSec(届いたときの累計プレイ秒の p25 / p50 / p75 / p90)と medianDays、recurring は medianElapsedSec(回を始めてからの秒)。分位と中央値は人ごとの値の上で取る |
scope | 数えた範囲。作者・共同制作者・運営のイベントは含まない |
collecting | ゲームからの分析イベントを今保存しているか。false の間は送ったイベントが残らない |
onboarding は人で、recurring は人と funnelSessionId の組(省いたステップはプレイセッション)を1回として数えます。期間の中で始めた回だけを数え、その回のステップは今までの到達をすべて数えます。先のステップに届いた回は、飛ばした手前のステップにも届いたと数えます。ファネルの名前は人数の多い上位 10 個まで返し、3人未満のファネルは other にまとめます。3人未満しか送っていないステップ名は null に、到達した人が5人未満のステップの時間は null になります。list と report は、集計に失敗すると source が failed か unavailable になります。
playersBasis が peak のとき、期間の人数(players など)は重なりを除いた実際の人数ではなく、その下限です。期間の中で人数のいちばん多い日か、期間にまるごと入る月の人数の大きいほうを出します。実際の人数はこれ以上で、人数で割った値は実際より大きく出ます。どちらの数え方になるかは期間で変わります。
GET /api/analytics/games/:id/events で、Studio の「カスタムイベント」と同じ数字を取れます。ゲームが SDK から送ったカスタムイベントを、イベント名ごとの指標・推移・custom field ごとの内訳で返します。period は上と同じです。event はイベント名で、省くか、一覧に無い値なら一覧の先頭のイベントを返します。field は内訳に使う custom field のキーで、省くか、選べないキーなら内訳を返しません。
curl "https://gamerush.jp/api/analytics/games/$GAME_ID/events?period=28d&event=level_clear&field=stage" \
-H "Authorization: Bearer $GRUSH_TOKEN"| フィールド | 内容 |
|---|---|
list | hasEvents・hasAnyEvents(funnels と同じ)・events(key・count・players)・other(一覧に入れなかったイベント名の events・count・players。無ければ null) |
report | 選んだイベントの event・totals・series(bucket ごとの指標)・fields(内訳に選べるキー。人数の多い上位 20 個まで)・breakdown。名前を出せるイベントが期間に無ければ source が none |
playersBasis | 人数の数え方。funnels と同じ。peak のときは、期間の totals と内訳の行の perPlayer が null になる |
指標 | count(回数)・sum(value の合計)・players(人数)・avg・min・max(人ごとの value の平均の、平均・最小・最大)・perPlayer(合計を人数で割った値) |
report.breakdown | field・values(value と指標)・other(values に入れなかった値をまとめた指標)・otherValues(その値の種類の数)・unset(そのキーを持たないイベントの指標) |
scope | 数えた範囲。作者・共同制作者・運営のイベントは含まない |
collecting | ゲームからの分析イベントを今保存しているか。false の間は送ったイベントが残らない |
期間の中に送られたイベントを数えます。イベント名は人数の多い上位 100 個まで返し、3人未満のイベント名は other にまとめます。custom field のキーと値も3人未満のものは名前を出さず、値は上位 20 個まで返して残りを breakdown.other にまとめます。sum・avg・min・max・perPlayer は、対象の人数が5人未満なら null になります。推移の区切りと内訳の行(other を含む)も、それぞれの人数で同じです。期間の sum から見えている区切りや行の sum を引いて隠した値が戻るときは、人数のいちばん少ない区切りや行の sum と perPlayer も null にします。list と report は、集計に失敗すると source が failed か unavailable になります。
GET /api/analytics/games/:id/economy で、Studio の「エコノミー」と同じ数字を取れます。ゲームが SDK から送った通貨の入手(source)と消費(sink)を、通貨ごとの合計・日ごとの推移・所持・内訳で返します。period は上と同じです。currency は通貨の名前で、省くか、一覧に無い値なら人数のいちばん多い通貨を返します。
curl "https://gamerush.jp/api/analytics/games/$GAME_ID/economy?period=28d¤cy=Gold" \
-H "Authorization: Bearer $GRUSH_TOKEN"| フィールド | 内容 |
|---|---|
list | hasEvents・hasAnyEvents(funnels と同じ)・currencies(currency・players)・other(一覧に入れなかった通貨の currencies と players。無ければ null) |
report | 選んだ通貨の currency・players・sourcePlayers・sinkPlayers・totals(source・sink・net)・latestBalance(人ごとの期間の中の最後の所持の p50 / p90)・days・breakdown。期間に行のある通貨が無ければ source が none |
playersBasis | 人数の数え方。funnels と同じ |
report.days | UTC の日ごとの day・source・sink・net・players・sourcePlayers・sinkPlayers・balanceAvg(人ごとのその日の最後の所持の平均)。行の無い日は players が 0 で、量は 0、balanceAvg は null。期間を区切ると、最初の日は期間の始まりの時刻から後だけを数える |
report.breakdown | transactionType と itemSku のそれぞれに、source と sink ごとの items(name・amount・players)と other(names・amount・players)。品目を送らなかった行の name は null |
scope | 数えた範囲。作者・共同制作者・運営のイベントは含まない |
collecting | funnels と同じ |
量はどれも正の値で、net は入手から消費を引いた値です。量と所持はゲームが送った値のままで、GameRush は確かめません。通貨は人数の多い上位 10 個まで、取引の種類と品目は入手と消費のそれぞれで人数の多い上位 20 個まで返し、3人未満の名前は other にまとめます。latestBalance は人数が5人未満なら null、balanceAvg はその日の人数が5人未満なら null です。量(totals・days の source / sink・内訳の amount)も、入手(消費)した人が5人未満なら null で、net は入手と消費の両方を出せるときだけ値を持ちます。隠した量を同じ応答の合計から引き算で戻せないよう、和の関係(期間の合計 ↔ days、期間の合計 ↔ 内訳の行と other)の中で隠した値が1つだけになるときは、人数が最小のほかの値も null にします。期間の違う2つの応答の差からは戻せることがあります。list と report は、集計に失敗すると source が failed か unavailable になります。
7. アイテムの販売
ゲームの中で売るアイテム(買い切り)の商品を、作者の手元から登録・管理する API です。
使えるのは、自分がオーナーか承諾済みの共同制作者のゲームです。ゲームを売れるかはオーナーで決まり、運営がオーナーの販売を開いていないゲームと、オーナーかあなたのアカウントが止められているときは 403(shop.notEnabled)になります。
商品を足す・名前や価格を変える・販売を再開するには、オーナーが Studio のゲームの「アイテム販売」で、販売に関する取り決めの今の版に同意しておく必要があります。共同制作者が呼んでも、見るのはオーナーの同意です。同意していないと 403(shop.agreementRequired)になります。同意は API キーではできません。一覧を読むことと、active: false だけを送って販売をやめることは、同意していなくてもできます。
| API | 権限 | 内容 |
|---|---|---|
GET /api/games/:id/shop/catalog | shop:write | 商品の一覧(販売をやめた商品も含む) |
POST /api/games/:id/shop/catalog | shop:write | 商品を足す。成功は 201。同じ sku があれば 409(shop.skuTaken) |
PATCH /api/games/:id/shop/catalog/:sku | shop:write | 送ったフィールドだけ更新。sku は変えられない。無い商品は 404 |
GET /api/games/:id/shop/revenue-split | shop:write | 収益の分け方(作者の取り分を、オーナーと共同制作者で分ける割合)。共同制作者には自分の割合だけを返す |
PUT /api/games/:id/shop/revenue-split | Studio のログインだけ | 分け方を変える。オーナーだけが Studio のゲームの「アイテム販売」で行い、API キーでは scope によらず 403 |
curl -X POST "https://gamerush.jp/api/games/$GAME_ID/shop/catalog" \
-H "Authorization: Bearer $GRUSH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"sku":"sword","name":"剣","priceJpy":500}'| フィールド | POST | PATCH | 値 |
|---|---|---|---|
sku | 必須 | パスで渡す | 英小文字・数字と _ . - で 64 文字まで。先頭は英小文字か数字。ゲームの中でアイテムを見分ける値 |
name | 必須 | 任意 | 1〜30 文字。改行は空白になる |
priceJpy | 必須 | 任意 | 税込みの円。100〜10000 の整数 |
active | — | 任意 | false で販売をやめる。足した商品は販売中から始まる |
商品は消せません。売るのをやめるときは PATCH で active: false にしてください。買われたアイテムは、販売をやめた後もプレイヤーの手元に残ります。
一覧の応答は { products: [...] }、作成と PATCH の応答は { product } です。商品は上の表のフィールドに加えて productId・createdAt・updatedAt を持ちます。本文は 4KB までで、超えると 413 です。
運営が販売の機能を止めている間は、どれも 503(service.featureDisabled、params.feature が shop)になります。
8. 自分のツールからトークンを取る
作者に Studio でトークンを発行して貼ってもらう代わりに、ブラウザで承認してもらって自分のツールがトークンを受け取る形も取れます(RFC 8252 のループバック + PKCE)。Unity の Editor 拡張はこの形です。
- ツールが手元で
http://127.0.0.1:<port>の HTTP サーバを立て、code_verifier(A-Za-z0-9と._~-だけからなる 43〜128 文字のランダムな文字列)を作る - ブラウザで下の URL を開く。作者がログインして内容を確かめ、承認ボタンを押す
- ブラウザが
redirect_uri?code=…&state=…へ戻ってくる。stateが送ったものと同じか確かめる exchangeにcodeとcode_verifierを送り、トークンを受け取る
https://gamerush.jp/studio/authorize
?redirect_uri=http://127.0.0.1:53682
&code_challenge=<base64url(sha256(code_verifier))>
&code_challenge_method=S256
&client_name=My%20Build%20Tool
&scopes=games:read,builds:write
&state=<ランダムな値>curl -X POST "https://gamerush.jp/api/api-token-authorizations/exchange" \
-H "Content-Type: application/json" \
-d '{"code":"<戻ってきた code>","codeVerifier":"<code_verifier>","redirectUri":"http://127.0.0.1:53682"}'redirect_uriはhttp://127.0.0.1:<port>/http://localhost:<port>/http://[::1]:<port>だけです。クエリもフラグメントも付けられません。code_challenge_methodはS256だけです。scopesはカンマ区切りです。game_idsにゲーム ID をカンマ区切りで渡すと、トークンの対象をそのゲームに絞れます。50 件までで、games:createとは一緒に使えません。stateは任意で、200 文字までです。200 文字を超えたstateはエラーにならずに捨てられ、ブラウザはstateを付けずに戻ってくるので、ツールの側の照合が失敗します。client_nameは承認画面と Studio のトークン一覧に出ます。60 文字を超えた分は切り詰められ、改行と制御文字は空白になります。codeはワンタイムで 5 分です。code_verifierかredirectUriが合わない交換はcodeを消費しないので、5 分以内なら正しい値でexchangeをやり直せます。exchangeの失敗は、codeの期限切れ・使用済み・code_verifierの不一致・形の誤りのどれでも、400Invalid authorization code.です。- 応答は
{ token, secret }で、secretがトークンの本体です。有効期限は 90 日です。有効なトークンが 20 本あると409になります。このときもcodeは消費されないので、Studio でトークンを1本失効させてから、5 分以内なら同じcodeでexchangeをやり直せます。