단일 푸시 발송
API Endpoint
POST /api/push/single
단일 구독자에게 푸시 알림을 발송합니다.
엔드포인트: POST https://api.pushmanager.kr/api/push/single
POST /api/push/single
Content-Type: application/json
X-API-Key: <서비스-API-키>
Origin: <등록된-도메인>
Content-Type: application/json
X-API-Key: <서비스-API-키>
Origin: <등록된-도메인>
Parameters
subscription
대상 구독자의 푸시 서비스 엔드포인트와 암호화에 필요한 키들을 포함하는 구독 객체입니다. 브라우저의
PushManager.subscribe() 메서드로 생성된 표준 웹 푸시 구독 객체를 전달하면 됩니다. endpoint URL과 keys.p256dh, keys.auth가 필수로 포함되어야 합니다.
payload
사용자에게 표시될 알림의 내용을 정의하는 객체입니다. 웹 푸시 Notification API 규격을 따르며, 다양한 시각적 요소와 상호작용 옵션을 설정할 수 있습니다.
필수 속성:
- •
title(String) - 알림 제목 (최대 100자) - •
body(String) - 알림 본문 (최대 300자)
선택 속성:
- •
icon(String) - 알림 아이콘 URL - •
image(String) - 큰 이미지 URL - •
badge(String) - 배지 아이콘 URL - •
url(String) - 클릭 시 이동할 URL - •
tag(String) - 그룹핑용 태그 (최대 50자) - •
requireInteraction(Boolean) - 사용자 상호작용 필요 여부 - •
silent(Boolean) - 무음 알림 여부 - •
data(Object) - 사용자 정의 데이터 - •
actions(Array) - 액션 버튼 배열 (최대 2개)
options
푸시 알림의 전송 방식과 우선순위를 제어하는 웹 푸시 표준 옵션들입니다. 모든 항목은 선택사항이며, 기본값으로도 정상 동작합니다.
- •
TTL(Number) - 메시지 생존 시간(초), 0~2,419,200 (최대 4주) - •
urgency(String) - 우선순위: 'very-low', 'low', 'normal', 'high' - •
topic(String) - 메시지 분류용 토픽 (최대 32자)
Discussion
이 엔드포인트는 구독 정보와 페이로드의 유효성을 검사하고, 서비스의 VAPID 키를 사용하여 인증을 구성한 후 지정된 구독자에게 푸시 알림을 발송합니다. 발송 결과는 자동으로 서비스 통계에 기록되어 모니터링과 분석에 사용됩니다.
요청 제한: API 키당 분당 100회
페이로드 제한: 최대 4KB
인증: 유효한 X-API-Key 헤더와 Origin 검증 필요
페이로드 제한: 최대 4KB
인증: 유효한 X-API-Key 헤더와 Origin 검증 필요
응답 형식
성공 응답 (200 OK)
{
"success": true,
"message": "Push notification sent successfully",
"data": {
"sent": 1,
"failed": 0,
"statusCode": 201,
"payloadSize": 256
}
}
"success": true,
"message": "Push notification sent successfully",
"data": {
"sent": 1,
"failed": 0,
"statusCode": 201,
"payloadSize": 256
}
}
실패 응답 (푸시 발송 실패 시에도 200 응답)
{
"success": false,
"message": "Push notification failed",
"data": {
"sent": 0,
"failed": 1,
"error": "Invalid subscription",
"statusCode": 410,
"retryable": false,
"expired": true
}
}
"success": false,
"message": "Push notification failed",
"data": {
"sent": 0,
"failed": 1,
"error": "Invalid subscription",
"statusCode": 410,
"retryable": false,
"expired": true
}
}
에러 응답 (400/401/403/429/500)
{
"success": false,
"message": "Invalid subscription",
"code": "INVALID_SUBSCRIPTION"
}
"success": false,
"message": "Invalid subscription",
"code": "INVALID_SUBSCRIPTION"
}