연동 준비사항

싱글 푸시 API를 연동하려면 인증토큰(API KEY)을 발급받아야 합니다. 토큰을 이미 발급받았다면 추가할 권한만 요청합니다. HIVE Server API > 노티피케이션 > 푸시 v4 > 인증에서 인증토큰 발급과 요청 방법을 확인하세요.

환경별 접근 URL

서버 URL
Production https://notification.withhive.com
Sandbox https://sandbox-notification.withhive.com

기본 정보 및 요청 변수

Method POST
URL /push/send
구분 필드명 설명 타입 필수여부
Header Content-Type application/json;charset=utf-8
Authorization bearer {{API KEY}}
Body notice 공지 알림 설정여부 (기본값: false)

true

  • 공지 알림으로 발송
  • 수신 동의 여부에 따라 발송

false

  • 게임 알림으로 발송
  • 수신 동의 여부에 관계없이 발송

수신 동의 항목은 공지 알림과 야간 알림으로 이루어져 있음

  • 대상자가 공지 알림 수신에 동의하지 않으면 공지로 설정된 모든 알림 메시지가 발송되지 않음
  • 야간 알림 수신 동의는 공지 알림 수신에 동의한 경우에만 적용되므로 동의하지 않으면 공지로 설정된 모든 알림 메시지가 야간에 발송되지 않음. 야간은 오후 9시부터 다음날 오전 8시 사이를 의미
 Boolean O
identifiers 식별자 정보 (최대 100개)identifier 구조와 예제는 아래에서 확인 identifier[] O
game gameid 게임ID String O
appids AppID 목록
식별자에 매핑되는 AppID가 유효하지 않을 경우 미발송 처리

권장사항

  • 기기 기반 식별자(did)일 경우: 매핑되는 AppID를 추가
  • 계정 기반 식별자(playerId, vid, uid)일 경우: 매핑되는 모든 AppID 목록을 추가
  • 다양한 식별자가 존재할 경우: identifier 구조에서 우선순위 확인
 String[] X
enableLocale 언어 로케일 적용 여부

true

  • 푸시 발송 대상자가 설정한 언어와 동일한 언어로 메시지를 전송. 토큰 정보와 함께 저장된 언어 코드를 기준으로 함
  • 토큰 저장 시 언어를 결정하는 기준
  • 1순위: 게임 언어
  • 2순위: 기기 언어 (전달된 게임 언어가 없을 경우)

false

  • 언어 로케일은 무시하고 payload의 single값을 통해서만 발송
 Boolean O
payload single enableLocale=false일 경우 single 필드로 요청 Message 구조는 아래에서 확인 Message O
defaultLanguage enableLocale=true일 경우 기본 언어로 설정 String
locale {{LANGUAGE}} enableLocale=true일 경우 locale 필드로 설정single 필드 Message 정보와 동일 Message
option Option 정보는 아래에서 확인 Option X
  • identifier 구조
    구분 필드명 설명 타입 필수여부
    identifier identifier playerId 4가지 중 하나 이상으 반드시 포함되어야 함적용 우선순위는 playerId, vid, uid, did 순 Long O
    vid
    uid
    did
  • identifier 예제
  • Message 구조
    구분 필드명 설명 타입 필수여부
    Message android title 제목 String O
    message 본문 String O
    messageExpanded 본문 확장 String O
    imageUrl 이미지 경로 String X
    ticker 티커 String X
    summaryText 본문 간략히 String X
    ios title 제목 String O
    message 본문 String O
    mediaUrl 이미지 경로 String X
    facebook title 제목 (1~30자 이내) String O
    body 본문 (10~180자 이내) String O
    media 이미지 URL String O
  • Option 정보
    구분 필드명 설명 타입 필수여부
    Option badge 푸시를 수신할 때 앱 아이콘 위에 표시하는 숫자값(기본값: 1) Integer X
    overwrite Android의 푸시 덮어쓰기 기능 사용 여부(기본값: false) Boolean X
    collapseKey 푸시 덮어쓰기 기능을 사용할 때 키값(숫자의 문자열 형식: “123”) String X
    engagement 유저인게이지먼트 String X
    comment 문구 String X
    groupKey iOS와 Android OS 사용 기기에서 알림 수신 시, 알림을 같은 그룹끼리 묶어 노출하기 위한 그룹 키 값입니다. 기기 OS에 설정된 알림 옵션이 기본 적용됩니다. 옵션에 관한 자세한 내용은 아래 문서를 참고하세요.

    		 String X
    android icon 유저 기기에 푸시 알림이 뜰 때 노출되는 아이콘 이미지 파일명입니다. 이미지 파일은 /src/main/res/drawable에 존재해야 합니다. 지원하는 이미지 파일 형식은 다음을 확인하세요.
    웹에 있는 이미지를 노출하고 싶다면 이미지 파일명 대신 이미지 URL을 이 필드에 입력하세요. 이 필드가 비어있으면 앱 아이콘 이미지를 노출합니다.     		String X
    sound 유저 기기에 푸시 알림이 뜰 때 재생할 알림 음원 파일명입니다. 앱 번들에 포함된 음원 파일을 지정할 수 있으며 음원 파일은 /src/main/res/raw에 존재해야 합니다. 이 필드가 비어있으면 시스템 기본 음원을 사용합니다. String X
    priority Android 기기로 전송할 메시지의 우선순위입니다. 이 우선순위는 메시지 전송 시기를 제어하는 FCM 개념입니다. NORMAL 또는 HIGH 값을 가질 수 있으며, 기본값은 NORMAL 입니다. 자세한 내용은 Firebase 가이드를 참고하세요.

    • NORMAL = 데이터 메시지의 기본 우선순위입니다. 보통 우선순위 메시지는 기기가 절전 모드가 아닐 때 즉시 전송됩니다. 기기가 잠자기 모드일 때는 기기가 잠자기 모드를 종료할 때까지 배터리를 절약하기 위해 전송이 지연될 수 있습니다. 새로운 이메일 알림, UI 동기화 유지, 백그라운드 앱 데이터 동기화와 같이 시간이 크게 중요하지 않은 메시지의 경우 보통 전송 우선순위를 선택하세요.
    • HIGH = FCM이 높은 우선순위 메시지를 즉시 전송하려고 시도하며 필요한 경우 FCM에서 기기의 절전 모드를 해제하고 매우 제한된 네트워크 액세스를 포함하여 제한된 일부 처리 작업을 실행할 수 있습니다. 높은 우선순위 메시지는 대개 사용자가 앱 또는 알림과 상호작용하는 과정을 포함합니다.
    		 enum(NORMAL, HIGH) X
    ios sound 유저 기기에 푸시 알림이 뜰 때 재생할 알림 음원 파일명입니다. 음원 파일은 앱 컨테이너의 Library/Sounds 또는 앱 메인 번들에 존재해야 합니다. 이 필드가 비어있으면 “default”로 자동 설정되며 유저 애플 기기 시스템 기본 음원을 사용합니다. String X

출력 결과

구분 필드명 설명
Header Content-Type application/json;charset=utf-8
UUID {{UUID}}
Body – 성공일 경우 Body는 비어있음

응답 상태 코드

키 값 설명
200 성공 (Body는 비어있음)
400 Bad Request POST 데이터 누락JSON 포맷 오류데이터 내 필수 요소가 누락되었거나 유효하지 않음
401 Unauthorized 요청 메시지의 Authorization 헤더가 누락되었거나 그 값이 유효하지 않음인증토큰(API KEY)이 등록되어 있지 않음해당 API로의 접근 권한 없음
403 Forbidden Authorization 헤더의 인증 스킴이 “Bearer”가 아님 (현재 Bearer만 지원)
404 Not Found 요청 URL이 잘못되었음
500 Internal Server Error 서버 내부적으로 문제가 발생함
502 Bad Gateway 푸시 게이트웨이 서버 과부하네트워크가 잘못된 연결을 시도하였음
503 Service Unavailable API 서버 또는 인증 서버 다운 상태

예제코드

    • 호출 (“enableLocale”:false)
    • 호출 (“enableLocale”:true)

 

  • 요청
  • 응답

 

⇡ Go to top