푸시 알림 API

'푸시 알림'에서 앱 서버가 직접 호출하는 Hive Axyl Server API를 설명합니다. 앱 클라이언트는 푸시 알림을 직접 보내지 않으므로, 앱 서버가 이 API로 사용자에게 리모트 푸시 알림을 보냅니다.

리모트 푸시 전송

POST /push/v1/messages

지정한 사용자에게 푸시 알림을 즉시 보냅니다. 한 번의 요청에 최대 100명의 사용자를 지정합니다. 앱에서 특정 이벤트가 발생하거나 조건이 충족된 사용자 한 명 또는 여러 명에게 알림을 보낼 때 호출합니다.

알림은 사용자가 디바이스 토큰 등록으로 등록한 기기에 전달됩니다. 토큰을 등록하지 않은 사용자에게는 알림이 전달되지 않습니다.

API 호출 전 준비

항목	값
호출 주체	`앱 서버`
기본 URL	`https://app-api.hiveaxyl.com`
인증	`Authorization: Bearer {access-token}`

Warning

인증 헤더에는 토큰 발급으로 받은 앱 서버용 토큰을 넣습니다. 사용자의 로그인 토큰으로 호출하면 요청이 거부됩니다. 액세스 토큰과 토큰 발급에 사용하는 Client Secret은 앱 서버에서만 보관하세요.

호출 Parameters

이름	위치	타입	필수	설명
body	body	`CreatePushSendRequest`	`true`	알림을 받을 사용자, 알림 내용, 전달 옵션입니다.

요청 본문 CreatePushSendRequest

필드	타입	필수	설명
`appIds`	`array[string]`	`true`	알림을 보낼 App ID 목록입니다. App ID는 플랫폼이나 스토어마다 따로 만들므로, Android와 iOS 사용자에게 모두 보내려면 각 App ID를 함께 지정하세요. 지정한 App ID에 등록된 토큰에만 알림을 보냅니다. 프로젝트 설정 > App ID에서 확인하며, 1개 이상 50개 이하로 지정합니다.
`identifiers`	`array[object]`	`true`	알림을 받을 사용자 목록입니다. 1명 이상 100명 이하로 지정합니다.
`category`	`string`	`true`	알림 유형입니다. `INFO`는 정보성 알림, `ADVERTISE`는 광고성 알림이며, 사용자의 수신 동의에 따라 알림을 받을 기기가 정해집니다. 자세한 내용은 API별 처리 시 유의 사항을 참조하세요.
`defaultLanguage`	`string`	`true`	기본 언어 코드입니다. 사용자 기기의 언어에 맞는 메시지가 `messages`에 없을 때 이 언어의 메시지를 보냅니다. `messages`에 이 언어 코드의 메시지가 반드시 있어야 합니다.
`messages`	`object`	`true`	언어 코드를 키로, 그 언어의 메시지를 값으로 하는 맵입니다. 메시지를 1개 이상 넣습니다. 사용할 수 있는 언어 코드는 `ko`, `en`, `ja`, `zh-Hans`, `zh-Hant`, `de`, `fr`, `ru`, `it`, `es`, `pt`, `pl`, `nl`, `tr`, `th`, `id`, `ar`, `hi`, `vi`, `sv`, `cs`, `fa`, `no`, `uk`, `ro`, `he`, `ms`, `da`, `el`, `hu`, `tl`입니다.
`options`	`object`	`false`	플랫폼별 알림 전달과 표시 옵션입니다. 생략하면 각 플랫폼의 기본 설정으로 보냅니다. `customData`, `android`, `apns`를 모두 포함한 `options` 전체를 JSON으로 변환한 크기가 1,536바이트를 넘으면 요청이 거부됩니다.

중첩 요청 객체 identifiers[]

필드	타입	필수	설명
`targetPlayerId`	`integer(int64)`	`true`	알림을 받을 사용자의 Player ID입니다.

중첩 요청 객체 messages.{언어 코드}

필드	타입	필수	설명
`notification`	`object`	`true`	사용자에게 표시할 알림 내용입니다. 모든 플랫폼에 같은 내용이 적용됩니다.
`notification.title`	`string`	`true`	알림 제목입니다. 최대 240자입니다.
`notification.body`	`string`	`true`	알림 본문입니다. 최대 420자입니다.
`notification.image`	`string`	`false`	알림 이미지 URL입니다. 최대 512자입니다. Android에서는 확장 알림의 이미지로 표시됩니다. iOS에서는 앱에 Notification Service Extension을 포함한 경우에만 이미지가 표시됩니다.

중첩 요청 객체 options

필드	타입	필수	설명
`customData`	`object`	`false`	앱에 전달할 데이터입니다. 키와 값이 모두 문자열인 쌍을 최대 12개까지 넣으며, 키는 최대 20자, 값은 1자 이상 512자 이하입니다. `customData`를 포함한 `options` 전체 크기는 1,536바이트 이하여야 합니다. Android 기기에만 전달되고 iOS 기기에는 전달되지 않습니다. `from`, `notification`, `message_type`, `google.`로 시작하는 키처럼 시스템이 예약한 키는 사용할 수 없습니다.
`android.priority`	`string`	`false`	Android 기기로 메시지를 전달하는 우선순위입니다. `HIGH`는 기기가 절전 상태인 Doze 모드에서도 즉시 전달을 시도하고, `NORMAL`은 운영 체제의 배터리 최적화 대상이 됩니다. 알림 채널의 표시 중요도와는 다른 값입니다.
`android.notification.channelId`	`string`	`false`	Android 8.0 이상에서 사용할 알림 채널 ID입니다. 앱이 채널을 미리 만들어 두어야 하며, 지정하지 않거나 없는 채널 ID이면 FCM 기본 채널을 사용합니다. 최대 64자입니다.
`android.notification.clickAction`	`string`	`false`	알림을 탭했을 때 실행할 Intent 액션입니다. 해당 intent-filter를 가진 Activity가 실행되며, 지정하지 않으면 앱의 기본 Activity가 실행됩니다. 최대 128자입니다.
`android.notification.icon`	`string`	`false`	알림 아이콘 리소스 이름입니다. 앱의 res/drawable에 포함되어 있어야 하며, 지정하지 않으면 앱 아이콘을 사용합니다. 최대 64자입니다.
`android.notification.sound`	`string`	`false`	알림음 리소스 이름입니다. 앱의 res/raw에 포함되어 있어야 합니다. 최대 64자입니다.
`android.notification.tag`	`string`	`false`	알림 태그입니다. 같은 태그의 알림이 이미 있으면 새 알림으로 교체합니다. 최대 64자입니다.
`apns.sound`	`string`	`false`	iOS와 macOS 기기에서 재생할 알림음 파일 이름입니다. 시스템 기본 알림음을 쓰려면 `default`를 지정합니다. 최대 64자입니다.
`apns.badge`	`integer`	`false`	앱 아이콘에 표시할 배지 숫자입니다. 0 이상이며 기본값은 `1`입니다.
`apns.category`	`string`	`false`	알림 유형 식별자입니다. 앱이 시작할 때 등록한 `UNNotificationCategory` 식별자 중 하나와 일치해야 합니다. 최대 128자입니다.

호출 예시

curl

curl -X POST 'https://app-api.hiveaxyl.com/push/v1/messages' \
  -H 'Authorization: Bearer {access-token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "appIds": ["{android-app-id}", "{ios-app-id}"],
    "identifiers": [
      { "targetPlayerId": 1001 },
      { "targetPlayerId": 1002 }
    ],
    "category": "INFO",
    "defaultLanguage": "en",
    "messages": {
      "en": {
        "notification": {
          "title": "Maintenance Notice",
          "body": "Server maintenance is scheduled from 12:00 to 14:00 UTC. Some services may be unavailable.",
          "image": "https://cdn.example.com/push/maintenance_en.png"
        }
      },
      "ko": {
        "notification": {
          "title": "서버 점검 안내",
          "body": "오늘 오후 12시부터 2시까지 서버 점검이 진행됩니다. 이용에 불편을 드려 죄송합니다."
        }
      }
    },
    "options": {
      "android": {
        "notification": {
          "icon": "ic_notification",
          "tag": "maintenance"
        },
        "priority": "HIGH"
      },
      "apns": {
        "sound": "default",
        "badge": 1
      }
    }
  }'

응답

공통 data, meta, 오류 본문, 제품 공통 오류 코드는 푸시 알림 응답 및 오류를 참조하세요. 이 섹션에서는 이 API가 실제로 반환하는 객체와 API별 처리 방법을 설명합니다.

비동기 요청 접수 응답

202 응답은 알림 전송 요청이 접수되었다는 뜻이며, 사용자 기기에 알림이 도착했다는 뜻은 아닙니다. 응답의 data와 meta는 모두 null입니다.

응답 예시

202 Accepted400 Bad Request

{
  "data": null,
  "meta": null
}

{
  "type": "/errors/common/invalid-parameter",
  "title": "Invalid Parameter",
  "status": 400,
  "detail": "Invalid request parameters.",
  "instance": "/push/v1/messages",
  "code": "invalid_parameter",
  "errors": [
    {
      "field": "identifiers",
      "message": "must not be empty"
    },
    {
      "field": "defaultLanguage",
      "message": "must not be blank"
    }
  ]
}

API별 처리 시 유의 사항

알림은 category에 맞는 수신 동의를 한 기기에만 전달됩니다. INFO는 정보성 알림 수신 동의가 켜진 기기에, ADVERTISE는 광고성 알림 수신 동의와 야간 광고성 알림 수신 동의가 모두 켜진 기기에 전달됩니다. 사용자의 수신 동의는 앱 클라이언트가 수신 동의 변경으로 갱신합니다.

notification만 보내면 운영 체제가 알림을 표시하므로 앱에서 따로 구현할 내용이 없습니다. 알림과 함께 options.customData를 보내면, Android 앱이 포그라운드에 있거나 사용자가 알림을 탭했을 때 앱이 그 데이터를 처리합니다.

응답 상태

상태	콘텐츠 유형	의미	응답 헤더	응답 본문 또는 처리
`202`	`application/json`	알림 전송 요청 접수	-	`data`와 `meta`는 `null`입니다.
`400`	`application/problem+json`	요청 유효성 검사 실패 또는 인가 거부	-	-
`500`	`application/problem+json`	서버 오류	-	-