AgeKit: 通用年龄API

介绍

AgeKit是k-ID的通用年龄API，提供对195+个国家和240+个司法管辖区的数字同意年龄要求和监管信息的即时访问。通过单一API集成，您可以确定是否应显示年龄门控，并了解数字同意和数据处理合规性的本地年龄要求。

该API根据用户的司法管辖区返回全面的年龄门控要求，帮助您实施适当的年龄验证流程、了解当地法规，并在优化用户体验的同时确保全球合规性。

主要功能

• 全球覆盖: 195+个国家和240+个司法管辖区
• 监管智能: 实时访问本地年龄要求
• 隐私优先: 最小化数据处理，不保留个人数据
• 始终最新: 月度监管更新
• 简单集成: 全球合规的单一端点

基础URL

https://game-api.k-id.com/api/v1/

身份验证

所有API请求都需要在Authorization标头中使用Bearer令牌进行身份验证。此令牌在您的AgeKit欢迎邮件中提供。

Authorization: Bearer YOUR_API_KEY

⚠️ 安全最佳实践: 永远不要将您的API密钥包含在客户端代码或前端应用程序中。此端点专为服务器到服务器通信而设计。

端点: 获取年龄门控要求

GET /age-gate/get-requirements

根据玩家的司法管辖区获取显示年龄门控的要求。此端点帮助您确定是否应显示年龄门控、本地年龄要求是什么，以及哪些年龄收集方法在该司法管辖区获得批准。

参数

参数	类型	必需	描述
jurisdiction	string	是	作为ISO 3166-1 alpha-2国家代码（例如："US"）或ISO 3166-2细分代码（例如："US-CA"）的司法管辖区。建议在可用时使用细分代码。

请求示例

cURL

curl -X GET "https://game-api.k-id.com/api/v1/age-gate/get-requirements?jurisdiction=US-CA" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

JavaScript

const axios = require('axios');

async function getAgeGateRequirements(jurisdiction) {
  try {
    const response = await axios.get('https://game-api.k-id.com/api/v1/age-gate/get-requirements', {
      params: { jurisdiction },
      headers: {
        'Authorization': `Bearer ${process.env.AGEKIT_API_KEY}`,
        'Accept': 'application/json'
      }
    });
    
    return response.data;
  } catch (error) {
    console.error('Error fetching age gate requirements:', error.response?.data || error.message);
    throw error;
  }
}

// 用法
getAgeGateRequirements('US-CA')
  .then(result => {
    console.log('Should display age gate:', result.shouldDisplay);
    console.log('Digital consent age:', result.digitalConsentAge);
    console.log('Approved methods:', result.approvedAgeCollectionMethods);
  })
  .catch(error => console.error(error));

Python

import requests
import os

def get_age_gate_requirements(jurisdiction):
    url = "https://game-api.k-id.com/api/v1/age-gate/get-requirements"
    
    headers = {
        "Authorization": f"Bearer {os.getenv('AGEKIT_API_KEY')}",
        "Accept": "application/json"
    }
    
    params = {
        "jurisdiction": jurisdiction
    }
    
    try:
        response = requests.get(url, headers=headers, params=params)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching age gate requirements: {e}")
        raise

# 用法
try:
    result = get_age_gate_requirements("US-CA")
    print(f"Should display age gate: {result['shouldDisplay']}")
    print(f"Digital consent age: {result['digitalConsentAge']}")
    print(f"Approved methods: {result['approvedAgeCollectionMethods']}")
except Exception as e:
    print(f"Error: {e}")

PHP

<?php
function getAgeGateRequirements($jurisdiction) {
    $url = 'https://game-api.k-id.com/api/v1/age-gate/get-requirements';
    $url .= '?' . http_build_query(['jurisdiction' => $jurisdiction]);
    
    $headers = [
        'Authorization: Bearer ' . $_ENV['AGEKIT_API_KEY'],
        'Accept: application/json'
    ];
    
    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("API request failed with status code: $httpCode");
    }
    
    return json_decode($response, true);
}

// 用法
try {
    $result = getAgeGateRequirements('US-CA');
    echo "Should display age gate: " . ($result['shouldDisplay'] ? 'Yes' : 'No') . "\n";
    echo "Digital consent age: " . $result['digitalConsentAge'] . "\n";
    echo "Approved methods: " . implode(', ', $result['approvedAgeCollectionMethods']) . "\n";
} catch (Exception $e) {
    echo "Error: " . $e->getMessage() . "\n";
}
?>

C#

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text.Json;

public class AgeKitClient
{
    private readonly HttpClient _httpClient;
    private readonly string _apiKey;

    public AgeKitClient(string apiKey)
    {
        _apiKey = apiKey;
        _httpClient = new HttpClient();
        _httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
        _httpClient.DefaultRequestHeaders.Add("Accept", "application/json");
    }

    public async Task<AgeGateRequirementsResponse> GetAgeGateRequirementsAsync(string jurisdiction)
    {
        var url = $"https://game-api.k-id.com/api/v1/age-gate/get-requirements?jurisdiction={jurisdiction}";
        
        try
        {
            var response = await _httpClient.GetAsync(url);
            response.EnsureSuccessStatusCode();
            
            var json = await response.Content.ReadAsStringAsync();
            return JsonSerializer.Deserialize<AgeGateRequirementsResponse>(json, new JsonSerializerOptions 
            { 
                PropertyNamingPolicy = JsonNamingPolicy.CamelCase 
            });
        }
        catch (HttpRequestException ex)
        {
            throw new Exception($"Error fetching age gate requirements: {ex.Message}");
        }
    }
}

public class AgeGateRequirementsResponse
{
    public bool ShouldDisplay { get; set; }
    public bool AgeAssuranceRequired { get; set; }
    public int DigitalConsentAge { get; set; }
    public int CivilAge { get; set; }
    public int MinimumAge { get; set; }
    public string[] ApprovedAgeCollectionMethods { get; set; }
}

// 用法
var client = new AgeKitClient(Environment.GetEnvironmentVariable("AGEKIT_API_KEY"));
var result = await client.GetAgeGateRequirementsAsync("US-CA");

Console.WriteLine($"Should display age gate: {result.ShouldDisplay}");
Console.WriteLine($"Digital consent age: {result.DigitalConsentAge}");
Console.WriteLine($"Approved methods: {string.Join(", ", result.ApprovedAgeCollectionMethods)}");

响应格式

成功响应 (200 OK)

{
  "shouldDisplay": true,
  "ageAssuranceRequired": true,
  "digitalConsentAge": 13,
  "civilAge": 18,
  "minimumAge": 0,
  "approvedAgeCollectionMethods": [
    "date-of-birth",
    "age-slider", 
    "platform-account"
  ]
}

响应字段

字段	类型	必需	描述
shouldDisplay	boolean	是	根据当地法规指示是否应向玩家显示年龄门控
ageAssuranceRequired	boolean	是	此司法管辖区的玩家是否需要年龄保证（验证）
digitalConsentAge	integer	是	玩家可以为数据处理提供数字同意的最小年龄
civilAge	integer	是	玩家在此司法管辖区被视为法定成年人的民事/合同年龄
minimumAge	integer	是	访问平台/游戏所需的最小年龄（通常为0，除非有限制）
approvedAgeCollectionMethods	array	是	此司法管辖区玩家年龄信号收集的批准方法列表

年龄收集方法

approvedAgeCollectionMethods数组可能包含：

批准的收集方法	描述
date-of-birth	完整出生日期（YYYY-MM-DD）
age-slider	年龄范围或近似年龄选择
platform-account	使用现有平台账户年龄验证

司法管辖区格式

司法管辖区应提供为：

• ISO 3166-1 alpha-2国家代码: US, GB, DE, AU
• ISO 3166-2细分代码: US-CA, GB-ENG, DE-BY, AU-NSW

建议: 为了更精确的监管合规性，在可用时始终使用细分代码。

错误响应

400

HTTP 400 - Bad Request

{
  "error": "INVALID_INPUT",
  "errorMessage": "Invalid jurisdiction"
}

401

HTTP 401 - Unauthorized

{
  "error": "UNAUTHORIZED",
  "errorMessage": "Unauthorized"
}

429

HTTP 429 - Too Many Requests

最佳实践

安全性

• 永远不要暴露您的API密钥: 保持您的API密钥安全，永远不要将其包含在客户端代码中
• 使用环境变量: 将您的API密钥存储在环境变量中，而不是源代码中
• 仅服务器端: 从您的后端服务器进行所有API调用，而不是从浏览器或移动应用程序
• 仅HTTPS: 始终使用HTTPS进行API请求以保护传输中的API密钥

性能

• 缓存响应: 缓存司法管辖区的年龄门控要求以减少API调用
• 错误处理: 实施适当的错误处理和指数退避重试逻辑

实现

• 处理区域变化: 为了准确的合规性，在可用时使用细分代码（US-CA、GB-ENG）
• 优雅降级: 如果API暂时不可用，要有回退逻辑
• 用户体验: 使用shouldDisplay标志仅在需要时条件性地显示年龄门控