Developers
로그인

후원 이벤트

후원 이벤트를 구독하면 채널에서 발생하는 후원을 실시간으로 수신합니다. 현재 채팅 후원(CHAT), 영상 후원(VIDEO), 응원 후원(CHEERING) 세 가지 타입을 지원하며 모두 동일한 구독 엔드포인트로 수신합니다.

구독 엔드포인트: POST /api/openapi/open/v1/sessions/events/subscribe/donation

필요 Scope: READ:DONATION

이벤트 공통 스키마

{
  "event": "DONATION",
  "data": {
    "donationType": "CHAT" | "VIDEO" | "CHEERING",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [
      { "id": "subscribe_tier1", "name": "티어1 구독자", "imageUrl": "https://..." }
    ],
    "payAmount": "10000",
    "donationText": "응원합니다!",
    "emojis": {},
    "cheeringItems": [ /* donationType=CHEERING 일 때만 */ ]
  }
}
필드 타입 설명
donationType string "CHAT" / "VIDEO" / "CHEERING"
channelId string 후원이 발생한 채널의 ID
donatorChannelId string | null 후원자의 채널 ID. 익명 후원 시 null
donatorNickname string | null 후원자 닉네임. 익명 후원 시 null
donatorBadges array 후원자의 뱃지 목록 (없으면 빈 배열)
payAmount string 후원 금액 (빔 단위)
donationText string 후원 메시지. 응원 후원은 메시지가 없으므로 항상 ""
emojis object 이모티콘 토큰과 이미지 URL 매핑
cheeringItems array | undefined 응원 후원일 때만 제공되는 아이템 목록. 아래 스키마 참고

채팅 후원 (donationType: "CHAT")

사용자가 채팅과 함께 후원한 경우.

{
  "event": "DONATION",
  "data": {
    "donationType": "CHAT",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "10000",
    "donationText": "응원합니다!",
    "emojis": {}
  }
}

영상 후원 (donationType: "VIDEO")

영상 링크와 함께 후원한 경우. 현재 donationText에 후원 메시지가 담깁니다.

{
  "event": "DONATION",
  "data": {
    "donationType": "VIDEO",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "30000",
    "donationText": "이 영상 꼭 보세요!",
    "emojis": {}
  }
}

응원 후원 (donationType: "CHEERING")

응원봉·눈꽃·컨페티 등 응원 아이템을 골라 한 번에 여러 개 후원하는 포맷입니다.

  • donationText는 항상 빈 문자열 ("")
  • payAmount는 선택한 아이템들의 빔 합계
  • cheeringItems에 선택한 아이템의 종류·수량·이미지 URL이 포함됨
{
  "event": "DONATION",
  "data": {
    "donationType": "CHEERING",
    "channelId": "12345",
    "donatorChannelId": "67890",
    "donatorNickname": "후원자명",
    "donatorBadges": [],
    "payAmount": "80",
    "donationText": "",
    "emojis": {},
    "cheeringItems": [
      {
        "cnt": 3,
        "type": "CONCERT_1",
        "skinType": "CONCERT",
        "amount": 10,
        "imageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_1.webp",
        "overlayImageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_1_overlay.webp"
      },
      {
        "cnt": 1,
        "type": "CONCERT_4",
        "skinType": "CONCERT",
        "amount": 50,
        "imageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_4.webp",
        "overlayImageUrl": "https://streaming.cf.ci.me/public/assets/images/donation/concert_4_overlay.webp"
      }
    ]
  }
}

cheeringItems[] 필드

필드 타입 설명
cnt number 해당 아이템을 선택한 수량
type string 아이템 타입 코드
skinType string 응원 후원 스킨 타입 (예: CONCERT)
amount number 아이템 개당 빔 금액
imageUrl string 아이템 이미지 URL
overlayImageUrl string 채팅 메시지에 노출되는 아이템 이미지 URL

권장 구현 팁

  • 세 가지 donationType을 switch로 분기하여 UI를 구성하세요.
  • 응원 후원은 cheeringItems[].imageUrl을 그대로 사용해 자체 오버레이 효과를 그릴 수 있습니다. 추가 메타 API를 호출할 필요가 없습니다.
  • payAmount는 문자열이며 단위는 "빔" 입니다. 금액 비교가 필요하다면 Number(payAmount)로 변환해 사용하세요.

미션 후원 이벤트는 현재 지원하지 않습니다.