プラットフォームシグナル詳細

このページはプラットフォーム年齢シグナルの実装に特化したコンパニオンページです。正確なフィールド形式、エンドポイントの動作、およびクライアントまたはサーバー側の統合に直接マッピングできる例が必要な場合に使用してください。

適切なシグナル形式の選択

プラットフォーム	ネイティブシグナルタイプ	k-IDに送信するもの	年齢要件の確認済み？	備考
Apple iOS	数値年齢範囲	`ageLow`、`ageHigh`、オプションの `declarationType`	はい（確認済み宣言タイプの場合）	`category` は送信しないこと
Google Play	数値年齢範囲	`ageLow`、`ageHigh`、オプションの `declarationType`	はい（確認済み宣言タイプの場合）	`category` は送信しないこと
Xbox	カテゴリ	`category`	いいえ	k-IDはプレイヤーの管轄区域を使用してカテゴリを解決する
Meta Horizon	カテゴリ	`category`	いいえ	k-IDはプレイヤーの管轄区域を使用してカテゴリを解決する
k-ID	以前の確認	`verificationId`、オプションで `category` または範囲	はい（確認が有効な場合）	`declarationType` はサーバー側で解決される

ヒント

プラットフォームがすでに ageLow と ageHigh を提供している場合は、それらの値を直接送信してください。カテゴリベースのプラットフォームにのみ POST /age-gate/get-platform-age-range を使用してください。

プラットフォーム固有の統合ガイド

Apple iOS

シグナルの取得方法： Age Range Service を使用してプレイヤーの年齢範囲と宣言タイプを取得します。

k-IDに送信するもの： name、ageLow、ageHigh、およびオプションで declarationType。

確認済み宣言タイプ： paymentChecked、governmentIDChecked、guardianPaymentChecked、guardianGovernmentIDChecked

{
  "name": "apple-ios",
  "ageLow": 18,
  "ageHigh": 25,
  "declarationType": "governmentIDChecked"
}

Google Play

シグナルの取得方法： Play Age Signals API を使用してプレイヤーの年齢範囲と userStatus を取得します。

k-IDに送信するもの： name、ageLow、ageHigh、およびオプションで declarationType。

確認済み宣言タイプ： VERIFIED、SUPERVISED

{
  "name": "google-play",
  "ageLow": 13,
  "ageHigh": 17,
  "declarationType": "VERIFIED"
}

Xbox

シグナルの取得方法： XR-014 と XUserGetAgeGroup を使用してプレイヤーの年齢グループを取得します。

k-IDに送信するもの： name と category。

受け入れるカテゴリ： child、teen、adult

k-IDによる解釈：

child = [0, digitalConsentAge - 1]
teen = [digitalConsentAge, civilAge - 1]
adult = [civilAge, 100]

Xboxシグナルは確認済み年齢権限の確認済みとは見なされません。

{
  "name": "xbox",
  "category": "adult"
}

Meta Horizon

シグナルの取得方法： Get Age Category API を使用して CH、TN、または AD を取得します。

k-IDに送信するもの： name と category。

受け入れるカテゴリ： CH、TN、AD

k-IDによる解釈：

CH = [10, digitalConsentAge - 1]（最小年齢10歳）
TN = [digitalConsentAge, civilAge - 1]
AD = [civilAge, 100]

ブラジルの一般的な設定では、CH=10-12、TN=13-17、AD=18+ となります。

Meta Horizonシグナルは確認済み年齢権限の確認済みとは見なされません。

{
  "name": "meta-horizon",
  "category": "TN"
}

k-ID

シグナルの取得方法： 以前に完了したk-ID確認を使用し、その verificationId を渡します。

k-IDに送信するもの： name: "k-id" と verificationId。フローで必要であれば category または ageLow と ageHigh も送信できますが、シグナルが確認済みかどうかは確認ルックアップによって決まります。

サーバー側の確認チェック： シグナルが確認済みと見なされるのは、確認が以下を満たす場合のみです：

存在する
ステータスが PASS
リクエスト元のプロダクトと同じ組織に属している

呼び出し元が提供した declarationType 値は k-id シグナルでは無視されます。

{
  "name": "k-id",
  "category": "adult",
  "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
}

備考

verificationId は、組織内のプロダクトごとに1つのアクティブセッションに制限されています。同じ確認を同じ組織内の異なるプロダクトで再利用できますが、同じプロダクト内の複数のアクティブセッションでは使用できません。

APIリファレンス

以下の6つのエンドポイントは、プラットフォーム年齢シグナル統合に最も関連しています。各エントリでは、いつ・なぜ呼び出すかを説明します。完全なリクエストおよびレスポンスのスキーマは、APIリファレンスのリンクを参照してください。

`GET /age-gate/get-requirements`

年齢ゲートを表示する前に呼び出します。クエリパラメータとしてプラットフォームシグナルフィールド（platformName、platformAgeLow、platformAgeHigh、platformCategory、platformDeclarationType、platformVerificationId）を渡して、入力を収集する前にk-IDがシグナルを考慮できるようにします。

対応が必要なキーレスポンスフィールド：

shouldDisplay: 確認済みプラットフォームシグナルがプレイヤーが成人であることを証明する場合 false；false の場合は年齢ゲートUIをスキップ
ageAssuranceRequired: すべての確認済み年齢権限がシグナルによってすでに満たされている場合のみ false
permissions: verifiedAgeThreshold を持つ権限をリスト；すべてがすでに満たされている場合でも有用

`GET /age-gate/get-default-permissions`

セッションを作成せずに権限の状態をプレビューする場合に呼び出します。完全な年齢ゲートフローが実行される前に、確認済みシグナルが閾値権限を即座に満たすかどうかを確認するのに役立ちます。

verifiedAgeThreshold を持つ権限はデフォルトで enabled: false
ageLow >= threshold の確認済みシグナルは、これらの権限を enabled: true に設定する
k-id シグナルの場合、宣言タイプは platformVerificationId からサーバー側で解決される

`GET /session/get`

check、VPC、または年齢保証チャレンジ後にセッションを更新します。レスポンスには、確認済みプラットフォームシグナル（または完了した年齢保証）がセッションに記録されている場合に ageVerification オブジェクトが含まれます。確認元を理解するために ageVerification.platformName と ageVerification.declarationType を確認してください。

`POST /age-gate/check`

セッションを作成または更新します。platformAgeSignal をリクエストボディに渡します（単独で、または dateOfBirth、age、kuid と一緒に）。両方が存在する場合、k-IDはより保守的な（低い）年齢を使用します。

プラットフォームシグナルに関連する可能な結果：

確認済みシグナル + 年齢が閾値を満たす： セッションに ageVerification が含まれ、権限は enabled: true
シグナルが存在するが確認されていない： セッションは ageVerification なしで作成；高リスク権限は後で年齢保証が必要
プレイヤーの年齢が閾値未満： 権限は managedBy: PROHIBITED；年齢保証の回復フローが適用される
年齢矛盾： 年齢矛盾検出が有効で、プラットフォームシグナルがプレイヤーの自己申告年齢カテゴリより若い年齢カテゴリを示す場合、400 AGE_CONFLICT を返す

`POST /age-gate/get-platform-age-range`

指定された管轄区域のプラットフォームカテゴリ文字列を具体的な ageLow/ageHigh ペアに変換します。カテゴリベースのプラットフォーム（Xbox、Meta Horizon、k-ID）にのみ必要です。プラットフォームがすでに数値範囲を提供している場合は、この呼び出しをスキップして値を直接送信してください。

`POST /session/upgrade`

プレイヤーの既存のセッションに追加の権限をリクエストします。これは、高リスク権限を即座に解除できるか、年齢保証チャレンジが最初に必要かを決定するエンドポイントです。

返されるチャレンジタイプは、リクエスト内容によって異なります：

シナリオ	返される `challenge.type`
権限が `PLAYER` 管理	チャレンジなし：権限は即座に有効
権限が `GUARDIAN` 管理	`CHALLENGE_SESSION_UPGRADE`（信頼できる大人の同意）
権限に `verifiedAgeThreshold` があり、セッションに `ageVerification` がない	`CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE`（プレイヤーが年齢を確認する必要がある）
権限に `verifiedAgeThreshold` があり、セッションにすでに閾値を満たす `ageVerification` がある	チャレンジなし：権限は即座に有効

主な制約： 1回のアップグレードリクエスト内のすべての権限は同じタイプでなければなりません。verifiedAgeThreshold のある権限とない権限を混在させると 400: "Can't mix permissions with and without verifiedAgeThreshold" が返されます。

例：高リスク権限のリクエスト（年齢保証をトリガー）：

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

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ]
}

例：完了した年齢申し立てからのk-IDシグナルを渡して、新しいチャレンジを作成せずに閾値を直接満たす：

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

{
  "sessionId": "b1a6482d-5242-4b4a-aa88-3fa52595a672",
  "requestedPermissions": [
    { "name": "loot-boxes-paid-gameplay-impacting" }
  ],
  "platformAgeSignal": {
    "name": "k-id",
    "verificationId": "a50f4f73-3c0c-4720-a8b3-ec57ccb0aa34"
  }
}

CHALLENGE_SESSION_UPGRADE_BY_AGE_ASSURANCE チャレンジが返された場合、プレイヤーを challenge.url に誘導してAgeKit+で年齢確認を完了させます。チャレンジが完了したら、更新されたセッションを取得してください：権限は enabled: true となり、セッションに ageVerification オブジェクトが含まれます。

バリデーションとエッジケース

入力バリデーション

シナリオ	結果
`platformAgeSignal` に `name` がない	400: "Platform name must be provided"
不明なプラットフォーム名	400: "Unknown platform name"
`apple-ios` または `google-play` に `category`	400: "Platform must have age range specified"
`category` と `ageLow`/`ageHigh` の両方が提供された	400: "Provide either category or `ageLow` and `ageHigh`, not both"
`ageHigh` なしで `ageLow` のみ（またはその逆）	400: "`ageLow` and `ageHigh` must both be provided"
`ageLow` が `ageHigh` より大きい	400: Invalid range
`session/upgrade` で閾値あり権限と閾値なし権限の混在	400: "Can't mix permissions with and without verifiedAgeThreshold"

年齢矛盾マトリックス

主要な年齢とプラットフォームシグナルの両方が存在する場合：

プラットフォーム年齢カテゴリ＼主要年齢カテゴリ	主要：未成年	主要：青少年	主要：成人
プラットフォーム：未成年	矛盾なし	矛盾	矛盾
プラットフォーム：青少年	矛盾なし	矛盾なし	矛盾
プラットフォーム：成人	矛盾なし	矛盾なし	矛盾なし

矛盾は、プラットフォームがプレイヤーを自己申告の年齢カテゴリより若いと示す場合にのみ発生します。

`k-id` シグナルのセキュリティルール

declarationType は常に verificationId からサーバー側で解決される
呼び出し元が提供した declarationType は無視される
確認は PASS でなければならない
確認はリクエスト元のプロダクトと同じ組織に属していなければならない
有効な verificationId なしでは、k-id シグナルは未確認として扱われる

保守的なデフォルト

shouldDisplay が false でプラットフォームシグナルがない場合は、age: 1 を指定して POST /age-gate/check を呼び出す
プラットフォームシグナルと主要な年齢が一致しないが矛盾しない場合、k-IDはより低い年齢を使用する
確認済み年齢権限は実際に満たされるまでデフォルトで enabled: false

適切なシグナル形式の選択​

プラットフォーム固有の統合ガイド​

Apple iOS​

Google Play​

Xbox​

Meta Horizon​

k-ID​

APIリファレンス​

GET /age-gate/get-requirements​

GET /age-gate/get-default-permissions​

GET /session/get​

POST /age-gate/check​

POST /age-gate/get-platform-age-range​

POST /session/upgrade​

バリデーションとエッジケース​

入力バリデーション​

年齢矛盾マトリックス​

k-id シグナルのセキュリティルール​

保守的なデフォルト​