セッションと権限

セッションと権限は、プレイヤーがゲームでアクセスできる機能と能力を決定するk-IDのコアコンセプトです。

セッション

k-ID Sessionには、現在のプレイヤーと場所の権限と年齢ステータスのコレクションが含まれています。すべてのプレイヤーにはアクティブなSessionが必要です。ゲームは、アクティブなSessionを参照して、機能がゲームで許可されているか禁止されているかを決定する必要があります。

セッションの詳細については、セッションを参照してください。

セッションの取得

セッションは2つの方法で取得できます：

• /session/get: sessionIdまたはkuidでセッションを取得する
• /age-gate/check: 年齢ゲートフローの一部としてセッションを作成または更新する

リクエストの例

GET /api/v1/session/get?sessionId=608616da-4fd2-4742-82bf-ec1d4ffd8187&etag=6d9d24fccd428f845b355122799948dd0a52fc5d
Authorization: Bearer your-api-key

/session/get APIは、etagパラメータを使用した条件付きリクエストをサポートします。セッションが最後のリクエスト以降変更されていない場合、APIはHTTP 304（Not Modified）を返し、不要なデータ転送を回避できます。

レスポンスの例

{
  "session": {
    "ageStatus": "LEGAL_ADULT",
    "dateOfBirth": "2005-04-15",
    "etag": "6d9d24fccd428f845b355122799948dd0a52fc5d",
    "jurisdiction": "US-CA",
    "kuid": "123456",
    "permissions": [
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "ai-generated-avatars"
      },
      {
        "enabled": true,
        "managedBy": "PLAYER",
        "name": "text-chat-private"
      }
    ],
    "allowances": [],
    "sessionId": "608616da-4fd2-4742-82bf-ec1d4ffd8187",
    "status": "ACTIVE"
  },
  "status": "PASS"
}

権限

権限は、保護者の同意が必要な場合や年齢制限がある可能性のあるゲーム内の機能または機能を表します。各権限は、以下に基づいてプレイヤーに対して許可または不許可にできます：

• 年齢と管轄区域
• 保護者の同意（必要な場合）
• Compliance Studioでの権限の設定

権限の詳細については、権限を参照してください。

権限の使用

ゲームコードは、各k-ID権限を使用して、ゲーム内の対応する機能へのアクセスを制御する必要があります。権限のenabledフィールドがtrueの場合、これは機能をゲーム内のプレイヤーに対して有効にできることを意味します。enabledフィールドがfalseの場合、機能をオフにする必要があります。

managedByフィールドは、この権限を許可または不許可にできる人を示します：

• PLAYER: プレイヤー自身がこの権限を有効/無効にできる
• GUARDIAN: 信頼できる大人のみがこの権限を有効/無効にできる
• PROHIBITED: この権限は、現在の場所の現在のプレイヤーに対して許可されない

機能が信頼できる大人の同意に関係なく、現在の場所の現在のプレイヤーに対して許可されない場合、managedByフィールドには値PROHIBITEDが含まれます。この場合、ゲームが機能をオフの状態で表示するのではなく、禁止された機能をユーザーエクスペリエンスから完全に削除するのが適切です。

権限のアップグレード

プレイヤーが権限付きのセッションを受信した後、追加の権限を許可したい場合があります。/session/upgrade APIを使用して、追加の権限をリクエストします。

詳細については、権限アップグレードを参照してください。

法的文書とデータ通知の提示

/session/upgrade は、更新された法的文書とデータ通知を提示し、信頼できる大人が同じ同意の場でそれらを確認して承諾できるようにします。提示する文書はリクエストの materialChange で渡します。

• materialChange.termsOfServiceDocument、materialChange.privacyPolicyDocument、materialChange.additionalLegalLinks: 提示する法的文書バリアントの設定済みID。

次のいずれかがリクエストされた場合、文書を確認して承諾できるようにチャレンジが作成されます。

• 保護者の同意を必要とする保護者管理の権限、
• materialChange 内の1つ以上の法的文書、または
• 重要な変更による再同意（下記を参照）。

これらのいずれにも該当しない場合、従来どおりチャレンジなしで権限が直接付与されます。セッションがまだ同意を必要とするデータ通知は自動的に含まれ、チャレンジを承諾すると法的文書とデータ通知の両方について同意が記録されます。

信頼できる大人は承認ページで実際の文書を確認します。解決済みの文書を読み取るには、アップグレードレスポンスの challenge.documents 配列を使用します。各エントリには、バリアントの id、そのローカライズされた name、法的文書の場合は url、および isDataNotice（名前のみのデータ通知の場合は true。データ通知に url はありません）が含まれます。再同意チェーン（priorChallengeId）では、この配列に前のチャレンジの文書が累積されるため、先頭のチャレンジが常に完全なセットを保持します。

期限付きの再同意のリクエスト（重要な変更）

文書が変更され、信頼できる大人に期限までに再承諾してもらう必要がある場合は、アップグレードリクエストの materialChange に acceptanceDeadline を追加します。

• materialChange.acceptanceDeadline: 大人が承諾しなければならない期限（RFC 3339のUTC日時）。任意: 省略すると、期限なしで文書を提示します。設定する場合は、未来の日時である必要があります。
• materialChange.locale: 再同意メールのロケール（デフォルトは en）。

期限を設定すると、アップグレードは能動的で期限付きの再同意になります。チャレンジには期限が付与され（/challenge/get-status から expiresAt として返されます）、信頼できる大人には同じ承認ページへのリンクがメールで送信されます。期限を設定しない場合でも、文書は承認ページで確認のために提示されますが、承諾期限は適用されません。

能動的な再同意と受動的な再同意

acceptanceDeadline を伴う /session/upgrade の materialChange は、アップグレードにバンドルされた能動的な再同意のためのものです。アクセスを制限せずに通知のみ（受動的）のメールを送信するには、専用の /session/send-material-change-notice APIを使用してください。

権限アップグレードウィジェットの使用

k-ID APIを使用してカスタムVPCフローを構築する場合、権限アップグレードウィジェットを使用して、保護者の同意を必要とする追加の権限をプレイヤーがリクエストできるようにします。ウィジェットは、権限アップグレードの同意ワークフローを処理します。

保護者管理セッションのみ

権限アップグレードウィジェットは保護者管理セッションでのみ機能します。プレイヤーのセッションがプレイヤー管理（managedByが"PLAYER"）の場合、チャレンジを作成せずに/session/upgrade APIを直接使用して権限を有効にできるため、ウィジェットは必要ありません。

親の認証が必要

セッション権限管理ウィジェットは、親が認証されたセッションでのみホストする必要があります。ウィジェットは独自の親認証を提供しないため、未成年者に直接提示してはいけません。ウィジェットが認証された親または信頼できる大人にのみ表示されるように常に確認してください。

権限アップグレードの一般的な情報（必要な場合とその仕組みを含む）については、コアコンセプトセクションの権限アップグレードを参照してください。

権限アップグレードウィジェットURLの生成

/widget/generate-manage-session-permissions-url APIを呼び出して、権限アップグレードウィジェットURLを作成します。これにより、信頼できる大人が追加の権限を確認および承認するための一意のURLが返されます。

リクエストの例

POST /api/v1/widget/generate-manage-session-permissions-url
Content-Type: application/json
Authorization: Bearer your-api-key

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "email": "parent@example.com"
}

リクエストパラメータ

プロパティ	説明	必須?
sessionId	セッションのID	はい
email	信頼できる大人のメールアドレス	はい

レスポンスの例

{
  "url": "https://family.k-id.com/widget?token=eyJhbGciOiJFUzM4NCIs..."
}

ウィジェットの埋め込み

返されたURLを使用して、Webサイトまたはアプリにiframeを作成します。信頼できる大人は、このインターフェースを通じて追加の権限を確認および承認できます：

<iframe 
  src="WIDGET_URL" 
  width="100%" 
  height="600"
  frameborder="0">
</iframe>

アップグレード結果の受信

権限アップグレードは、セッションの一部として追跡されます。追加の権限が承認されると、セッションが新しい権限で更新されます。/session/get APIを呼び出してセッションを確認することで、更新された権限を確認できます。

リアルタイム更新については、セッション関連のイベントをリッスンすることもできます：

JavaScriptイベント（クライアント側）

イベント構造の詳細については、Widget.ExitReviewを参照してください。

権限アップグレードウィジェットがiframeに埋め込まれている場合、ウィジェットからのウィンドウメッセージをリッスンできます：

window.addEventListener('message', (event) => {
  if (!event.origin.endsWith('.k-id.com')) {
    return;
  }
  
  const message = event.data;
  
  // ウィジェット完了イベントを処理
  if (message.eventType === 'Widget.ExitReview') {
    // 権限アップグレードフローが完了
    console.log('Permissions upgrade completed');
    handleUpgradeCompleted();
  }
});

Webhooks（サーバー側）

webhookイベント構造の詳細については、Session.ChangePermissionsを参照してください。

セッション関連のイベントを受信するwebhookエンドポイントを設定します。権限がアップグレードされると、セッションの変更がSession.ChangePermissionsイベントに反映されます。詳細については、Webhooksを参照してください。

権限アップグレードとセッション

ウィジェットを通じて権限がアップグレードされると、セッションが新しい権限で更新されます。セッションは、どの権限が有効になっているか、いつ有効になったかを追跡します。/session/get APIを呼び出してセッションを取得することで、更新された権限を確認できます。

権限アップグレードがセッションとどのように連携するかの詳細については、コアコンセプトセクションの権限アップグレードを参照してください。

セッションのキャッシュ

Sessionはローカルストレージまたはクラウドストレージにキャッシュする必要があり、プレイヤーのアカウントに関連付けることができます。k-IDセッションは、親が権限を更新するか、子供やティーンエイジャーが次の年齢カテゴリに「年齢が上がる」か、親またはプレイヤーによって削除された場合にのみ変更されます。

ゲームが起動するたびに/session/get APIからセッションを更新することを推奨しますが、これは明示的に必須ではありません。さらに、k-ID Webhooksを使用して、/session/get APIを呼び出す代わりにSessionの更新を受信できます。

セッションWebhooks

セッション関連のイベントを受信するwebhookを設定します：

• Session.ChangePermissions: 親によって権限が変更されたときに送信される
• Session.Delete: セッションが削除されたときに送信される

詳細については、Webhooksを参照してください。