@nowsoft-lab/chear-widget-react
v2.0.0
Published
치어(CHEAR) 위젯 — 플레이어 · 채팅을 리액트 컴포넌트로. <ChearPlayer channel="…" />
Maintainers
Readme
@nowsoft-lab/chear-widget-react
치어(CHEAR) 라이브 방송의 플레이어와 채팅을 리액트 앱에 컴포넌트로 넣습니다. 채널 키(channelKey) 하나만 넘기면 스튜디오 › 위젯과 같은 화면 · 같은 동작이 나오고, 위젯이 개선되면 이 패키지를 다시 설치하지 않아도 같이 바뀝니다.
import { ChearPlayer, ChearChat } from "@nowsoft-lab/chear-widget-react";
export default function Live() {
return (
<div style={{ display: "flex", gap: 16 }}>
<ChearPlayer channelKey="3kTq9ZbW0x" style={{ flex: 1 }} />
<ChearChat channelKey="3kTq9ZbW0x" style={{ width: 360, height: 600 }} />
</div>
);
}- API 키 · 백엔드 연동 없이 바로 씁니다.
- 방송 중이면 재생, 아니면 채널 프로필과 "방송 준비 중"을 보여 줍니다. 방송이 시작되면 저절로 재생으로 바뀝니다.
- 채팅은 읽기만이 아니라 실제로 채팅합니다 — 로그인 · 가입 · 이모티콘 · 신고 · 팔로우가 위젯 안에서 됩니다.
- 위젯은 Shadow DOM 안에 그려져 내 사이트 스타일과 서로 섞이지 않습니다.
설치
npm i @nowsoft-lab/chear-widget-react
# 또는
pnpm add @nowsoft-lab/chear-widget-react
yarn add @nowsoft-lab/chear-widget-react- React 18 이상(18 · 19).
- ES 모듈만 제공합니다(Vite · Next.js · webpack 5 · Rspack 등 요즘 번들러는 그대로 됩니다).
- 타입(TypeScript) 포함.
컴포넌트
<ChearPlayer> — 방송 플레이어
<ChearPlayer channelKey="3kTq9ZbW0x" />
<ChearPlayer channelKey="3kTq9ZbW0x" chat /> {/* 오른쪽에 채팅 같이 */}
<ChearPlayer channelKey="3kTq9ZbW0x" muted={false} autoplay={false} />| prop | 타입 | 기본 | 설명 |
|---|---|---|---|
| channelKey | string | 필수 | 채널 키 — 채널마다 고정된 영숫자 10자(대소문자 구분). 스튜디오 › 위젯에서 복사하거나 API 채널 응답의 channelKey. 스트리머가 @아이디를 바꿔도 그대로예요 |
| autoplay | boolean | true | 자동 재생. 브라우저 정책상 소리 끔과 함께일 때만 확실합니다 |
| muted | boolean | true | 소리 끔으로 시작. 화면의 "소리 켜기"로 켤 수 있습니다 |
| controls | boolean | true | 재생 컨트롤 표시 |
| chat | boolean | false | 플레이어 오른쪽에 채팅을 같이(좁은 세로 화면은 아래). 컨트롤의 채팅 단추로 접고 펼칩니다 |
| stats | boolean | true | 왼쪽 위 LIVE · 시청 중 표시 |
크기 — 기본은 부모 폭 100% · 16:9 입니다. 폭만 정하면 높이는 따라옵니다.
<ChearPlayer channelKey="3kTq9ZbW0x" style={{ width: 640 }} /> {/* 640 × 360 */}
<ChearPlayer channelKey="3kTq9ZbW0x" className="my-player" /> {/* CSS 로 */}<ChearChat> — 채팅
<ChearChat channelKey="3kTq9ZbW0x" style={{ width: 360, height: 600 }} />
<ChearChat channelKey="3kTq9ZbW0x" theme="light" />| prop | 타입 | 기본 | 설명 |
|---|---|---|---|
| channelKey | string | 필수 | 채널 키 |
| theme | "dark" \| "light" | "dark" | 다크 · 라이트 |
크기 — 기본은 폭 100% · 부모 높이(부모에 높이가 없으면 최소 480px). 높이를 꼭 정해 주세요.
공통 prop
| prop | 타입 | 설명 |
|---|---|---|
| ssoToken | string | 간편 로그인(SSO) 토큰 — 내 사이트 회원을 바로 채팅에 로그인시킵니다. 아래 |
| origin | string | 위젯 출처. 기본 https://player.chear.live. 보통은 안 넣습니다 |
| className · style | | 위젯 바깥 div 에 그대로 |
| onError | (error) => void | 위젯을 불러오지 못했을 때(네트워크 · 사이트 보안 정책) |
<ChearProvider> — 위젯 출처 한 번에
개발서버나 다른 플랫폼 위젯을 쓸 때만 필요합니다.
import { ChearProvider, ChearPlayer, ChearChat } from "@nowsoft-lab/chear-widget-react";
<ChearProvider origin="https://dev.chear.live">
<ChearPlayer channelKey="3kTq9ZbW0x" />
<ChearChat channelKey="3kTq9ZbW0x" />
</ChearProvider>Next.js
App Router 에서 그대로 씁니다. 패키지에 "use client" 가 들어 있어 서버 컴포넌트에서 바로 import 해도 됩니다 — 서버에서는 빈 div 만 그리고, 브라우저에서 위젯이 뜹니다.
// app/live/page.tsx
import { ChearPlayer } from "@nowsoft-lab/chear-widget-react";
export default function Page() {
return <ChearPlayer channelKey="3kTq9ZbW0x" />;
}간편 로그인(SSO)
내 사이트에 로그인한 회원을 치어 계정 없이 바로 채팅에 들어오게 합니다(치어에서 파트너 SSO 를 켠 경우). 내 서버에서 SSO 비밀값으로 짧은 토큰(JWT HS256, 5분 이하)을 만들어 컴포넌트에 넘깁니다 — 비밀값은 브라우저에 두지 마세요.
const { token } = await fetch("/my-api/chear-sso").then((r) => r.json()); // 내 서버가 만든 토큰
<ChearChat channelKey="3kTq9ZbW0x" ssoToken={token} />- 토큰 형식(claims) · 서버 예제(Node · PHP · Java) · 오류 코드: 스튜디오 › 위젯 › 채팅 › "간편 로그인 안내" 또는 개발자 문서.
- 토큰은 한 번만 쓸 수 있습니다. 새 토큰을 넘기면 위젯이 다시 로그인합니다.
내 사이트 설정
허용 도메인
채널 설정에 "허용 도메인"이 있으면 그 사이트에서만 로그인 · 채팅할 수 있습니다(아니면 로그인 때 EMB-005). 보기 · 재생은 막지 않습니다.
채널 설정에서 "퍼가기 허용"을 끄면 어디서든 안내만 나옵니다.
CSP(Content-Security-Policy)
사이트에 CSP 를 쓰고 있다면 아래를 더해 주세요.
| 지시어 | 넣을 주소 |
|---|---|
| script-src | https://player.chear.live |
| connect-src | https://player.chear.live https://*.edge.naverncp.com https://*.firebasedatabase.app wss://*.firebasedatabase.app https://firestore.googleapis.com https://identitytoolkit.googleapis.com https://securetoken.googleapis.com |
| media-src | blob: https://*.edge.naverncp.com |
| img-src | https://*.edge.naverncp.com data: |
| style-src | https://cdn.jsdelivr.net 'unsafe-inline' |
| font-src | https://cdn.jsdelivr.net |
ChearProvider 로 다른 출처를 쓰면 player.chear.live 자리에 그 출처를 넣습니다.
브라우저 저장소
채팅 로그인 정보는 이 사이트의 localStorage 에 chear.widget: 로 시작하는 키로 둡니다. 채팅 · 신고 · 팔로우만 되는 짧은 토큰이고, 결제 · 마이페이지 같은 권한은 없습니다.
사이트 스크립트와 완전히 떼어 두어야 한다면 스튜디오 › 위젯의 iframe 위젯을 쓰세요.
동작 방식
이 패키지는 얇은 껍데기입니다. 화면은 위젯 출처의 런타임(https://player.chear.live/sdk/v1/runtime.js)이 그립니다.
- 컴포넌트가 처음 그려질 때 런타임을 한 번 받습니다(브라우저 캐시 · 여러 컴포넌트가 함께 씀).
- 컴포넌트의 div 에 Shadow DOM 을 열고 그 안에 위젯을 그립니다. 모달 · 로그인 창 · 전체 화면도 위젯 틀 안에서만 동작합니다.
- prop 이 바뀌면 다시 받지 않고 그 자리에서 바뀝니다.
그래서 화면 · 기능 개선은 런타임 배포만으로 모든 사이트에 반영됩니다. 이 패키지의 판은 prop 이 바뀔 때만 올라갑니다.
판 정책
2.0.0 (2026-10-27) —
channel(@아이디) 대신channelKey(채널 고정 키)를 받아요. 1.x 의channel은 더 이상 동작하지 않아요(@아이디 주소는 거부). 런타임 주소는 그대로/sdk/v1/이에요.
| 판 | 런타임 | |
|---|---|---|
| 2.x | /sdk/v1/ | 지금(channelKey). prop 추가는 2.x 안에서(기존 코드 그대로 동작) |
| 1.x | — | 끝남(channel = @아이디, 쓰는 곳이 없어 호환 없이 바꿈) |
prop 을 바꾸거나 빼는 큰 변경은 다음 큰 판(3.x)과 새 런타임 주소로 하고, 이전 판은 한동안 함께 유지해요.
문제 해결
| 증상 | 확인할 것 |
|---|---|
| 아무것도 안 보임 | onError 로 오류 확인. 사이트 CSP 의 script-src · 광고 차단 확장 |
| "이 채널은 퍼가기를 허용하지 않아요" | 채널 설정의 퍼가기 허용 |
| 로그인하면 EMB-005 | 채널 허용 도메인에 내 사이트 도메인 추가 |
| 채팅 높이가 0 · 너무 작음 | <ChearChat> 또는 부모에 높이 지정 |
| 소리가 안 나옴 | 자동 재생은 소리 끔으로 시작합니다. 화면의 "소리 켜기" 또는 muted={false}(브라우저가 막으면 소리 끔으로 재생) |
라이선스
UNLICENSED — 치어 위젯을 넣는 용도로만 씁니다.
