왜 Node.js인가요?
Node.js는 TikTok LIVE 연동에 가장 많이 쓰이는 런타임이에요. 공식 @tiktool/live SDK는 TypeScript로 작성돼 npm에 배포되며, 전체 타입 정의가 기본으로 들어 있어요. 이런 장점이 있어요:
- 타입 안전성 - 모든 이벤트와 메서드에 대한 완전한 TypeScript 정의
- 자동 재연결 - 연결이 끊기면 SDK가 자동으로 처리
- 이벤트 기반 - 익숙한
.on('event', handler)패턴 - 어디서나 작동 - Node.js 18+, Bun, Deno
SDK 설치
npm install @tiktool/live다른 패키지 매니저로도 설치할 수 있어요:
# Yarn
yarn add @tiktool/live
# pnpm
pnpm add @tiktool/live
# Bun
bun add @tiktool/live빠른 시작: 코드 3줄로 실시간 데이터
app.mjs 파일을 만들고 붙여 넣으세요:
import { TikTokLive } from '@tiktool/live'
const client = new TikTokLive({
uniqueId: 'tv_asahi_news', // TikTok username (without @)
apiKey: process.env.TIKTOOL_API_KEY
})
client.on('chat', (event) => {
console.log(`${event.nickname}: ${event.comment}`)
})
await client.connect()실행하세요:
TIKTOOL_API_KEY=your_api_key node app.mjs몇 초 안에 터미널에 채팅 메시지가 들어오는 게 보여요.
사용 가능한 모든 이벤트
SDK는 방송의 모든 상호작용을 구조화된 이벤트로 보내 줘요:
import { TikTokLive } from '@tiktool/live'
const client = new TikTokLive({
uniqueId: 'target_username',
apiKey: process.env.TIKTOOL_API_KEY
})
// Chat messages
client.on('chat', (event) => {
console.log(`[CHAT] ${event.nickname}: ${event.comment}`)
})
// Virtual gifts (Rose, Universe, etc.)
client.on('gift', (event) => {
console.log(`[GIFT] ${event.nickname} sent ${event.giftName} (${event.diamondCount} 💎)`)
})
// New followers
client.on('follow', (event) => {
console.log(`[FOLLOW] ${event.nickname} just followed!`)
})
// Likes
client.on('like', (event) => {
console.log(`[LIKE] ${event.nickname} liked (total: ${event.totalLikeCount})`)
})
// Viewer count changes
client.on('viewer_count', (event) => {
console.log(`[VIEWERS] ${event.viewerCount} watching`)
})
// Member joins (someone enters the stream)
client.on('member', (event) => {
console.log(`[JOIN] ${event.nickname} joined the stream`)
})
// Share events
client.on('share', (event) => {
console.log(`[SHARE] ${event.nickname} shared the stream`)
})
await client.connect()
console.log('✅ Connected and listening!')예상 출력
✅ Connected and listening!
[VIEWERS] 3,412 watching
[CHAT] viewer_1: Hello everyone! 👋
[FOLLOW] new_fan just followed!
[GIFT] whale_user sent Universe (34,000 💎)
[LIKE] cool_viewer liked (total: 12,847)
[CHAT] fan_123: Love this stream!
[JOIN] curious_viewer joined the stream
[SHARE] supporter_1 shared the streamTypeScript 지원
SDK는 TypeScript로 작성됐어요. 타입이 자동으로 포함돼서 @types 패키지는 필요 없어요:
import { TikTokLive } from '@tiktool/live'
import type { ChatEvent, GiftEvent } from '@tiktool/live'
const client = new TikTokLive({
uniqueId: 'target_username',
apiKey: process.env.TIKTOOL_API_KEY
})
client.on('chat', (event: ChatEvent) => {
// event.comment, event.nickname, event.userId - all typed
console.log(event.nickname, event.comment)
})
client.on('gift', (event: GiftEvent) => {
// event.giftName, event.diamondCount, event.repeatCount - all typed
if (event.diamondCount >= 100) {
console.log(`Big gift from ${event.nickname}!`)
}
})
await client.connect()Raw WebSocket (SDK 없이)
raw WebSocket을 직접 쓰고 싶나요? 어떤 언어나 프레임워크에서든 작동해요:
import WebSocket from 'ws' // npm install ws
const ws = new WebSocket(
'wss://api.tik.tools?uniqueId=tv_asahi_news&apiKey=YOUR_API_KEY'
)
ws.on('message', (raw) => {
const msg = JSON.parse(raw.toString())
switch (msg.event) {
case 'chat':
console.log(`${msg.data.user.nickname}: ${msg.data.comment}`)
break
case 'gift':
console.log(`Gift: ${msg.data.giftName} (${msg.data.diamondCount} 💎)`)
break
case 'viewer_count':
console.log(`Viewers: ${msg.data.viewerCount}`)
break
}
})
ws.on('open', () => console.log('Connected!'))FAQ
TikTok에 공식 Node.js API가 있나요?
없어요. TikTok은 LIVE 방송 데이터용 공개 API를 제공하지 않아요. TikTools API는 채팅, 선물, 시청자 등 LIVE 이벤트에 안정적으로 실시간 접근할 수 있게 해 주는 서드파티 관리형 서비스예요. @tiktool/live npm 패키지가 이 API의 공식 SDK예요.
무료인가요?
네. Sandbox 요금제로 하루 요청 5,000건과 동시 WebSocket 연결 3개를 무료로 쓸 수 있어요. 평가 전용이며 신용카드는 필요 없어요. 여기서 가입하세요.
Express, Fastify, Next.js에서도 쓸 수 있나요?
네. SDK는 모든 Node.js 환경에서 작동해요. Express 라우트 핸들러, Fastify 플러그인, Next.js API 라우트, 단독 스크립트 어디서든 쓰세요.
Bun과 Deno에서도 작동하나요?
네. SDK는 Bun, Deno와 호환돼요. bun add @tiktool/live 명령으로 설치하거나, Deno에서는 npm에서 import하세요.