logo

概要

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[契約詳細画面が表示される]
Image without caption

スカラー

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[契約詳細画面が表示される]
Image without caption

専用ページヘの遷移について

専用ページへの導線はゲーム内にリンクを配置して頂き、そこから遷移する流れとしております。
スカラーシップ遷移後もログインフェーズがありますが、ゲームにログイン済みであれば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ページ表示
Image without caption

契約に関して

  • 契約はオーナーから申請し、スカラーが承諾して成約となります。
  • 契約は、オーナーとスカラーの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: ゲームプレイ
Image without caption

報酬分配に関して

  • 報酬を分配するタイミングは、コンテンツ側に一任しております。イベントやクエストをこなしたタイミングでも構いませんし、シーズン制にしてシーズン終了時に一斉に配布しても構いません。
  • 報酬分配はゲーム内で実施をお願いします。報酬額を契約時に設定した報酬分配率に応じてゲーム側で算出し、オーナーとスカラーに対して、PMPが提供するDEP付与APIをそれぞれ叩くことでDEPを移転してください。
  • 🚕PlayMining用語集 での分配には対応しておりません。
    • DEAPcheckは1枚あたりの額と枚数を決定した上で、事前に発行しておく必要があり、分配率によって無数の額になりうる報酬分の事前発行が困難であるためです。
  • ゲーム内通貨の分配には対応しておりません。DEPでの分配を前提とした設計としております。
  • 報酬分配後、PlayMiningスカラーシップが提供するPlayMiningスカラーシップ専用ページを利用する を叩き、オーナー/スカラーそれぞれの分配額を必ず報告して下さい。
    • オーナー/スカラーが収益確認時に、いつ、どれほど稼ぐことができたかを参照できるようにしています。

ゲームプレイ(クエストクリア)による報酬配布におけるシーケンス

例として、クエストクリア後即時DEP付与の場合を下図に示します。
シーズン制の場合は、シーズン終了のタイミングでPlayMiningスカラーシップ専用ページを利用するDEP付与APIPlayMiningスカラーシップ専用ページを利用する をリクエストしてください。
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
Image without caption

解約に関して

  • 解約はオーナーまたはスカラーどちらからでも申請可能です。
  • 解約申請後、相手方の同意を必要とせずに解約待ちステータスとなります。
  • 解約待ちステータスの契約は、翌々日の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: 解約完了画面表示
Image without caption

契約状況/収益確認に関して

  • PlayMiningスカラーシップのページ上で、過去から現在に至る契約情報をすべて確認することができます。
  • 各契約における、分配処理ごとの収益を確認することができます。
その他、懸念点/疑問点/相談は別途、コンテンツごとにSlackで用意します「エンジニア問い合わせチャンネル」でお問い合わせください。

PlayMiningスカラーシップとの連携

環境情報

提供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表示は、レスポンスで返った項目順ごとに改行し表示するという非常に簡素な設計です。
表示例1:Spec表示は項目と値ごとに改行を入れて表示している
表示例1:Spec表示は項目と値ごとに改行を入れて表示している
表示例2:Skillなどの表示は文面が長くなりうるため、項目と説明も改行して表示している
表示例2:Skillなどの表示は文面が長くなりうるため、項目と説明も改行して表示している
  • トークンごとにSpecが異なるようであればトークンごとに返す「トークンSpecAPI」を、アセット単位で共通であれば「アセットSpecAPI」を準備する必要があります。
  • 細かな仕様に関しては、会話にて確認できればと思いますが、大まかには以下の仕様に沿ってAPIをご提供下さい。
    • 接続ホスト
      • DEV,STG,PROD各環境分決定し共有してください(適宜でも構いません)。
        • 例:https://[dev, stg, prod]-apiserver.xxxxxxxx.com
    • リクエスト
      • HTTPSプロトコルを使用してください。
      • Bearerトークンを使用してください。
      • PATH: 特に指定はありません。(例:scholarship/[asset, token])
      • リクエストメソッド: GET
      • APIリクエストヘッダ:
        • 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
          データが取得できない
      • レスポンスパラメータ
        • valueはすべてStringとしてください。
        • “Spec”の下階層(”hp”や”atk”)は例ですので、ゲームの仕様に合わせて変更/追加してください。
        • “Skill”の下階層は、表示したいスキルの順番に沿って”1”, ”2”とし、その中にゲームの仕様に合わせて変更/追加してください。
        • アルファベットや漢字も表示可能ですが、あまり長い文字数ではSpec表示が崩れうるため、”attack”は”ATK”などより短い表示となるように工夫ください。
        • 英語(en)表記は必須で、ゲームで日本語(ja)/インドネシア語(id)/繁体字(tw)もサポートするようでしたら、必要に応じてそれぞれ返してください。
          • 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スカラーシップの専用ページに遷移し、契約する流れとしています。
  • スカラーシップのリンク(アイコン可)を配置するスペースを検討いただきますようお願いいたします。
  • ロゴとバナーは以下の画像を利用ください。
スカラーシップロゴ
スカラーシップロゴ
スカラーシップバナー
スカラーシップバナー