Livedeck 위젯 SDK: 함수와 이벤트
livedeck 객체로 할 수 있는 모든 것: 이벤트, 설정, 이미지, 사운드, 컨텍스트.
SDK는 Livedeck이 모든 위젯 주소의 /sdk/v1.js 경로로 제공하는 작은 라이브러리예요. 위젯을 오버레이에 연결하고 livedeck 객체를 제공해요.
<script src="/sdk/v1.js"></script>내 코드보다 먼저 불러오세요. 페이지가 로드되면 SDK가 알아서 오버레이에 연결을 알려요. 따로 호출할 건 없어요.
함수
livedeck.on(type, fn)
이 타입의 이벤트마다 fn을 호출해요. fn을 다시 제거하는 함수를 반환해요.
livedeck.off(type, fn)
fn을 제거해요.
livedeck.ready(fn)
오버레이가 연결되고 설정이 도착하면 fn을 호출해요. Promise도 반환해요.
livedeck.settings
현재 설정(읽기 전용). 사용자가 무언가를 바꾸면 settings 이벤트가 와요.
livedeck.context
{ mode, format, locale, size, scale, test }. size는 CSS 픽셀 단위의 페이지 크기, scale은 크기 조절된 위젯의 배율이에요(기본값 1). mode는 live(OBS 링크), editor(미리보기), demo(Marketplace) 중 하나예요.
livedeck.host
스트리머의 { handle, nickname, avatar }. host.profile 권한이 있을 때만 제공되고, 없으면 null이에요.
livedeck.image(ref)
이미지 참조(avatar, gift.image)를 로컬 이미지 주소로 바꿔요. 주소 또는 null을 담은 Promise를 반환해요.
livedeck.media.play(key, { volume })
미디어 설정 key의 사운드를 Livedeck을 통해 마스터 볼륨으로 재생해요. volume은 0~1. media.play 권한이 필요해요. true 또는 false를 담은 Promise를 반환해요.
livedeck.media.url(key)
미디어 설정 key의 이미지나 클립의 로컬 주소예요. 주소 또는 null을 담은 Promise를 반환해요.
livedeck.version
"1"
| 호출 | 기능 |
|---|---|
| livedeck.on(type, fn) | 이 타입의 이벤트마다 fn을 호출해요. fn을 다시 제거하는 함수를 반환해요. |
| livedeck.off(type, fn) | fn을 제거해요. |
| livedeck.ready(fn) | 오버레이가 연결되고 설정이 도착하면 fn을 호출해요. Promise도 반환해요. |
| livedeck.settings | 현재 설정(읽기 전용). 사용자가 무언가를 바꾸면 settings 이벤트가 와요. |
| livedeck.context | { mode, format, locale, size, scale, test }. size는 CSS 픽셀 단위의 페이지 크기, scale은 크기 조절된 위젯의 배율이에요(기본값 1). mode는 live(OBS 링크), editor(미리보기), demo(Marketplace) 중 하나예요. |
| livedeck.host | 스트리머의 { handle, nickname, avatar }. host.profile 권한이 있을 때만 제공되고, 없으면 null이에요. |
| livedeck.image(ref) | 이미지 참조(avatar, gift.image)를 로컬 이미지 주소로 바꿔요. 주소 또는 null을 담은 Promise를 반환해요. |
| livedeck.media.play(key, { volume }) | 미디어 설정 key의 사운드를 Livedeck을 통해 마스터 볼륨으로 재생해요. volume은 0~1. media.play 권한이 필요해요. true 또는 false를 담은 Promise를 반환해요. |
| livedeck.media.url(key) | 미디어 설정 key의 이미지나 클립의 로컬 주소예요. 주소 또는 null을 담은 Promise를 반환해요. |
| livedeck.version | "1" |
이벤트
gift
권한: events.gift
필드: user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest
chat
권한: events.chat
필드: user(+ isModerator, isSubscriber, fanLevel), text
like
권한: events.like
필드: user(또는 null), count, total
follow
권한: events.follow
필드: user
share
권한: events.share
필드: user
join
권한: events.join
필드: user
fanclub
권한: events.fanclub
필드: user
viewers
권한: events.viewers
필드: count
stream
권한: stream.status
필드: status: live, offline 또는 checking
settings
권한: 없음
필드: 새 설정
context
권한: 없음
필드: 새 컨텍스트(예: 새 크기)
ready
권한: 없음
필드: 연결 후 한 번
*
권한: 없음
필드: 위의 모든 LIVE 이벤트
| 유형 | 권한 | 필드 |
|---|---|---|
| gift | events.gift | user, gift { id, name, image, diamonds }, count, totalDiamonds, combo { count, ended }, toGuest |
| chat | events.chat | user(+ isModerator, isSubscriber, fanLevel), text |
| like | events.like | user(또는 null), count, total |
| follow | events.follow | user |
| share | events.share | user |
| join | events.join | user |
| fanclub | events.fanclub | user |
| viewers | events.viewers | count |
| stream | stream.status | status: live, offline 또는 checking |
| settings | 없음 | 새 설정 |
| context | 없음 | 새 컨텍스트(예: 새 크기) |
| ready | 없음 | 연결 후 한 번 |
| * | 없음 | 위의 모든 LIVE 이벤트 |
모든 LIVE 이벤트에는 type과 id가 있어요. user는 { handle, nickname, avatar }예요. handle은 @ 없는 TikTok 사용자 이름이고, avatar는 livedeck.image()용 이미지 참조예요. 시청자는 사용자 이름("@" + handle)으로 표시하세요. nickname은 시청자가 직접 입력한 표시 이름이라 실명인 경우가 많으니 표시하지 마세요. 위젯은 TikTok 숫자 ID, 이메일 주소, 링크를 절대 받지 않아요.
{
"type": "gift",
"id": "42",
"user": { "handle": "lena.loops", "nickname": "Lena", "avatar": "i:7" },
"gift": { "id": 5655, "name": "Rose", "image": "i:8", "diamonds": 1 },
"count": 3,
"totalDiamonds": 3,
"combo": { "count": 7, "ended": false },
"toGuest": false
}선물
- gift.diamonds는 선물 하나의 코인 가격이에요. count는 이 이벤트의 새 선물 수이고, totalDiamonds = count × gift.diamonds는 추가되는 코인이에요. 콤보는 이미 정산되어 있으니 count와 totalDiamonds만 더하면 돼요.
- combo는 표시용 연속 선물 전체예요("Rose ×7"): combo.count는 지금까지의 선물 수, combo.ended는 TikTok이 콤보를 끝내면 설정돼요. combo.count를 합산하거나 곱하지 마세요.
- 코인 값은 항상 이벤트에서 가져와요. 자체 가격표를 쓰거나 선물 이름으로 가격을 추측하지 마세요.
- 가장 큰 단일 선물: gift.diamonds를 비교하세요. 최고 후원자 / 리더보드: user.handle별로 totalDiamonds를 합산하세요.
- toGuest는 멀티 게스트 LIVE에서 선물이 게스트에게 간 경우 true예요.
- 특정 선물 하나만 처리하려면 gift 타입 설정을 쓰고 e.gift.id를 그 값과 비교하세요.
좋아요
LIVE 중에 Livedeck은 좋아요를 500ms마다 하나의 이벤트로 묶어요. count는 그 시간 동안의 합계, total은 LIVE 전체 누적 수예요.
예시: 선물 목표
"manifest.json 레퍼런스" 페이지의 manifest.json과 일치해요. 페이지에 #bar와 #label 요소가 있어야 해요.
let total = 0;
let reached = false;
function render() {
const goal = Number(livedeck.settings.goal) || 100;
const bar = document.getElementById("bar");
bar.style.width = Math.min(total / goal, 1) * 100 + "%";
bar.style.background = livedeck.settings.accent;
document.getElementById("label").textContent = total + " / " + goal;
if (!reached && total >= goal) {
reached = true;
if (livedeck.settings.doneSound) livedeck.media.play("doneSound", { volume: 0.8 });
}
}
livedeck.on("gift", (e) => {
const only = livedeck.settings.giftId;
if (only && e.gift.id !== only) return;
total += e.count; // counts gifts; for a diamond goal use e.totalDiamonds
render();
});
livedeck.on("settings", render);
livedeck.ready(render);예시: 프로필 사진이 있는 채팅
livedeck.on("chat", async (e) => {
const row = document.createElement("div");
const img = document.createElement("img");
img.alt = "";
row.append(img, "@" + e.user.handle + ": " + e.text);
document.getElementById("chat").prepend(row);
// picture reference → local address (or null, then it stays empty)
const url = await livedeck.image(e.user.avatar);
if (url) img.src = url;
});알아 두세요
- 이름과 채팅 텍스트는 시청자가 작성해요. 항상 textContent로 넣고, innerHTML은 절대 쓰지 마세요.
- 위젯에는 브라우저 저장소가 없어요. localStorage, sessionStorage, IndexedDB, 쿠키는 차단돼요. 상태는 메모리에 보관하세요. 사용자가 오버레이를 새로고침하면 위젯이 처음부터 다시 시작돼요.
- 로드는 내 패키지에서만 가능해요. 다른 사이트로의 fetch, WebSocket, 프레임, 폼, 팝업, 페이지 이동은 차단돼요.
- 오버레이는 2000ms마다 위젯이 아직 응답하는지 확인해요. 코드가 브라우저를 막지 않는 한 SDK가 알아서 응답해요.
- LIVE 중 위젯은 초당 최대 50개의 메시지를 받아요. 이벤트가 아주 많으면 선물과 채팅이 우선이에요.
- 위젯은 오버레이에 초당 최대 10개의 요청(예: livedeck.image)을 보낼 수 있고, 요청당 최대 64 KB예요. SDK가 이미지를 기억하므로 같은 참조는 한 번만 비용이 들어요.
- livedeck.media.play로 재생한 사운드는 Livedeck 오디오를 거치므로 마스터 볼륨과 사용자가 고른 출력 장치가 적용돼요. 패키지의 사운드를 <audio>로 재생할 수도 있지만, 그러면 Livedeck 볼륨을 거치지 않아요.
- 폰트는 .woff2로 패키지에 넣고 @font-face와 상대 경로로 불러오세요. 이미지를 직접 생성해도 돼요(canvas, data:, blob:).
이 글이 도움이 되었나요?