4단계 리모트 푸시 전송

POST /v1/messages

특정 유저 대상으로 알림 메시지를 즉시 발송합니다. 최대 100명의 유저를 대상으로 지정할 수 있습니다.

Warning

이 작업을 수행하려면 다음 중 하나를 사용해 API 인증을 받아야 합니다: bearerAuth

호출 Parameters

이름	위치	타입	필수	설명
body	body	`CreatePushSendRequest`	true	즉시 발송할 푸시 알림의 대상 식별 정보, 메시지 내용 및 발송 옵션
» category	body	string	true	수신 동의 필터 기준. `INFO`이면 `agreement.info`가 true인 토큰에만, `ADVERTISE`이면 `agreement.advertise`와 `agreement.night`가 모두 true인 토큰에만 발송한다.
» defaultLanguage	body	`LanguageCode`	true	폴백으로 사용할 언어 코드. 이 값에 해당하는 언어 코드 키가 `messages` 맵에 반드시 존재해야 한다.
» identifiers	body	`Identifier[]`	true	푸시 알림을 발송할 대상 유저 식별자 목록. 최대 100명까지 지정할 수 있다.
»» targetPlayerId	body	integer(int64)	true	Hive에서 유저를 식별하는 ID. Hive 인증 응답에서 확인한다.
» messages	body	object	true	언어 코드를 키로 하는 메시지 맵. `defaultLanguage`에 지정한 언어 코드 항목이 반드시 포함되어야 하며, 유저 토큰의 언어 코드와 매칭되는 항목이 없을 때 해당 항목이 폴백으로 사용된다. 언어 코드 키는 `LanguageCode` enum 값만 허용한다 (예: ko, en, ja).
»» additionalProperties	body	`Message`	false	단일 언어의 푸시 메시지 객체.
»»» notification	body	`NotificationContent`	true	사용자에게 표시되는 알림 내용. 모든 OS의 기본값으로 사용된다.
»»»» body	body	string	true	알림 본문.
»»»» image	body	string	false	알림 이미지 URL. Android: 확장 알림(BigPictureStyle) 이미지로 자동 표시된다. iOS: NotificationServiceExtension이 앱에 포함된 경우에만 표시된다. 미포함 시 이미지가 표시되지 않는다. (Reference Kit 참조)
»»»» title	body	string	true	알림 제목.
» options	body	`PushOptions`	false	OS별 알림 전달 및 표시 동작 옵션. 생략 시 각 OS 기본 설정으로 발송한다.
»» android	body	object	false	FCM을 통한 Android 알림 전달 방식 및 표시를 제어하는 옵션
»»» notification	body	object	false	Android 시스템 알림 표시 방식 제어 옵션. notification 필드가 있을 때만 유효하다.
»»»» channelId	body	string	false	Android 알림 채널 ID (Android 8.0+). 앱이 채널을 미리 생성해야 한다. 미지정 또는 없는 채널 ID이면 FCM 기본 채널로 fallback된다.
»»»» clickAction	body	string	false	알림 탭 시 실행할 Intent 액션. 해당 intent-filter를 가진 Activity가 실행된다. 미지정 시 앱의 기본 Activity가 실행된다.
»»»» icon	body	string	false	알림 아이콘 리소스명. 앱의 res/drawable에 포함되어야 한다. 미지정 시 앱 아이콘 사용.
»»»» sound	body	string	false	알림음 리소스명. 앱의 res/raw에 포함되어야 한다.
»»»» tag	body	string	false	알림 태그. 동일 태그의 기존 알림을 교체(덮어쓰기)한다.
»»» priority	body	string	false	FCM 메시지 전달 우선순위. 알림 표시 우선순위(channelId의 importance)와 다른 개념이다. HIGH: Doze 모드에서도 즉시 전달 시도. NORMAL: OS 배터리 최적화 대상.
»» customData	body	`CustomData`	false	언어 코드와 무관하게 전달될 공통 커스텀 데이터. FCM으로만 전달된다.
»»» additionalProperties	body	string	false	none
»» ios	body	object	false	APNs를 통한 iOS 알림 전달 방식 및 표시를 제어하는 옵션
»»» badge	body	integer(int32)	false	앱 아이콘 배지 숫자. APNs aps.badge에 매핑된다.
»»» category	body	string	false	알림 유형 식별자. APNs aps.category에 매핑되며, 앱 시작 시 등록한 UNNotificationCategory 객체 중 하나의 식별자와 일치해야 한다.
»»» sound	body	string	false	알림음 파일명 또는 "default" (시스템 기본 알림음). APNs aps.sound에 매핑된다.
» project	body	object	true	발송 대상 Hive 프로젝트 및 앱 식별 정보
»» appIds	body	[string]	true	프로젝트 내 발송 대상 앱 식별자 목록. 앱은 게임이 서비스하는 OS(Android, iOS 등) 또는 마켓별로 각각 존재하며, 지정한 앱에 등록된 토큰을 대상으로 발송한다. Hive 앱센터에서 확인한다.
»» projectId	body	string	true	Hive 콘솔에서 확인하는 발송 대상 프로젝트 식별자

messages 상세 정보

이름	설명
»» additionalProperties	단일 언어의 푸시 메시지 객체. - `notification`만 제공: OS가 자동으로 알림을 표시한다. 앱 구현 불필요. - `notification` + `Options.customData`: OS가 알림을 표시하고, 앱이 포그라운드 또는 알림 탭 시 Android 앱이 customData를 처리한다. (권장)

Enumerated Values

파라미터	값
» category	INFO
» category	ADVERTISE
» defaultLanguage	ko
» defaultLanguage	en
» defaultLanguage	ja
» defaultLanguage	zh-Hans
» defaultLanguage	zh-Hant
» defaultLanguage	de
» defaultLanguage	fr
» defaultLanguage	ru
» defaultLanguage	it
» defaultLanguage	es
» defaultLanguage	pt
» defaultLanguage	pl
» defaultLanguage	nl
» defaultLanguage	tr
» defaultLanguage	th
» defaultLanguage	id
» defaultLanguage	ar
» defaultLanguage	hi
» defaultLanguage	vi
» defaultLanguage	sv
» defaultLanguage	cs
» defaultLanguage	fa
» defaultLanguage	false
» defaultLanguage	uk
» defaultLanguage	ro
» defaultLanguage	he
» defaultLanguage	ms
» defaultLanguage	da
» defaultLanguage	el
» defaultLanguage	hu
» defaultLanguage	tl
»»» priority	NORMAL
»»» priority	HIGH

호출 예시

curl

# You can also use wget
curl -X POST https://test-api.hiveaxyl.com/push/v1/messages \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer {access-token}' \
  -d '{
  "category": "INFO",
  "defaultLanguage": "en",
  "identifiers": [
    {
      "targetPlayerId": 1001
    },
    {
      "targetPlayerId": 1002
    }
  ],
  "messages": {
    "en": {
      "notification": {
        "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",
        "title": "Maintenance Notice"
      }
    },
    "ko": {
      "notification": {
        "body": "오늘 오후 12시부터 2시까지 서버 점검이 진행됩니다. 이용에 불편을 드려 죄송합니다.",
        "title": "서버 점검 안내"
      }
    }
  },
  "options": {
    "android": {
      "notification": {
        "icon": "ic_notification",
        "sound": "",
        "tag": "maintenance"
      },
      "priority": "HIGH"
    },
    "ios": {
      "badge": 1,
      "sound": "default"
    }
  },
  "project": {
    "appIds": [
      "com.com2us.hivesdk.android",
      "com.com2us.hivesdk.ios"
    ],
    "projectId": "com.com2us.hivesdk"
  }
  }'

응답

상태	의미	설명	스키마
202	Accepted	Accepted	`AcceptedEmptyResponse`
400	Bad Request	Bad Request — 요청 유효성 검사 실패	`AxylBusinessErrorResponse`
401	Unauthorized	Unauthorized — 인증 실패 (토큰 없음 또는 만료)	`AxylBusinessErrorResponse`
403	Forbidden	Forbidden — 해당 리소스에 대한 접근 권한 없음	`AxylBusinessErrorResponse`
500	Internal Server Error	Internal Server Error	`AxylErrorResponse`

응답 예시

202 Accepted요청 본문 필드의 타입이 스키마와 다를 때(예: boolean 필드에 문자열, int64 필드에 문자열) 발생한다. 본문이 역직렬화 단계에서 실패하므로 필드 단위 검증에 도달하지 못하며, 이때 응답에는 errors 배열이 포함되지 않는다. instance는 실제 요청 경로에 따라 달라진다.Bad Request — 요청 유효성 검사 실패Unauthorized — 인증 실패 (토큰 없음 또는 만료)Forbidden — 해당 리소스에 대한 접근 권한 없음Internal Server Error

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

{
  "code": "invalid_parameter",
  "detail": "Request validation failed.",
  "instance": "/v1/tokens",
  "outcome": null,
  "status": 400,
  "title": "Invalid Request",
  "type": "/errors/axyl-push/invalid-parameter"
}

{
  "code": "invalid_parameter",
  "detail": "Request validation failed.",
  "errors": [
    {
      "field": "identifiers",
      "message": "must not be empty"
    },
    {
      "field": "defaultLanguage",
      "message": "must not be blank"
    }
  ],
  "instance": "/v1/messages",
  "outcome": null,
  "status": 400,
  "title": "Invalid Request",
  "type": "/errors/axyl-push/invalid-parameter"
}

{
  "code": "unauthorized",
  "detail": "Authentication token is missing or expired.",
  "instance": "/v1/...",
  "outcome": null,
  "status": 401,
  "title": "Unauthorized",
  "type": "/errors/axyl-push/unauthorized"
}

{
  "code": "forbidden",
  "detail": "You do not have permission to access this resource.",
  "instance": "/v1/...",
  "outcome": null,
  "status": 403,
  "title": "Forbidden",
  "type": "/errors/axyl-push/forbidden"
}

{
  "detail": "An unexpected error occurred.",
  "instance": "/v1/...",
  "status": 500,
  "title": "Internal Server Error",
  "type": "/errors/axyl-push/internal-error"
}