이용 정지 알림 게임 서버 등록¶

이용 정지 사용자 정보를 신규 등록하거나 변경하거나 제재를 해제할 때 해당 데이터를 게임 서버로 실시간 자동 발송하는 API입니다. 게임 서버는 이 API를 통해 사용자의 제재 상태 변화를 즉시 수신하여 서비스에 반영합니다.

• 데이터 전달 시점: 이용 정지 사용자의 정보가 새로 등록되거나 변경될 때, 그리고 이용 정지가 해제될 때 자동으로 게임 서버로 전달됩니다. 이용 정지 해제는 관리자가 직접 해제한 경우와 이용 정지 기간이 만료된 경우를 모두 포함하며, 두 경우 모두 status가 E로 전달됩니다.
• 데이터 전송 단위: 한 번의 요청(Request)으로 최대 100건의 이용 정지 사용자 정보가 전송됩니다. 다만 동일한 사용자의 처리 순서를 보장하기 위해 사용자를 여러 그룹으로 나누어 전송하므로, 대상이 많더라도 항상 100건을 채워서 전송되지는 않습니다. 요청 횟수와 요청당 건수는 대상 사용자의 분포에 따라 달라집니다.

이 API를 사용하려면 요청(Request)을 받을 수 있도록 게임 서버를 준비한 후, Hive 콘솔 > 인증 > 이용 정지 > 게임 서버 등록에서 게임 서버를 등록해야 합니다.

Request URL¶

Request header¶

Request body¶

Request example¶

한 번의 요청에 담기는 data는 모두 같은 status와 같은 event_time을 가집니다. 서로 다른 상태가 한 요청에 섞여서 전달되지 않습니다.

기간 이용 정지 (B)¶

{
  "game_index": 539,
  "server_url": "{Hive 콘솔에 등록한 프로젝트의 게임 서버 URL}",
  "data": [
    {
      "event_time": 1720612623847,
      "player_id": 1,
      "status": "B",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "2024-07-13 20:56:59"
    },
    {
      "event_time": 1720612623847,
      "player_id": 2,
      "status": "B",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "2024-07-13 20:56:59"
    }
  ]
}

영구 이용 정지 (P)¶

{
  "game_index": 539,
  "server_url": "{Hive 콘솔에 등록한 프로젝트의 게임 서버 URL}",
  "data": [
    {
      "event_time": 1720612624215,
      "player_id": 3,
      "status": "P",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "9999-12-31 00:00:00"
    },
    {
      "event_time": 1720612624215,
      "player_id": 4,
      "status": "P",
      "start_date": "2024-07-10 20:56:59",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

이용 정지 해제 (E)¶

해제된 이용 정지의 기간이 그대로 전달되므로, start_date와 end_date는 사용자마다 다를 수 있습니다.

{
  "game_index": 539,
  "server_url": "{Hive 콘솔에 등록한 프로젝트의 게임 서버 URL}",
  "data": [
    {
      "event_time": 1720829722391,
      "player_id": 5,
      "status": "E",
      "start_date": "2024-07-01 10:00:00",
      "end_date": "2024-07-08 10:00:00"
    },
    {
      "event_time": 1720829722391,
      "player_id": 6,
      "status": "E",
      "start_date": "2024-07-03 15:30:00",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

처리 순서 판별하기¶

event_time은 Hive 서버가 해당 정보를 발행한 시각을 epoch 밀리초(1970년 1월 1일 00:00:00 UTC부터 흐른 밀리초)로 나타낸 값입니다. 예를 들어 1720612623847은 KST 기준 2024-07-10 20:57:03.847입니다. 값이 클수록 나중에 발생한 처리이므로, 게임 서버는 이 값을 비교해 요청이 도착한 순서와 관계없이 최신 상태를 판별할 수 있습니다.

player_id별로 마지막에 반영한 event_time을 저장해 두고, 새로 수신한 값과 비교해 아래와 같이 처리하세요.

수신한 값이 최신 상태인지 확실히 확인해야 한다면 게임 이용 정지 사용자 확인하기 API로 해당 사용자의 현재 상태를 조회하세요.

Response body¶

게임 서버는 요청을 정상적으로 처리한 후 아래 형식으로 응답해야 합니다.

응답 코드¶

Response example¶

성공¶

{
  "result_code": 0
}

게임 서버 상태 확인¶

등록된 게임 서버가 이용 정지 사용자 정보를 수신할 수 있는 상태인지 확인하기 위해 일정한 간격으로 상태 확인 요청을 전송합니다. 요청 URL과 요청 헤더, 요청 본문의 형식은 실제 이용 정지 사용자 정보 전달과 동일합니다.

전송 간격은 운영 상황에 따라 조정될 수 있습니다. 따라서 게임 서버가 특정 주기를 가정하고 구현해서는 안 됩니다. 요청 수신 시점과 관계없이 항상 정상 응답을 반환할 수 있어야 합니다.

상태 확인 요청의 data 필드에는 아래와 같이 player_id가 1인 더미 데이터 한 건만 포함되어 전달됩니다.

• player_id: 1 (실제 존재하지 않는 더미 ID)
• event_time / start_date: 상태 확인 요청을 발송한 시각
• 예외 처리 필수: player_id가 1인 요청은 수신 가능 여부만 확인하기 위한 신호입니다. 실제 이용 정지 로직을 수행하지 않아야 하며, 처리 순서 판별 대상에서도 제외해야 합니다.

{
  "game_index": 539,
  "server_url": "{Hive 콘솔에 등록한 프로젝트의 게임 서버 URL}",
  "data": [
    {
      "event_time": 1720612623847,
      "player_id": 1,
      "status": "P",
      "start_date": "2024-07-10 20:57:03",
      "end_date": "9999-12-31 00:00:00"
    }
  ]
}

게임 서버는 상태 확인 요청에도 result_code를 포함한 응답을 반환해야 합니다. result_code의 값은 확인하지 않고 필드가 있는지만 확인하므로, 존재하지 않는 사용자로 판단해 실패 코드(0 이외의 값)를 반환해도 정상 응답으로 처리됩니다.