メインコンテンツに移動

セッションと権限

セッションと権限は、プレイヤーがゲームでアクセスできる機能と能力を決定する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を使用して、追加の権限をリクエストします。

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

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

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

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

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

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

リクエストの例​

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

{
  "challengeId": "ae6d4729-af32-42ea-8ef2-ff46c7664802",
  "email": "parent@example.com"
}

リクエストパラメータ​

プロパティ説明必須?
challengeId/session/upgradeによって作成されたVPCチャレンジの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を設定します：

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