Playell Connect 開発者ガイド

はじめに

Playell Connect は、利用者の同意を得て、外部アプリが Playell のアカウントや画像を使うための連携機能です。ゲームからログインし、利用者が選んだ画像を使う方法のほか、許可された画像の一覧を読む方法と画像を保存する方法があります。必要な権限だけを依頼してください。

この案内では、秘密を保持できるサーバー型のアプリを想定します。ブラウザー、ゲームクライアント、公開リポジトリには client_secret や利用者のトークンを埋め込まないでください。

受け取った情報は、利用者に示した連携サービスの機能にだけ使います。受け取った画像のサービス外での利用・再配布・機械学習への利用は禁止されています。プライバシーポリシーに利用方法、共有先、削除の頼み方を記載し、アプリが Playell の提供するものではないことを利用者に示してください。詳細は Playell Connect 利用規約に従ってください。

利用できるのは、日本に住所のある個人で、Playell の提供者として承認されている方、またはゲーム作成者として登録した方です。

アプリの登録

1. Playell にログインし、左のメニューまたはアカウント画面の「開発者になる」または「接続先の管理」から接続先画面へ進みます。
2. ゲーム作成者としての登録が必要な場合は、Playell Connect 利用規約に同意して登録します。
3. 接続先の登録前に「パスワードを確認」で再確認します。登録・秘密の更新・停止には、直近 15 分以内のパスワード確認が必要です。確認画面へ移った場合、入力内容は再送されません。
4. 「接続先を登録する」に名前、戻り先の URL、連絡先のメール、プライバシーポリシーの URL を入力し、日本に住所のある個人であることと規約への同意を確認して登録します。
5. 表示された client_id と client_secret を控えます。秘密は発行時に一度だけ表示されます。安全なサーバー側の保管場所で管理してください。

名前は 40 文字以内。戻り先は HTTPS の URL を 1〜5 件、1 行に 1 件ずつ登録します。重複は登録できません。プライバシーポリシーも HTTPS の URL を指定します。認可と画像の選択には登録済みの戻り先を使います。ゲーム作成者の接続先は 2 件までです。

秘密を紛失した場合は接続先の操作から再発行できます。予備の秘密を作成・停止する操作もあります。切り替えるときは、予備を発行してアプリのサーバー設定を切り替えた後、不要になった秘密を停止または再発行します。主の秘密の再発行は主の値を置き換え、予備の停止は予備だけを無効にします。漏えいのおそれがあるときは、該当する秘密を直ちに再発行または停止し、運営に連絡してください。

Playell でログイン

1. サーバーで予測困難な state と PKCE の code_verifier を作り、code_challenge を S256 で導きます。元の値は利用者のセッションに安全に保持します。
2. 利用者を /portal/ConnectAuthorize.aspx に移動し、response_type=code、client_id、登録済みの redirect_uri、必要な scope、state、code_challenge、code_challenge_method=S256 を送ります。認可は Playell の画面で行います。
3. 利用者が同意すると戻り先へ認可コードが返ります。戻り先で state を照合し、エラーや不一致なら処理を止めます。
4. サーバーから POST /portal/ConnectToken.ashx に application/x-www-form-urlencoded で grant_type=authorization_code、code、同じ redirect_uri、元の code_verifier を送ります。クライアント認証は client_secret_basic です。トークン交換に scope を送ると拒否されます。
5. 応答の access_token をサーバー側で管理し、API の Authorization: Bearer … に指定します。expires_in を読み、有効期限を管理します。

認可コードの有効期限は 60 秒、アクセストークンは 60 分です。継続セッションは 72 時間で、許可ごとに 5 件までです。

アクセス範囲には identity、characters.read、library.pick、library.read、library.write などがあります。ゲーム作成者の接続先は participation.read を要求できません。op.spend と op.balance.read は、承認済みの提供者情報・本人確認・接続先の設定などの条件を満たす場合に限られます。

継続利用が必要な場合は認可時に access_type=offline を指定し、利用者の同意を得ます。トークン応答に refresh_token と refresh_expires_in が含まれます。更新は同じトークン口へ grant_type=refresh_token と refresh_token を送り、発行された新しい値を安全に保存します。値が変わる場合は応答の expires_in を優先してください。

更新の応答を受け取れなかった場合は、条件を満たせば使用済みの refresh token で同じ結果を 120 秒以内に回復できます。後継のトークンが既に使われた場合など、常に回復できるわけではありません。回復できなければ再認可を行ってください。

任意の resource を送る場合は https://playell.jp/portal/ConnectApi.ashx を指定します。

画像を選ぶ

library.pick の同意後、POST /portal/ConnectApi.ashx?action=picker-start に Bearer トークンとフォームの max、redirect_uri、state を送ります。max は 1〜50、省略時は 1 です。戻り先は登録済みの URL を指定します。

応答の picker_url を利用者に開いてもらいます。利用者が選択を確定すると戻り先に pick と state が返り、取り消した時は error=access_denied が返ります。state を照合してから、GET /portal/ConnectApi.ashx?action=picked&pick=… を同じ許可の Bearer トークンで呼び、images を受け取ります。チケットと選択結果はどちらも 5 分間有効で、選択結果は 1 回だけ受け取れます。

選ばれた画像の ID は GET /portal/ConnectApi.ashx?action=image&id=… で使います。利用者が画像の共有を取り消した場合は、選び直しを案内してください。

画像の一覧を読む

library.read は利用者のライブラリの画像を読む権限です。個別に選んだ画像だけを使う場合は、より限定された library.pick を検討してください。同意後、GET /portal/ConnectApi.ashx?action=library-list に Bearer トークンを付けます。

応答は images と next_page を含みます。1 ページは最大 24 件です。次がある場合は返された next_page をそのまま page に渡します。各要素には image、name、width、height、type、bytes、created_at が含まれます。画像とサムネイルはそれぞれ action=image、action=thumb に ID を指定します。

画像を保存する

library.write の同意後、POST /portal/ConnectApi.ashx?action=library-save に Bearer トークン、Idempotency-Key ヘッダー、multipart/form-data の name と画像ファイル file を送ります。ファイルは 1 件です。成功すると HTTP 201 と画像 ID・名前が返ります。

画像は 20,971,520 バイトまで、各辺 4,096 pxまで、総画素数 16,000,000 までです。送る前にファイルの大きさと寸法を確かめてください。multipart の境界や他の欄も要求の大きさに含まれます。要求全体が 22,085,632 バイトを超えると、アプリより手前の Web サーバーが HTML のエラーを返すことがあるため、応答を JSON と決めつけず HTTP の状態と Content-Type を確かめてください。

保存の応答を受け取れなかったときは、同じ許可・同じ名前・同じ画像に同じ Idempotency-Key を使って送り直します。同じキーを異なる内容や許可に使うと 409 idempotency_mismatch になります。別の保存には別のキーを使ってください。PNG・JPEG・GIF・WebP に対応し、保存は利用者の画像枠と容量を使います。容量が足りないときは利用者に案内してください。利用者の明示の操作なしに画像を保存することはできません。

エラーへの対応

秘密やトークンを、ログ・URL・問い合わせの本文に出さないでください。

同時数と回数の上限

• 接続先あたりの API:600 回/分
• トークンあたりの API:60 回/分
• サムネイル:240 回/分
• 接続先あたりのトークンの交換と更新:合わせて 60 回/分
• 画像の取得:1 つのトークンで同時 4 本まで

これらは変わることがあります。画像の読み取りには別の同時実行の制御があり、混雑時には 503 が返ります。サムネイルは元の画像と同じものが返ることがあります。利用者ごとの画像枠と容量に加え、画像の新規作成数やサーバー全体の容量にも上限があり、状態によって保存を受け付けられない場合があります。

利用者が連携を外したとき

利用者は Playell の「連携中のアプリ」から連携や共有画像を管理できます。取り消された許可や画像へのアクセスは続けられません。アクセスに失敗したときは利用者に状況を示し、必要なら再認可・選び直しを案内してください。アプリからトークンを取り消す場合は POST /portal/ConnectRevoke.ashx に Basic 認証とフォームの token を送ります。

連携を取り消されたとき、または利用者から削除を求められたときは、法令で保存が必要なものを除き、この API から受け取った情報を遅滞なく削除してください。連携サービスを終えるときや運営から求められたときも同じです。

試し方

専用の試験環境はありません。本番の Playell で、自分のアカウントと自分の画像を使って試してください。利用者の画像を試しに使わないでください。戻り先は自分のサーバーに設定し、試し終わったら連携を外してください。

よくあるつまずき

• 戻り先の URL が登録した物と合わない:登録内容と実際の URL を照らし合わせます。
• 保存の応答が JSON で返らない:大きな要求は Web サーバーの HTML のエラーになることがあります。画像だけでなく multipart 全体の大きさも確かめます。
• 同じ画像の保存を送り直したら競合した:同じキーに異なる名前・ファイル・許可を使っていないか確かめます。
• 認可の後に画像が見えない:利用者が同意した scope、連携の状態、選択の取り消し、画像があるかを確かめます。
• 登録の画面が出ない:アカウントの種類を確かめます。
• 日本語の画像名:UTF-8 で送り、保存後に返る名前を確かめます。