Push Message API 연동 가이드

API 개요

Push Message API는 모바일 게임, 리모트, 런처 등 앱에 발송 할 푸시메시지를 등록하는 API 입니다.

시작하기

기본 URL

Environment	Endpoint
qa	https://api-qa.pub-dev.hybegames.io
prod	https://api.hybegames.com

모든 API 호출은 HTTPS를 통해 이루어져야 합니다.

인증

• 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.

이름	값	비고
X-Req-Pjid	프로젝트ID	기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key	인증용 키	기술 PM 등에게 전달받은 해당 게임용 인증 키

API 엔드포인트

POST /push/api-in/v1/send-message/{imId}

URL 파라미터:

• imId (필수): 사용자 고유 식별자

Content-Type: application/json

요청 형식

기본 구조

{
  "message": {
    "imId": "string (required)",
    "notification": {
      "title": "string (required)",
      "body": "string (required)"
    },
    "data": { /* optional object */ },
    "android": { /* optional object */ },
    "apns": { /* optional object */ },
    "webpush": { /* optional object */ },
    "apps": ["string"] // optional array
  }
}

필드 상세 설명

필수 필드

• message.imId: 사용자 식별자 (URL 파라미터와 일치해야 함)

• message.notification.title: 푸시 알림 제목

• message.notification.body: 푸시 알림 내용

선택 필드

• message.data: 앱에서 사용할 커스텀 데이터 (임의의 JSON 객체)

• message.android: Android 특화 설정

• message.apns: iOS APNS 특화 설정

• message.webpush: Web Push 특화 설정

• message.apps: 대상 앱 목록 (["game", "remote", "launcher"] 중 선택)

  • 비어있는 Array나 해당 필드를 포함하지 않으면 모든 대상에 발송됩니다.

요청 예시

기본 푸시 메시지

{
  "message": {
    "imId": "AVBXHNEBAV4FLRZQ4RLZ",
    "notification": {
      "title": "새 메시지가 도착했습니다",
      "body": "친구가 메시지를 보냈습니다"
    }
  }
}

커스텀 데이터 포함

{
  "message": {
    "imId": "AVBXHNEBAV4FLRZQ4RLZ",
    "notification": {
      "title": "게임 이벤트",
      "body": "특별 보상을 받으세요!"
    },
    "data": {
      "event_type": "special_reward",
      "reward_id": "reward_001",
      "expires_at": "2024-12-31T23:59:59Z"
    },
    "apps": ["game"]
  }
}

플랫폼별 설정

{
  "message": {
    "imId": "AVBXHNEBAV4FLRZQ4RLZ",
    "notification": {
      "title": "중요 알림",
      "body": "긴급 업데이트가 있습니다"
    },
    "android": {
      "priority": "high",
      "ttl": "3600s",
      "notification": {
        "icon": "myicon",
        "color": "#ff0000"
      }
    },
    "apns": {
      "headers": {
        "apns-priority": "10",
        "apns-expiration": "1735689599"
      },
      "payload": {
        "aps": {
          "badge": 1,
          "sound": "default"
        }
      }
    }
  }
}

응답 형식

성공 응답

HTTP Status Code: 200 OK

{
  "resultCode": "SUCCESS",
  "resultMessage": "Message successfully queued for processing",
  "resultData": {
    "messageId": "12345678-1234-1234-1234-123456789012",
    "imId": "AVBXHNEBAV4FLRZQ4RLZ"
  }
}

실패 응답

HTTP Status Code: 200 OK

{
  "resultCode": "ERROR_CODE",
  "resultMessage": "에러 메시지",
  "resultData": {
    "details": "상세 에러 메시지 내용"
  }
}

에러 처리

에러 코드 목록

에러 코드	설명	해결 방법
INVALID_REQUEST_FORMAT	요청 형식이 올바르지 않음	JSON 구조와 필수 필드 확인
IMID_MISMATCH	URL 파라미터와 본문의 IMID 불일치	URL과 본문의 imId 값 일치시키기
INTERNAL_SERVER_ERROR	내부 서버 오류	잠시 후 재시도하거나 관리자 문의
NOT_FOUND	엔드포인트를 찾을 수 없음	URL 경로 확인
MISSING_HEADER	인증 헤더를 찾을 수 없음	인증 헤더를 추가
NOT_ALLOW_AUTH	잘못된 인증 정보	올바른 인증 정보로 요청

트러블슈팅

IMID_MISMATCH 에러

문제: URL 파라미터의 imId와 요청 본문의 imId가 다름

해결:

// 잘못된 예시
fetch('/push/api-in/v1/send-message/AVBXHNEBAV4FLRZQ4RLZ', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: { imId: 'DMWYJZ3HWSGJR5TYUXGP', ... }  // 불일치!
  })
});

// 올바른 예시
fetch('/push/api-in/v1/send-message/AVBXHNEBAV4FLRZQ4RLZ', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    message: { imId: 'AVBXHNEBAV4FLRZQ4RLZ', ... }  // 일치!
  })
});

INVALID_REQUEST_FORMAT 에러

문제: 필수 필드 누락 또는 잘못된 데이터 타입

해결:

• message.notification.title과 message.notification.body 필수 확인

• apps 배열에는 올바른 값만 포함 ("game", "remote", "launcher")

• JSON 구조 검증

메시지가 전송되지 않음

문제: API는 성공하지만 실제 푸시가 도착하지 않음

해결:

• 기술PM에 관리자 문의

• 대상 디바이스의 푸시 알림 설정 확인

메시지가 느리게 전송 됨

문제: API는 성공하지만 푸시메시지가 느리게 도착 함

해결:

• 기술PM에 관리자 문의