App Store Server API(Storekit)¶
この機能は Apple のアプリ内課金API(App Store Server API)を XG が代理実行するものです。(以下、本機能と呼びます)
本機能をご利用いただくことで、App Store の『アプリ内課金キー』の発行手続きや管理運用から解放され、安全かつ効率的に App Store Server API を実行できます。
はじめに¶
本機能が解決する課題¶
従来、App Store Server API を利用するためには『アプリ内課金キー』の発行とセキュアな管理が不可欠でした。
しかしながら、当社からキーをお渡しする現状の運用では以下の課題が生じていました。
当社の管理が及ばない状況下における『アプリ内課金キー』の取り扱いリスク
当社の『アプリ内課金キー』払い出しと管理運用コスト
新規タイトル開発に対する『アプリ内課金キー』不足の懸念
本機能はこれらの課題を解決し、安全かつ効率的な App Store Server API 利用を目的としています。
利用者¶
ターゲット |
説明 |
|
|---|---|---|
メインターゲット |
XG のゲーム内通貨管理機能を利用しないが App Store Server API を実行する必要があるタイトル |
|
サブターゲット |
通常の XG 利用者。本機能の利用も可能 |
ワークフロー¶
本機能の利用開始フロー¶
メインターゲット利用者が対象です。
本ゲートウェイ機能を通して App Store Server API を実行するフロー¶
本機能を利用(実行)するには¶
XG API の認証処理で実行可能です。
導入 および APIの認証処理について を参照し、必要な準備・処理を行ってください。
注意点¶
本機能は App Store Server API を代理実行し、結果をレスポンスします。
レスポンス構造は本機能特有のものになっていますので、後述の APIレスポンス例 を参考に必要な情報を取り出してください。
API一覧¶
機能 |
利用シーン |
|
|---|---|---|
App Store Server APIのGETリクエストを呼び出す時 |
||
App Store Server APIのPOSTリクエストを呼び出す時 |
||
App Store Server APIのPUTリクエストを呼び出す時 |
GET¶
App Store 本番環境¶
GET /storekit/{path}
App Store Sandbox環境¶
GET /storekit-sandbox/{path}
App Storeの本番環境・Sandbox環境に対してApp Store Server APIの GETリクエスト を実行します。
POST¶
App Store 本番環境¶
POST /storekit/{path}
App Store Sandbox環境¶
POST /storekit-sandbox/{path}
App Storeの本番環境・Sandbox環境に対してApp Store Server APIの POSTリクエスト を実行します。
PUT¶
App Store 本番環境¶
PUT /storekit/{path}
App Store Sandbox環境¶
PUT /storekit-sandbox/{path}
App Storeの本番環境・Sandbox環境に対してApp Store Server APIの PUTリクエスト を実行します。
APIリクエスト¶
リクエストボディ¶
App Store Server APIで指定されているリクエストボディを指定してリクエストを送信します。
クエリパラメーター¶
App Store Server APIで指定されているクエリパラメーターを指定してリクエストを送信します。
エンドポイント¶
App Store Server APIのエンドポイントの https://api.storekit.itunes.apple.com/ 以降を指定してリクエストを送信します。
（例） Get Transaction Info の場合¶
XG APIのエンドポイントの {path} に v1/store/transactions/{transactionId} を指定してリクエストを送信します。
App Store Server APIのエンドポイント
・App Store 本番環境
https://api.storekit.itunes.apple.com/v1/store/transactions/{transactionId}
・App Store Sandbox環境
https://api.storekit-sandbox.itunes.apple.com/inApps/v2/history/{transactionId}
XG APIのエンドポイント
・App Store 本番環境
https://<XG_BASE_URL>/storekit/{path}
・App Store Sandbox環境
https://<XG_BASE_URL>/storekit-sandbox/{path}
APIレスポンス例¶
正常系（XG処理成功 & App Store Server API成功）¶
App Store Server APIのレスポンスボディ・レスポンスヘッダー・httpStatusを返します。
（例） Get Transaction Info の場合¶
以下のようなレスポンスを返します。
{
"external": {
"body": { // App Store Server APIのレスポンスボディ
"signedTransactionInfo": "eyJhbGciOiJ****************"
},
"header": { // App Store Server APIのレスポンスヘッダー
"Content-Length": "64",
"Content-Type": "application/json",
"Date": "Fri, 04 Oct 2024 03:58:39 GMT"
},
"status": 200 // App Store Server APIのhttpStatus
}
}
正常系（XG処理成功 & App Store Server API失敗）¶
App Store Server APIでエラーになった場合でも、XGのhttpStatusが200のレスポンスを返します。
レスポンスの external にはApp Store Server APIのエラーレスポンスの内容が含まれます。
（例） Get Transaction Info でNotFoundエラーになった場合¶
以下のようなレスポンスを返します。
{
"error": {
"status": 200,
"code": "appstoreserverapi_error",
"title": "App Store Server APIで実行時エラーが発生しました。",
"detail": "App Store Server APIで実行時エラーが発生しました。"
},
"external": {
"status": 400,
"body": {
"errorCode": 4040010,
"errorMessage": "Transaction id not found."
},
"header": {
"Content-Length": "64",
"Content-Type": "application/json",
"Date": "Fri, 04 Oct 2024 03:58:39 GMT"
}
}
}
異常系（XG処理失敗 & App Store Server API無実行）¶
App Store Server APIの呼び出し前にXGの処理でエラーになった場合は、httpStatusは400系または500系でエラーレスポンスを返します。
エラーレスポンスのエラーコードは エラーコード一覧表 を参照してください。
注釈
本APIではApp Store Server APIがエラーになった場合でもXGはhttpStatusが200のレスポンスを返します。 そのため、 エラーコード一覧表 のApp Store Server APIのエラーコードのエラーレスポンスを返すことはありません。
（例）XGの認証エラーになった場合¶
以下のようなエラーレスポンスを返します。
{
"error": {
"status": 401,
"code": "authentication_failed",
"title": "認証エラー。",
"detail": "クレームフォーマットが違います"
}
}