概要
PlayMiningスカラーシップの概要については、スカラーシップ管理をご覧ください。
ここではPlayMiningスカラーシップ提供している、専用ページにて契約を行う方法について説明します。
この機能を利用することで、ゲーム内でスカラーシップの契約情報を管理するシステムを構築する必要が無くなります。
コンテンツへの利用料は発生しません。無料で使用可能です。
※一部、PlayMiningスカラーシップと連携する上で開発が必要な機能があります。
また、制約事項が複数ありますので、下記をよく読んでいただきますようお願い致します。
仕様
PlayMiningスカラーシップの主な仕様に加えて、以下の仕様で提供しています。
ユーザーフロー
オーナーとスカラーそれぞれにおける、契約〜解約、ゲーム内利用、報酬分配のフローは下記のとおりです。
オーナー
flowchart TD
top([PlayMiningスカラーシップTOPページ]) --> login[\ログインを選択する/]
login --> commonlogin[[ログイン]]
commonlogin --> main[PlayMiningスカラーシップメインページが表示される]
main --> owner[\オーナーページを選択する/]
owner --> ownermain[オーナーメインページが表示される]
ownermain --> contract[\'スカラーと契約'を選択する/]
contract --> contractpmid[スカラーPMID入力画面が表示される]
contractpmid --> ocontractpmid[\スカラーPMIDを入力する\n'次へ'を選択する/]
ocontractpmid --> contractdetailform[契約内容入力画面が表示される]
contractdetailform --> ocontractdetailform[\ゲームタイトルを選択する\n貸出NFTを選択する\n分配率を指定する\n'OK'を選択する/]
ocontractdetailform --> contractsign[契約確認画面が表示される]
contractsign --> ocontractsign[\'OK'を選択する/]
ocontractsign --> contractsigncomplete[申請完了画面が表示される]
contractsigncomplete --> ocontractback[\'メインページに戻る'を選択する/]
ocontractback --> oend([オーナーメインページが表示される])
ownermain --> cancel[\'スカラーを解約'を選択する/]
cancel --> cancellist[成約済リストが表示される]
cancellist --> ocancelcheck[\該当契約のチェックボックスを入れる\n'確認へ'を選択する/]
ocancelcheck --> cancelsign[解約確認画面が表示される]
cancelsign --> ocancelsign[\'OK'を選択する/]
ocancelsign --> cancelsigncomplete[申請完了画面が表示される]
cancelsigncomplete --> ocancelback[\'メインページに戻る'を選択する/]
ocancelback --> oend([オーナーメインページが表示される])
ownermain --> check[契約/収益を確認する]
check --> contractsignedlist[成約済契約リストが表示される]
contractsignedlist --> ocontractpendinglist[\'未契約'のラジオボタンを選択する/]
ocontractpendinglist --> contractpendinglist[未契約リストが表示される]
contractsignedlist --> ocontractcanceledlist[\'解約済'のラジオボタンを選択する/]
ocontractcanceledlist --> contractcanceledlist[解約済みリストが表示される]
contractsignedlist --> ocontractdetail[\契約を選択する/]
contractpendinglist --> ocontractdetail[\契約を選択する/]
contractcanceledlist --> ocontractdetail[\契約を選択する/]
ocontractdetail --> contractdetail[契約詳細画面が表示される]
スカラー
flowchart TD
top([PlayMiningスカラーシップTOPページ]) --> login[\ログインを選択する/]
login --> commonlogin[[ログイン]]
commonlogin --> main[PlayMiningスカラーシップメインページが表示される]
main --> scholar[\スカラーページを選択する/]
scholar --> scholarmain[スカラーメインページが表示される]
scholarmain --> contract[\'オーナーと契約'を選択する/]
contract --> contractpmid[オーナーPMID入力画面が表示される]
contractpmid --> scontractpmid[\オーナーPMIDを入力する\n'次へ'を選択する/]
scontractpmid --> contractlist[申請中リストが表示される]
contractlist --> scontractcheck[\該当契約のチェックボックスを入れる\n'OK'を選択する/]
scontractcheck --> contractcheckdetail[該当契約の詳細が表示される]
contractcheckdetail --> saccept[\'合意する'を選択する/]
saccept --> contractsign[契約確認画面が表示される]
contractsign --> scontractsign[\'はい'を選択する/]
scontractsign --> contractsigncomplete[申請完了画面が表示される]
contractsigncomplete --> scontractback[\'メインページに戻る'を選択する/]
scontractback --> send([スカラーメインページが表示される])
contractcheckdetail --> sdeny[\'合意しない'を選択する/]
sdeny --> denysign[申請却下確認画面が表示される]
denysign --> sdenysign[\'はい'を選択する/]
sdenysign --> contractdenycomplete[申請却下完了画面が表示される]
contractdenycomplete --> scontractdenyback[\'メインページに戻る'を選択する/]
scontractdenyback --> send([スカラーメインページが表示される])
scholarmain --> cancel[\'オーナーを解約'を選択する/]
cancel --> cancellist[成約済リストが表示される]
cancellist --> scancelcheck[\該当契約のチェックボックスを入れる\n'確認へ'を選択する/]
scancelcheck --> cancelsign[解約確認画面が表示される]
cancelsign --> scancelsign[\'OK'を選択する/]
scancelsign --> cancelsigncomplete[申請完了画面が表示される]
cancelsigncomplete --> scancelback[\'メインページに戻る'を選択する/]
scancelback --> send([スカラーメインページが表示される])
scholarmain --> check[契約/収益を確認する]
check --> contractsignedlist[成約済契約リストが表示される]
contractsignedlist --> ocontractpendinglist[\'未契約'のラジオボタンを選択する/]
ocontractpendinglist --> contractpendinglist[未契約リストが表示される]
contractsignedlist --> ocontractcanceledlist[\'解約済'のラジオボタンを選択する/]
ocontractcanceledlist --> contractcanceledlist[解約済みリストが表示される]
contractsignedlist --> ocontractdetail[\契約を選択する/]
contractpendinglist --> ocontractdetail[\契約を選択する/]
contractcanceledlist --> ocontractdetail[\契約を選択する/]
ocontractdetail --> contractdetail[契約詳細画面が表示される]
専用ページヘの遷移について
専用ページへの導線はゲーム内にリンクを配置して頂き、そこから遷移する流れとしております。
スカラーシップ遷移後もログインフェーズがありますが、ゲームにログイン済みであればPlayMining NFT遷移時に自動的にログインされ、専用ページに遷移します。
ゲーム内からスカラーシップページ遷移とログインまでにおけるシーケンス
sequenceDiagram
autonumber
actor user
participant game as コンテンツ
participant scholarship as スカラーシップ
participant pmp as PMP
user ->> game: ゲーム内からスカラーシップページにアクセス
user ->>+ scholarship: スカラーシップページにリダイレクト
scholarship -->>- user: スカラーシップTOPページ表示
user ->>+ scholarship: 「ログイン」押下
scholarship ->>+ pmp: PlayMining NFTのログインページへリダイレクト
pmp -->>- user: ログインページ表示
user ->>+ pmp: ログイン
pmp -->>- scholarship: スカラーシップTOPページへリダイレクト
alt 初回利用(=利用規約未同意)時
scholarship -->> user: 利用規約ページ表示
user ->> scholarship: 利用規約同意
scholarship ->> scholarship: ユーザー登録
end
scholarship -->>- user: スカラーシップTOPページ表示
契約に関して
- 契約はオーナーから申請し、スカラーが承諾して成約となります。
- 契約は、オーナーとスカラーのPMIDを用いてリクエストします。
- オーナーは契約申請時に貸出ゲームと貸出対象NFT(複数指定可能)、報酬分配率(0~10:10~0といった整数値の比率でのみ指定可能)を指定して申請します。
- オーナーがNFTを選定しやすいように、貸出対象NFT指定時にSpec情報を表示しています。
- 各アセット/トークン単位でのSpec情報はゲームにて管理する必要があります。
- また、PlayMiningスカラーシップ専用ページを利用する を対応していただき、PlayMiningスカラーシップから取得できるようにしていただく必要があります。
- 1ゲームあたり、オーナーは複数のスカラーと契約が可能ですが、スカラーは1人のオーナーとのみ契約可能です。
- 契約に期間はありません。オーナーまたはスカラーが解約を申請し、実際に解約処理が走るまで契約は有効となります。
- 契約ごとに必ず1つ以上のNFTを貸し出す必要があります。最大貸出可能数は100トークンです。
- 101件で実行すると、エラー(result:61021)が返却されます。
- オーナーによる契約申請後、スカラーが合意を72時間放置した際は、自動的に申請取り消しとなります。
スカラーシップの契約からゲーム利用におけるシーケンス
sequenceDiagram
autonumber
actor owner
actor scholar
participant game as コンテンツ
participant scholarship as スカラーシップ
participant pmp as PMP
owner -> scholar: Discord上などでの契約内容合意(NFTや分配率など)
owner ->>+ scholarship: ログイン
scholarship -->>- owner: スカラーシップTOPページ表示
owner ->>+ scholarship: 「マイページ」押下
scholarship -->>- owner: マイページ表示
owner ->>+ scholarship: 「スカラーと契約」押下
scholarship -->>- owner: スカラーPMID入力画面表示
owner ->>+ scholarship: スカラーのPMIDを入力
scholarship -->>- owner: 契約内容入力画面表示
owner ->>+ scholarship: 貸出ゲーム、貸出NFT、報酬分配率を指定
scholarship -->>- owner: 契約内容確認画面表示
owner ->>+ scholarship: 契約申請
scholarship ->> scholarship: 契約情報保持
scholarship ->>+ pmp: オーナー側契約申請API
pmp ->> pmp: 対象NFTのトークンロック
pmp -->>- scholarship: レスポンス
scholarship -->>- owner: 契約申請完了画面表示
scholar ->>+ scholarship: ログイン
scholarship -->>- scholar: スカラーシップTOPページ表示
scholar ->>+ scholarship: 「マイページ」押下
scholarship -->>- scholar: マイページ表示
scholar ->>+ scholarship: 「オーナーと契約」押下
scholarship -->>- scholar: オーナーPMID入力画面表示
scholar ->>+ scholarship: オーナーのPMIDを入力
scholarship -->>- scholar: 申請中契約一覧画面表示
scholar ->>+ scholarship: 対象契約選択
scholarship -->>- scholar: 契約内容確認画面表示
scholar ->>+ scholarship: 契約合意
scholarship ->> scholarship: 契約情報更新
scholarship ->>+ pmp: スカラー側契約申請API
pmp ->> pmp: 該当NFTの利用者変更
pmp -->>- scholarship: レスポンス
scholarship -->>- scholar: 成約完了画面表示
scholar ->>+ game: ゲームログインまたは所持NFT一覧情報更新
game ->>+ pmp: NFT所持情報一覧取得API
pmp ->>- game: レスポンス
game ->>+ pmp: 契約中NFT一覧取得API
pmp ->>- game: レスポンス
game ->>- scholar: 所持NFT一覧情報表示
scholar ->> game: ゲームプレイ
報酬分配に関して
- 報酬を分配するタイミングは、コンテンツ側に一任しております。イベントやクエストをこなしたタイミングでも構いませんし、シーズン制にしてシーズン終了時に一斉に配布しても構いません。
- 報酬分配はゲーム内で実施をお願いします。報酬額を契約時に設定した報酬分配率に応じてゲーム側で算出し、オーナーとスカラーに対して、PMPが提供するDEP付与APIをそれぞれ叩くことでDEPを移転してください。
- 報酬分配率に関しては、PlayMiningスカラーシップで提供しているPlayMiningスカラーシップ専用ページを利用する を叩き、取得して下さい。
- PlayMining用語集 での分配には対応しておりません。
- DEAPcheckは1枚あたりの額と枚数を決定した上で、事前に発行しておく必要があり、分配率によって無数の額になりうる報酬分の事前発行が困難であるためです。
- ゲーム内通貨の分配には対応しておりません。DEPでの分配を前提とした設計としております。
- 報酬分配後、PlayMiningスカラーシップが提供するPlayMiningスカラーシップ専用ページを利用する を叩き、オーナー/スカラーそれぞれの分配額を必ず報告して下さい。
- オーナー/スカラーが収益確認時に、いつ、どれほど稼ぐことができたかを参照できるようにしています。
ゲームプレイ(クエストクリア)による報酬配布におけるシーケンス
例として、クエストクリア後即時DEP付与の場合を下図に示します。
シーズン制の場合は、シーズン終了のタイミングでPlayMiningスカラーシップ専用ページを利用する 、DEP付与API、PlayMiningスカラーシップ専用ページを利用する をリクエストしてください。
sequenceDiagram
autonumber
actor owner
participant ownerwallet as オーナーウォレット
actor scholar
participant scholarwallet as スカラーウォレット
participant game as コンテンツ
participant scholarship as スカラーシップ
participant pmp as PMP
scholar ->>+ game: ゲーム内でのクエストクリア
game ->> scholar: クエストクリア画面
game ->>+ scholarship: 分配率取得API
scholarship -->>- game: 分配率情報
game ->>+ game: オーナー/スカラーの報酬額算出
game ->> pmp: スカラーPMIDでDEP付与API
pmp ->> scholarwallet: スカラーのウォレットにDEP入金
game ->> scholarship: スカラーPMIDで分配報酬共有API
game ->> pmp: オーナーPMIDでDEP付与API
pmp ->> ownerwallet: オーナーのウォレットにDEP入金
game ->> scholarship: オーナーPMIDで分配報酬共有API
解約に関して
- 解約はオーナーまたはスカラーどちらからでも申請可能です。
- 解約申請後、相手方の同意を必要とせずに解約待ちステータスとなります。
- 解約待ちステータスの契約は、翌々日のUTC0時に解約処理が行われる仕様としています。
- 即時解約を可能にすると、解約完了後即契約を繰り返すことで、オーナーが同じNFTで複数のスカラーと順番に契約が可能となり、オーナーのみがデイリータスク報酬を複数回分配取得するという不正行為が行われます。これを防ぐ施策です。
スカラーシップ契約の解約におけるシーケンス
sequenceDiagram
autonumber
actor user
participant game as コンテンツ
participant scholarship as スカラーシップ
participant pmp as PMP
user ->> scholarship: ログイン
scholarship -->> user: スカラーシップTOPページ表示
user ->>+ scholarship: 「マイページ」押下
scholarship -->>- user: マイページ表示
user ->>+ scholarship: 「スカラーを解約」押下
scholarship -->>- user: 契約中一覧画面表示
user ->>+ scholarship: 解約対象を選択
scholarship -->>- user: 解約確認画面表示
user ->>+ scholarship: 「OK」押下
scholarship ->>+ pmp: 契約解除API
pmp ->> pmp: 該当NFTの利用者更新&トークンロック解除
pmp -->>- scholarship: レスポンス
scholarship -->>- user: 解約完了画面表示
契約状況/収益確認に関して
- PlayMiningスカラーシップのページ上で、過去から現在に至る契約情報をすべて確認することができます。
- 各契約における、分配処理ごとの収益を確認することができます。
※「報酬分配に関して」にも記載しておりますが、上記の表示を行うために、コンテンツ側でPlayMiningスカラーシップ専用ページを利用する を叩き、分配額を連携していただく必要があります。
その他、懸念点/疑問点/相談は別途、コンテンツごとにSlackで用意します「エンジニア問い合わせチャンネル」でお問い合わせください。
PlayMiningスカラーシップとの連携
環境情報
環境名 | 画面のURL |
開発 | |
Staging | |
本番 |
提供APIについて
リクエストに必要な、ヘッダーのAuthorizationで指定するAPIKEYやパラメータのcontents_idは、PMPにて払い出したものを指定してください。
ヘッダー情報 | |
Content-type | application/json |
Authorization | Bearer [APIKEY] |
共通エラーレスポンスは下表のとおりです。
ステータスコード | メッセージ | 説明 |
200,201,202,204 | 成功 | |
400 | Bad Request | リクエスト不正 |
401 | Unauthorized | 未認証 |
403 | Forbidden | 認証に失敗 |
404 | Not Found | エンドポイント存在しない、メソッド不正 |
500 | Internal Server Error | 予期せぬエラー |
また、一部のAPIは内部的に別APIをリクエストします。
そのAPIでエラーとなった場合は、そのAPIのエラーコードをゲームへ返します。そのためスカラーシップのエラーとは内容が異なりますのでご注意ください。
分配率取得API
/api/admin/distribution-factors
PlayMiningスカラーシップに登録された報酬契約情報(報酬分配率)を取得するAPIです。
リクエストパラメータにPMIDを複数指定することができ、1リクエストで50件を取得可能です。
- リクエスト
パラメータ | 内容 |
ownerPmids | オーナーのPMIDです。 |
scholarPmids | スカラーのPMIDです。 |
limit | (任意)1ページあたりで取得する契約数です。 |
page | (任意)取得するページ番号です。
limit=2, page=2の場合、過去から遡って3,4件目の契約情報を取得します。
limit=10, page=1の場合、過去から遡って10件目までの契約情報を取得します。 |
jsonリクエスト例 { "contentsId": "contentsid", "ownerPmids": ["owner1", "owner2", ...], "scholarPmids": ["scholar1", "scholar2", ...], "limit": 50, "page": 0 }
- レスポンス
パラメータ | 内容 |
contracts | |
contractId | 契約IDです。 |
contentsId | 契約が結ばれているコンテンツIDです。 |
ownerPmid | オーナーのPMIDです。 |
scholarPmid | スカラーのPMIDです。 |
ownerDistributionFactor | オーナーの報酬分配率です。 |
scholarDistributionFactor | スカラーの報酬分配率です。 |
totalCount | 検索に合致した全件数です。 |
hasNext | 次ページの有無です。 |
jsonレスポンス例 { "contracts": [ { "contractId": 1, "contentsId": "contentsid", "ownerPmid": "owner1", "scholarPmid": "scholar1", "ownerDistributionFactor": 0.7, "scholarDistributionFactor": 0.3 },...], "totalCount": 20, "hasNext": true }
報酬共有API
/api/admin/distributions/share
契約を元に分配された報酬額をPlayMiningスカラーシップに共有するAPIです。
この額を共有していただくことで、ユーザーが契約状況を確認した際に、報酬の履歴を確認することができます。
クエストクリア等でオーナー/スカラーに報酬分配後、それぞれの報酬額を共有して下さい。
- リクエスト
パラメータ | 内容 |
contractId | 契約IDです。 |
pmid | 報酬を支払ったPMIDです。 |
amount | (任意)1ページあたりで取得する契約数です。 |
jsonリクエスト例 { "contentsId": "contentsid", "contractId": 1, "pmid": "pmid", "amount": 100.11, }
- レスポンス
パラメータ | 内容 |
distributionHistoryId | 分配履歴ID |
jsonレスポンス例 { "distributionHistoryId": 1 }
PlayMiningスカラーシップ利用手順
PMPチームへの利用申請
- 前述の仕様をご理解いただいた上で、以下の情報を揃え、ご相談下さい。
- 利用するゲーム名
- ゲームのリリース時期
- スカラーシップ機能の提供開始時期(「ゲームリリースと同時」、「リリース後3か月後目処」など)
IPアドレスの提供
PlayMiningスカラーシップは、APIの叩き元をIPアドレスでアクセスを制限しています。
APIを叩く上でゲーム側のIPアドレスを許可するため、各環境ごとにIPアドレスを「エンジニア問い合わせチャンネル」にて共有ください。
開発環境に限り、開発会社様VPNのIPアドレスからも許可致します。
PlayMiningスカラーシップ向けSpecAPI開発
- オーナーの貸出NFTが判別つくよう、オークションページと同様にSpec表示を実装しており、コンテンツ側にて該当NFTのSpec情報を返すAPIの開発が必要です。
- 上記を実現するために、Spec情報をゲーム内にてDBなどで保持していただく必要があります。
- PlayMiningスカラーシップのSpec表示は、レスポンスで返った項目順ごとに改行し表示するという非常に簡素な設計です。
- トークンごとにSpecが異なるようであればトークンごとに返す「トークンSpecAPI」を、アセット単位で共通であれば「アセットSpecAPI」を準備する必要があります。
- 細かな仕様に関しては、会話にて確認できればと思いますが、大まかには以下の仕様に沿ってAPIをご提供下さい。
- 接続ホスト
- DEV,STG,PROD各環境分決定し共有してください(適宜でも構いません)。
- 例:https://[dev, stg, prod]-apiserver.xxxxxxxx.com
- リクエスト
- HTTPSプロトコルを使用してください。
- Bearerトークンを使用してください。
- PATH: 特に指定はありません。(例:scholarship/[asset, token])
- リクエストメソッド: GET
- APIリクエストヘッダ:
- リクエストパラメータ:
- レスポンス
- 共通レスポンス
- レスポンスパラメータ
- valueはすべてStringとしてください。
- “Spec”の下階層(”hp”や”atk”)は例ですので、ゲームの仕様に合わせて変更/追加してください。
- “Skill”の下階層は、表示したいスキルの順番に沿って”1”, ”2”とし、その中にゲームの仕様に合わせて変更/追加してください。
- アルファベットや漢字も表示可能ですが、あまり長い文字数ではSpec表示が崩れうるため、”attack”は”ATK”などより短い表示となるように工夫ください。
- 英語(en)表記は必須で、ゲームで日本語(ja)/インドネシア語(id)/繁体字(tw)もサポートするようでしたら、必要に応じてそれぞれ返してください。
JSON Key | 型 | 必須 | 値 |
Content-type | String | ○ | application/json |
Authorization | String | ○ | Bearer [APIKEY] |
JSON Key | 型 | 必須 | 値 |
asset_id | String | ○ ※1 | アセットID(1~5桁)
※1 アセットSpecAPIでは必須 |
token_id | String | ○ ※2 | トークンID=アセットID(1~5桁)+シリアルNo(5桁) 例:123200642
※2 トークンSpecAPIでは必須 |
200 | Success | 成功 |
401 | Unauthorized | 認証に失敗( APIKEY が間違っている等) |
404 | Not Found | データが取得できない |
json{ "Spec":{ "hp":{ "name":{ "en": "HP" "ja": "体力" //対応言語によっては不要 "id": "HP" //対応言語によっては不要 "tw": "HP" //対応言語によっては不要 }, "param": "95230" }, "atk":{ "name":{ "en": "attack" "ja": "攻撃力" //対応言語によっては不要 "id": "" //対応言語によっては不要 "tw": "" //対応言語によっては不要 }, "param": "150" }, ・・・・・ }, "Skill":{ "1":{ "level": "1", "name":{ "en": "Skill NAME" "ja": "スキル名" //対応言語によっては不要 "id": "" //対応言語によっては不要 "tw": "" //対応言語によっては不要 }, "description": { "en": "Skill Detail" "ja": "スキルの説明" //対応言語によっては不要 "id": "" //対応言語によっては不要 "tw": "" //対応言語によっては不要 } }, ・・・・・ } }
PlayMiningスカラーシップ側からのアクセス許可
- 前項のとおり、PlayMiningスカラーシップのページ上でNFTのSpec情報を表示するため、ゲーム側でIPアドレス制限をかけている場合は、各環境ごとにPlayMiningスカラーシップのサーバーからのアクセスを許可していただく必要があります。
- 許可いただくIPアドレスは以下の通りです。
環境 | IPアドレス |
開発環境 | 52.197.135.50 |
検証環境 | 35.79.174.47
54.95.116.160 |
本番環境 | 18.180.187.58
52.193.121.22 |
ゲーム画面内でのPlayMiningスカラーシップページへのリンク配置
- PlayMiningスカラーシップへの遷移に関しては、ゲームページ内にリンクを配置していただく方針としております。
- ユーザーはリンクからPlayMiningスカラーシップの専用ページに遷移し、契約する流れとしています。
- スカラーシップのリンク(アイコン可)を配置するスペースを検討いただきますようお願いいたします。
- ロゴとバナーは以下の画像を利用ください。