Overview

Version information

Version : 1.0.0

URI scheme

Host : api.avatarplay3d.com
Schemes : HTTPS

Consumes

  • application/x-www-form-urlencoded

Produces

  • application/json

Paths

POST /v1/AccessToken

Description

アクセストークンAPI。付与トークンを渡し、アクセストークンとアバターIDを取得します。アバターIDを自社アプリのユーザと紐づけて、他のAPIで利用してください。接続開始時にゲストユーザのアバターIDを指定している場合、アップグレード処理も実行されます。RESTful APIのみを利用している場合、ここで得られたアクセストークンは破棄して問題ありません。

Parameters

Type Name Description Schema

Query

avatarId
optional

アップグレードの場合、ゲストとして割り振ったアバターID。アップグレードする場合は必ず指定してください。接続開始時に指定した値と一致する必要があります。

integer (int64)

Query

codeVerifier
required

接続開始時にcodeChallengeの生成で利用したcodeVerifier。Example: 4hmLHty5K6P…

string

Query

redirectUri
required

接続開始時に指定したリダイレクトURI。Example: https://example.com/oauth_callback

string

Query

requestDate
required

接続開始時にcodeChallengeの生成で利用したリクエスト日時。Example: 1552356284

integer (int64)

Query

scope
required

接続開始時に指定したスコープ。Example: AvatarLoad,ItemGrant

string

Query

token
required

redirectUri経由で受け取ったtokenパラメータの値をそのまま指定します。Example: veneh5On7MW…

string

Responses

HTTP Code Description Schema

200

成功

default

エラー

GET /v1/Avatar/{avatarId}

Description

アバター取得API。ひとつのアバターIDを指定して、アバター画像のURLなどを取得するAPIです。複数のアバター画像を取得するには、Avatars API を利用します。この API のレスポンスは、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

エラー

POST /v1/Avatar/{avatarId}/Items

Description

アイテム付与API。指定したアバターIDを持つユーザに、指定したアイテムを付与します。前提として、アイテム付与の権限を持つアクセストークンが有効となっている必要があります。デフォルトの動作では、付与アイテムの中に既に所持済みのアイテムが含まれていた場合、未所持のアイテムのみを付与して処理を正常終了します。個々のアイテムが付与されたかどうかは返り値のItemResultで確認できます。この動作は、failIfOwnedItemExists パラメータに真を指定することで変更できます。

Parameters

Type Name Description Schema

Path

avatarId
required

アバターID

integer (int64)

Query

failIfOwnedItemExists
optional

付与アイテムの中に一つでも所持アイテムが含まれている場合、全ての処理を失敗させる場合は真。デフォルトは偽。

boolean

Query

gachaSessionId
optional

UI Kit のガチャ経由の場合、セッションIDを指定します。セッションが削除され、再利用できなくなります。初回無料アイテムや初回限定価格が設定されている場合は必須。

string

Query

itemId
required

アイテムID。アプリが利用可能なアイテムとして登録されている必要があります。最大10個のアイテムIDを指定できます。

< integer (int64) > array(multi)

Query

shopSessionId
optional

UI Kit のショップ経由の場合、セッションIDを指定します。セッションが削除され、再利用できなくなります。

string

Responses

HTTP Code Description Schema

200

成功

default

エラー

GET /v1/Avatars

Description

複数のアバター取得API。内容は /v1/Avatar/{avatarId} と同じです。この API のレスポンスも、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Query

avatarId
required

アバターID。最低1つ指定する必要があり、最大50個まで指定できます。個別のアバター画像の取得は失敗する可能性があり、取得に失敗したアバターIDが含まれていた場合も、全体のレスポンスとしては正常(200)を返します。個々のアバターIDのステータスは、statusプロパティで確認できます。

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功。アバター画像のURLリストを返します。

default

エラー

GET /v1/Echo

Description

与えたメッセージを出力するだけのテスト用のAPIです。認証の動作確認などに利用してください。

Parameters

Type Name Description Schema

Query

message
optional

出力するメッセージ

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

POST /v1/Gacha/Session

Description

ガチャセッションを作成します。作成した段階で、このセッションで出現するアイテムが確定します。出現アイテムの情報は、アイテム付与が完了するまでエンドユーザがアクセスできない場所に一時的に保存しておきます。初回無料または初回限定価格が適用される場合も、セッション作成時点で適用が確定します(このセッションを、初回のセッションと呼びます)。初回のセッションを複数作成することも可能ですが、初回のセッションのアイテム付与が成功するのは1ユーザ1ガチャにつき1回までです。アイテム付与 API では gachaSessionId で初回のセッションの検証を行うため、必ず指定するようにしてください。同一ユーザ、同一ガチャのセッション作成は1秒以上間隔を空ける必要があります。セッションの作成とそのセッションのアイテム付与は同時に実行しないようにします。例えば「ガチャのトップ画面」「ガチャの演出画面」「ガチャの完了画面」という画面遷移の場合、「ガチャの演出画面」でセッションを作成し、「ガチャの完了画面」でアイテム付与するようにします。

Parameters

Type Name Description Schema

Query

avatarId
required

アバターID

integer (int64)

Query

gachaId
required

ガチャID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Gacha/Session

Description

UI Kit のガチャのセッション情報を取得するためのAPIです。ガチャ購入確認画面を構成する際に利用します。ここで取得したアイテムがガチャから引き当てられたアイテムとなるため、サーバに一時保存しておき、購入完了時にアイテム付与します。アイテム付与APIに引き渡したセッションはすぐに破棄されますが、アイテム付与APIの実行と同時ではなく、数秒程度のタイムラグが発生することがあります。

Parameters

Type Name Description Schema

Query

avatarId
required

自社アプリ側で認証できたユーザのアバターID

integer (int64)

Query

gachaSessionId
required

ガチャセッションID。購入確認画面のURLに追加されたパラメータから取得できます。

string

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Gacha/{gachaId}

Description

デベロッパーコンソールで設定した、ガチャの基本データとアイテムの情報を取得します。アバターIDをパラメータで渡した場合、ガチャを回したことのあるユーザかどうかの判定結果と各アイテムの所持状況も取得できます。タイマーも有効となるため、指定した avatarId に設定されている日時に販売中でない場合はエラーが返ります。

Parameters

Type Name Description Schema

Path

gachaId
required

ガチャID

integer (int64)

Query

avatarId
optional

アバターID。アバターに関する情報を取得する必要がある場合に指定。

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Gacha/{gachaId}/FittingRoom

Description

指定したアバターにガチャアイテムを試着したアバター画像のURLを取得します。

Parameters

Type Name Description Schema

Path

gachaId
required

ガチャID

integer (int64)

Query

avatarId
required

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Gachas

Description

販売中のガチャの一覧を取得します。ウェブ UI のガチャの一覧と同様、タイマー機能が有効になるため、指定した avatarId に設定した日時に販売されているガチャを返します。ひとつのガチャから取得できる情報は、/v1/Gacha/{gachaId} と同様です。

Parameters

Type Name Description Schema

Query

avatarId
optional

アバターID

integer (int64)

Responses

HTTP Code Description Schema

200

成功

default

失敗

POST /v1/Guest

Description

ゲストAPI。ゲストアバターを新規作成します。発行されたアバターIDを自社サービスのユーザと紐づけることで、以降は Avatars APIを使ってユーザのアバター画像URLなどを取得できるようになります。

Parameters

Type Name Description Schema

Query

scope
optional

スコープ。パーミッション名をカンマ区切りで連結した文字列。指定しなかった場合、アバターをロード(表示)する権限(AvatarLoad)のみのスコープを要求します。アイテム付与するためにはアイテム付与権限(ItemGrant)が必要になります。Example: AvatarLoad,ItemGrant

< string > array(multi)

Responses

HTTP Code Description Schema

200

成功。ゲストアバターの情報が返ります。

default

失敗

GET /v1/Items

Description

アプリで利用可能なアイテムの情報(サムネイル画像URLなど)をを取得します。avatarId を指定していない場合に限り、この API のレスポンスは、最大10分間キャッシュできます。

Parameters

Type Name Description Schema

Query

avatarId
optional

アバターID。指定した場合、そのユーザが該当アイテムを所持しているかどうかも判別できます。

integer (int64)

Query

itemId
required

アイテムID。アプリが利用できるアイテムとして登録されている必要があります。

< integer (int64) > array(multi)

Responses

HTTP Code Description Schema

200

成功

default

失敗

GET /v1/Shop/Session

Description

UI Kit のショップのセッション情報を取得するためのAPIです。アイテム購入確認画面を構成する際に利用します。ここで返されるアイテム情報は、購入対象となる、エンドユーザにとって未所持のアイテムに絞られます。アイテム付与APIに引き渡したセッションはすぐに破棄されますが、アイテム付与APIの実行と同時ではなく、数秒程度のタイムラグが発生することがあります。

Parameters

Type Name Description Schema

Query

avatarId
required

自社アプリ側で認証できたユーザのアバターID

integer (int64)

Query

shopSessionId
required

ショップセッションID。購入確認画面のURLに追加されたパラメータから取得できます。

string

Query

shopSessionVersion
required

ショップセッションのバージョン。購入確認画面のURLに追加されたパラメータから取得できます。セッションのバージョンが古い場合、APIへのアクセスがエラーとなります。これは、ブラウザのバックボタンでの操作や別の画面・タブを使って選択したアイテムが変更された場合に起こります。

integer (int32)

Responses

HTTP Code Description Schema

200

成功

default

失敗

Definitions

AccessToken

連携したアバターのアバターIDとアクセストークンを収録しています。

Name Description Schema

accessToken
optional

アクセストークン。RESTful APIのみを利用する場合は破棄して問題ありません。
Example : "d030073d5d1…​"

string

avatarId
optional

アバターID。自社アプリ内でアバターを一意に表すIDです。RESTful APIのパラメータとして利用できます。
Example : 1234567890

integer (int64)

avatarImageUrl
optional

アバター全身画像のURL。画像は240x320ピクセルサイズのアニメーションGIFです。テイストに応じたアニメーションが付きます。
Example : "https://example.com/avatar.gif"

string

faceImageUrl
optional

アバターバストアップ画像のURL。画像は120x120ピクセルサイズのGIFファイルです。アバターが正面を向いたアニメーションなしの画像です。サムネイルとしての利用などに適しています。
Example : "https://example.com/face.gif"

string

scope
optional

スコープ
Example : "AvatarLoad,ItemGrant"

string

tokenType
optional

トークンの種類。「Bearer」で固定です。
Example : "Bearer"

string

Avatar

アバター画像URLなどのアバター情報

Name Description Schema

avatarId
optional

アバターID
Example : 1234567890

integer (int64)

avatarImageUrl
optional

アバター全身画像のURL。画像は240x320ピクセルサイズのアニメーションGIFです。テイストに応じたアニメーションが付きます。
Example : "https://example.com/avatar.gif"

string

faceImageUrl
optional

アバターバストアップ画像のURL。画像は120x120ピクセルサイズのGIFファイルです。アバターが正面を向いたアニメーションなしの画像です。サムネイルとしての利用などに適しています。
Example : "https://example.com/face.gif"

string

guest
optional

ゲストユーザなら真
Example : true

boolean

status
optional

アバターのステータスを返します。200: 正常に画像取得。401: 画像取得のパーミッションが取れませんでした。ユーザがパーミッションを削除したなどの可能性があります。パーミッションを再取得することで改善する可能性があります。404: 存在しないアバターです。アバターIDが誤っているか、ユーザが削除された可能性があります。
Example : 200

integer (int32)

Avatars

Avatar のリストです。

Name Schema

avatars
optional

< Avatar > array

EchoMessage

エコー出力

Name Description Schema

message
optional

出力するメッセージ
Example : "hello"

string

Error

Name Description Schema

code
optional

Example : 400

integer (int32)

errors
optional

< ErrorDetail > array

message
optional

Example : "Invalid string value"

string

ErrorDetail

Name Description Schema

domain
optional

Example : "global"

string

message
optional

Example : "String 'abc' not a valid integer"

string

reason
optional

Example : "badRequest"

string

ErrorResponse

Name Schema

error
optional

Gacha

ガチャ情報

Name Description Schema

alertMessage
optional

アラート文。購入の際の注意事項として利用します。

string

alertMessage2
optional

アラート文2。購入の際の2つ目の注意事項として利用します。

string

backgroundImageUrl
optional

背景画像のURL

string

bannerImageUrl
optional

バナー画像のURL

string

closedAt
optional

販売終了日時。RFC3339形式。
Example : "2022-07-07T11:00:00Z"

string

currencyId
optional

通貨ID

integer (int64)

description
optional

説明文

string

firstTime
optional

ユーザがガチャを回したことがない場合は真。アバターIDを指定している場合にのみ有効。

boolean

firstTimeDiscountPrice
optional

初回限定価格。「0」が指定されている場合、初回限定価格は未設定。

number (double)

hasFree
optional

初回無料アイテムがある場合は真

boolean

iconImageUrl
optional

アイコン画像のURL

string

id
optional

ガチャID

integer (int64)

items
optional

ガチャに設定されているアイテムリスト。デベロッパーコンソールで設定した順番で返されます。

< GachaItem > array

name
optional

ガチャ名

string

openedAt
optional

販売開始日時。RFC3339形式。
Example : "2021-07-07T11:00:00Z"

string

price
optional

販売価格

number (double)

sampleCoordImageUrls
optional

サンプルコーデ画像のURLリスト

< string > array

tags
optional

ガチャに設定したタグリスト

< string > array

GachaFittingRoom

ガチャアイテムを試着したときの情報

Name Description Schema

avatarImageUrl
optional

試着したアバター画像のURL

string

GachaItem

ガチャアイテム

Name Description Schema

free
optional

初回無料アイテムなら真

boolean

have
optional

所持アイテムなら真。アバターIDを指定している場合にのみ有効。

boolean

itemId
optional

引き当てられたアイテムのID

integer (int64)

name
optional

デベロッパーコンソールで設定したアイテム名

string

rate
optional

出現確率(%)。小数第何位まで表示するかは、デベロッパーコンソールから指定できます。
Example : "12.34%"

string

tags
optional

デベロッパーコンソールで設定したアイテムのタグリスト

< string > array

thumbnailUrl
optional

引き当てられたアイテムのサムネイル画像URL

string

GachaSession

ガチャのセッション情報

Name Description Schema

currencyId
optional

通貨ID

integer (int64)

gachaId
optional

ガチャID

integer (int64)

gachaName
optional

ガチャ名

string

gachaTags
optional

ガチャに設定したタグリスト

< string > array

items
optional

引き当てたガチャアイテムリスト

< GachaItem > array

price
optional

販売価格。初回無料が適用される場合は0、初回限定価格が適用される場合は初回限定価格が設定されます。

number (double)

sessionId
optional

セッションID
Example : "1234567890…​"

string

Gachas

ガチャのリスト。ガチャアイテムの情報は含みません。

Name Schema

gachas
optional

< Gacha > array

Item

アイテムの情報

Name Description Schema

have
optional

指定したアバターIDのユーザが所持しているアイテムなら真。アバターIDを指定していない場合は偽が設定されます。
Example : false

boolean

itemId
optional

アイテムID
Example : 1234567890

integer (int64)

name
optional

デベロッパーコンソールで設定したアイテム名

string

tags
optional

デベロッパーコンソールで設定したタグリスト

< string > array

thumbnailUrl
optional

アイテムのサムネイル画像のURL。画像は60x60ピクセルのPNGファイルです。
Example : "https://example.com/thumbnail.png"

string

ItemResult

アイテム付与の結果

Name Description Schema

itemId
optional

アイテムID
Example : 1234567890

integer (int64)

status
optional

結果コード。200:正常に付与完了/409:所持済みのアイテム
Example : 200

integer (int32)

ItemResults

アイテム情報の取得結果

Name Schema

results
optional

< ItemResult > array

Items

アイテムリスト

Name Schema

items
optional

< Item > array

ShopItem

ショップの購入確認画面を構成する際に必要となるアイテム情報

Name Description Schema

itemId
optional

アイテムID

integer (int64)

name
optional

デベロッパーコンソールで設定したアイテム名

string

price
optional

価格。コンソールで設定されている値が返されます。

number (double)

shopId
optional

ショップID

integer (int64)

tags
optional

デベロッパーコンソールで設定したタグリスト

< string > array

thumbnailUrl
optional

アイテムのサムネイル画像のURL

string

ShopSession

ショップのセッション情報

Name Description Schema

currencyId
optional

通貨ID

integer (int64)

items
optional

< ShopItem > array

Security

api_key

Type : apiKey
Name : key
In : QUERY