基本概念

プロジェクト、キー、プレイヤーセッション、そして各 SDK が結果とエラーをどのように返すかを説明します。

コードのコメントと API 名は、SDK と一致させるため英語のままにしています。

このページの内容

プロジェクトとキー#

ゲームごとに 1 つのプロジェクトを使用します。キーはプロジェクトを識別するもので、プレイヤーを識別するものではありません。

認証情報使用する場所
Base URLこのサーバーのアドレスです。API は /v1 以下にあります。
Project IDすべてのリクエストに X-Project-ID として付けます。公開情報です。
クライアントキー pk_live_…ゲームのビルドや Web ページで X-Client-Key として使用します。公開情報で、ログイン中のプレイヤーの範囲でしか操作できません。
シークレットキー sk_live_…自社のサーバーでのみ X-Secret-Key として使用します。表示は一度だけで、ハッシュ化して保存されます。サーバー専用のエンドポイントを利用できるようになります。
シークレットキー(sk_live_…)は、ゲームのビルドや Web ページに絶対に含めないでください。プレイヤーに配布したものは、すべて読み取られる可能性があります。

プレイヤーとセッション#

プレイヤー向けの呼び出しにはアクセストークンが必要です。ログインすると、アクセストークン(有効期間 1 時間)とリフレッシュトークン(有効期間 30 日)が返されます。

  • SDK はセッションをデバイスに保存し、有効期限が切れる前に更新します。そのため、プレイヤーは起動をまたいでもログイン状態を維持できます。
  • リフレッシュトークンは使用するたびにローテーションされます。古いトークンを再利用すると、そのセッションはすべての場所でログアウトされます(盗用検知)。
  • すべてのプレイヤーはゲストとして始まり、あとからメールアドレスや Google アカウントを連携できます。ゲストの進行状況もそのまま引き継がれます。詳しくはプレイヤーを参照してください。

例外ではなく結果を返す#

SDK の呼び出しは、ネットワークエラーやサーバーエラーで例外をスローしません。ok、値、エラー(安定したコード、メッセージ、リクエスト ID を含む)を持つ結果を返します。

C#
var top = await Majacloud.Leaderboards.GetTopAsync("coins", 10);
if (top.Ok)
{
    foreach (var entry in top.Value.Entries)
        Debug.Log($"#{entry.Rank} {entry.PlayerName} {entry.Score}");
}
else if (top.Error.IsRetryable)
{
    // Network, timeout, 5xx or rate limit: try again later
    Debug.Log("Retry in " + top.Error.RetryAfterSeconds + " s");
}
else
{
    Debug.LogWarning(top.Error.Code + ": " + top.Error.Message + " (" + top.Error.RequestId + ")");
}

リトライとレート制限#

SDK は、ネットワークエラーや 5xx レスポンスの際に安全なリクエストを指数バックオフでリトライし、429 レスポンスには Retry-After に従って待機します。

  • 各プロジェクトは1 分あたり 120 リクエストまで送信できます。これを超えると、API は rate_limited を返します。
  • 各アカウントには、プランに応じた1 日あたりのリクエストクォータがあります(制限を参照)。これを超えると、00:00 UTC まで API は quota_exceeded を返します。
  • レスポンスには X-RateLimit-Limit と X-RateLimit-Remaining が含まれ、クォータに近づくと X-RateLimit-Daily-Remaining も含まれます。

リクエスト ID とログ#

すべてのレスポンスには X-Request-ID ヘッダーがあり、すべてのエラーには request_id が含まれます。プロジェクトのログページでこの ID を検索すると、エンドポイント、ステータス、レイテンシ、プレイヤーを確認できます。

ページタイトル、見出し、本文を検索します。

↑↓ で移動 ↵ で開く Esc で閉じる