선물과 채팅으로 게임과 보상 만들기

네, 게임이 TikTok 선물에 반응할 수 있습니다

Social Stream Ninja가 이벤트를 캡처해 페이지로 보내면 JavaScript가 로켓 추진, 정원 성장, 적 생성, 공동 목표 진행 등을 결정합니다. 동작과 기준값은 게임에서 정합니다. SSN으로 플랫폼의 선물 가격을 바꾸지는 못합니다.

시작하기: 템플릿 3종를 사용해 본 뒤 규칙의 측정 기준을 고르세요: 플랫폼 단위, 선물 식별 정보, 추정 USD.

소리, 알림, OBS 동작 또는 webhook에는 먼저 Event Flow. 게임판이나 별도 게임 상태가 필요하면 맞춤 HTML 페이지를 사용하세요. 완성된 게임은 게임 갤러리.

작고 편집하기 쉬운 템플릿 3종

각 미리보기에는 샘플 버튼과 ‘마지막 수신 데이터’ 표시가 있습니다. 샘플은 가상 이벤트이며 구매가 아닙니다. 미리보기는 실제 세션에 접속하지 않습니다.

코인 로켓: TikTok 코인 10개, Twitch 비트 100개 또는 Facebook 스타 100개가 추진 1회를 만듭니다. 나머지는 시청자와 플랫폼별로 누적됩니다. 다음을 변경하세요: COST 를 HTML에서 수정해 금액을 설정하세요.
공동 후원 목표: 네 플랫폼의 추정 USD 후원을 모아 달 기지를 만듭니다. 다음을 변경하세요: GOAL_USD 또는 진행 표시를 피해량, 연료, 타이머로 바꾸세요.
선물과 이벤트 정원: 선택한 TikTok 선물은 꽃을, 캡처된 TikTok 팔로우는 나무를 더하고, 무료 !water 채팅 명령은 물을 더합니다. 다음을 설정하세요: GIFT_ID 에 캡처한 ID를 넣거나 다음을 설정하세요: GIFT_NAME 에 정확한 이름을 넣으세요. ‘Demo flower’는 가상 예제입니다.

HTML 소스를 열고 다음을 찾으세요: EDIT THIS RULE 또는 EDIT THESE RULES. receive(data) 함수에서 샘플 동작을 게임 로직으로 바꿉니다. 연결과 계산 도우미 위치: starter.js; 화면 스타일은 다음 파일에 있습니다: starter.css.

템플릿을 방송에 연결하기

SSN을 실행하고 채팅 소스를 연결하세요. 채팅과 선물/후원이 dock에 도착하는지 확인하세요. TikTok 설정은 연결 모드.
다음 없이 템플릿을 여세요: ?demo. SSN 세션 ID를 지정하고, 세션 비밀번호가 설정되어 있으면 함께 넣으세요.
브라우저에서 확인한 뒤 같은 URL을 OBS 브라우저 소스로 추가하세요. 예를 들어 1000 × 800 크기를 사용할 수 있습니다. 다음을 추가하면 &clean 데이터 표시, 연결 상태, 진행자 버튼을 숨깁니다.

https://socialstream.ninja/games/templates/coin-rocket.html?session=YOUR_SESSION&password=YOUR_PASSWORD&clean

베타 사이트에서는 /beta/ 를 다음 앞에 유지하세요: games/. 비밀번호가 없으면 해당 매개변수를 빼세요. 세션 링크는 공개하지 마세요.

기본 연결은 SSN 오버레이와 같은 iframe 브리지를 씁니다. 호스팅된 WebSocket 캡처 채팅 경로를 쓰려면 SSN에서 다음을 켜세요: 서버를 통해 확장 프로그램에서 도크로 메시지 전송 (Send messages to Dock from Extension via server) 설정을 켜고 다음을 추가하세요: &server2. 참고: WebSocket 가이드 에서 로컬 설정을 확인하세요. 템플릿은 다음도 지원합니다: &server2&localserver 그리고 &localserverport=3000. localserver 만으로 경로가 활성화되지 않습니다. 이전 방식인 server 는 다른 채널을 쓰며 dock에서 그 채널로 게시해야 할 수 있습니다.

나만의 사본 만들기

베타 소스 ZIP 다운로드 한 뒤 압축을 푸세요. 편집할 파일 위치: games/templates/를 풀되 폴더 구조를 유지하세요. 템플릿은 다음 파일도 불러옵니다: js/local-server-url.js를 불러오며, 후원 목표는 currency.js 를 저장소 루트에서 불러옵니다.

압축을 푼 폴더를 로컬 웹 서버로 제공하세요. Python이 있다면 해당 폴더에서 실행하세요:

python -m http.server 8080 --bind 127.0.0.1

그런 다음 다음을 사용하세요: http://127.0.0.1:8080/games/templates/coin-rocket.html?session=YOUR_SESSION 를 브라우저나 OBS에서 여세요. 다른 곳에 호스팅해도 상대 경로를 유지하세요. 빌드는 필요 없습니다.

동작에 필요한 코인 수는 어떻게 정하나요?

숫자를 정하기 전에 무엇을 측정할지 고르세요:

규칙	읽기:	예시
플랫폼 고유 단위	TikTok `meta.coinsPerGift × meta.tiktokGiftCount` 가 있으면 이를, 또는 명시적인 `hasDonation` 와 같은 표시 문구 `10 coins`, `100 bits`, 또는 `100 Stars`.	10코인마다 추진 1회를 얻습니다.
특정 선물	TikTok `meta.giftId` 또는 `meta.giftName`와 그 수량입니다.	일치하는 선물마다 추정 USD 가치와 관계없이 꽃 하나를 더합니다.
비교 가능한 후원 가치	`getDonationValueUSD(data)` 출처: `currency.js`.	추정 1달러마다 연료 10을 더하고, 25달러면 목표가 완성됩니다.
무료 동작 또는 멤버십 동작	소스가 실제 제공한 `event`또는 채팅 명령입니다.	팔로우는 나무를 키우고, 새 유료 구독은 애니메이션을 재생합니다.

금액의 의미를 결정하세요: 정확히 일치 (coins === 10), 이벤트별 최소값 (coins >= 10), 또는 누적 잔액. 로켓은 잔액을 누적합니다. 25코인은 추진 2회와 잔여 5코인이 됩니다. ‘정확히 10’ 규칙은 25코인을 무시합니다. 이벤트마다 여러 단계 중 하나만 실행하려면 가장 높은 기준부터 검사해 낮은 단계가 모두 실행되지 않도록 하세요.

TikTok 시청자는 코인을 구매해 표시된 코인 가격의 선물을 보냅니다. 자신의 LIVE에서 가능한 선물을 고르고 규칙 공개 전 데이터를 확인하세요. 선물 이름, 선물 수량, 코인, 다이아몬드는 서로 다른 측정값입니다. USD 추정값을 나눠 ‘정확한 코인 수’를 구하거나 다이아몬드를 코인으로 취급하지 마세요. TikTok 코인과 선물 설명.

캡처가 선물 이름/수량이나 다이아몬드 표시만 제공하면, 명시적 코인 메타데이터가 없는 한 코인 템플릿은 해당 이벤트를 건너뜁니다. 선물 식별 규칙이나 추정 USD 템플릿을 사용하세요. 코인 메타데이터는 SSN 선물 매핑에서 올 수도 있으므로 정확한 가격이 중요하면 현재 LIVE 선물 목록과 비교하세요. 목록과 캡처 방식이 달라 모든 TikTok 메시지에 보장되는 공통 코인 필드는 없습니다.

플랫폼별로 보내는 데이터

type 은 소스를 식별합니다. event 가 있으면 동작을 나타냅니다. 제공 여부는 캡처 모드, 설정, 플랫폼 공개 데이터에 달려 있습니다. 예제는 SSN의 현재 코드 경로를 설명하며 모든 계정의 모든 이벤트를 보장하지 않습니다.

플랫폼	후원 및 이벤트 데이터	구분할 항목
TikTok	`type: "tiktok"`, `event: "gift"`. 후원 캡처는 다음을 제공할 수 있습니다: `hasDonation` 그리고 `donoValue`. 메타데이터에는 ID, 이름, 수량, 선물당 코인이나 다이아몬드, 연속 선물 식별자가 포함될 수 있습니다.	코인으로 선물을 구매하며 다이아몬드는 크리에이터 보상입니다. SSApp WebSocket 캡처는 연속 선물을 정산한 뒤 전달하지만 브라우저는 누적 업데이트를 보낼 수 있습니다. TikTok 후원 캡처를 끄면 선물 이벤트에 금액 필드가 없을 수 있습니다.
Twitch	Cheer는 비트를 사용합니다. 예: `hasDonation: "100 bits"`. API 캡처는 다음을 사용할 수 있습니다: `event: "cheer"` 그리고 `donoValue: 1`; 화면 채팅 캡처에는 이벤트 표시가 없을 수 있습니다.	구독, 선물 구독, 레이드, 채널 포인트는 별도 동작입니다. 일반 메시지의 구독자 배지는 새 구독이 아닙니다. 직접 Cheer와 Twitch 확장 프로그램에서 사용한 비트는 다른 연동입니다.
Facebook	화면에 표시된 Live Chat 스타 행은 예를 들어 다음을 제공합니다: `hasDonation: "100 Stars"` 그리고 `donoValue: 1`이며 다음 필드는 없습니다: `event` 표시를 요구하지 마세요.	댓글 API는 채팅 문구에서 스타를 추론하지 않습니다. DOM 캡처에는 보이는 스타 행이 필요하며, 일반 댓글과 반응은 결제 금액을 입증하지 않습니다.
YouTube	`superchat` 그리고 `supersticker` 은 원래 통화 금액을 다음에 담습니다: `hasDonation`. 선물은 다음을 사용합니다: `jeweldonation` 포함: `N Jewels`, 또는 `1 YouTube Gift` 를 금액이 숨겨졌을 때 사용합니다.	시청자는 쥬얼로 선물을 보내고 크리에이터는 루비를 얻습니다. 멤버십과 선물 멤버십은 별도 이벤트이며 쥬얼이 아닙니다. Super Thanks는 별도 상품으로 실시간 채팅 후원 이벤트를 보장하지 않습니다.

플랫폼 참고 자료: TikTok 다이아몬드; Twitch 비트와 구독; Meta 스타 개요; YouTube Super Chat 및 Super Stickers; YouTube 쥬얼, 선물, 루비. 용어 확인일은 2026년 9월 29일입니다. 자격 조건과 제공 여부는 플랫폼의 최신 안내를 확인하세요.

다른 소스도 팁, 선물, 멤버십 또는 구매를 보고할 수 있습니다. 다음을 확인하세요: 이벤트 참고 문서 를 확인한 뒤 템플릿의 isSupport 필터에 추가하세요. 상품 판매나 선물 구독이 자동으로 팁이 되지는 않습니다. 예를 들어 YouTube는 선물 구매와 수령 알림을 구분하므로 둘 다 세면 같은 선물을 두 번 보상합니다.

donoValue와 currency.js 올바르게 사용하기

hasDonation 는 원래 표시 문구입니다. 예: €5.00 또는 100 bits. donoValue 는 소스가 선택적으로 제공하는 숫자 USD 금액입니다. 표시 문구에서 추정하기 전에 0을 포함한 유효한 지정값을 우선하세요. 원래 문구는 표시용으로 보존하세요.

<script src="../../currency.js"></script>
<script>
// From games/templates/: use the existing helper, including its zero handling.
var usd = getDonationValueUSD(data);
// Use usd for your rule; display data.hasDonation for the original amount/unit.
</script>

기존 변환 방식: 현재 SSN은 TikTok 코인 1개를 0.01 USD, 다이아몬드 1개를 0.005 USD, Twitch 비트 또는 Facebook 스타 1개를 0.01 USD, YouTube 쥬얼 1개를 0.005 USD로 추정합니다. 가격 없는 TikTok 선물은 개당 코인 1개를 기본으로 쓰고, 쥬얼 수량 없는 YouTube 선물에는 별도 임시값 0.01 USD를 씁니다. 일반 통화도 실시간 환율 서비스가 아닌 내부 근사 환율로 변환합니다.

이 값은 SSN의 비교용 값이며 시청자 지출, 크리에이터 순수익, 출금 가능 잔액의 공통 정의가 아닙니다. 캡처 방식에 따라 추정값이 달라집니다. 특히 알 수 없는 TikTok 선물을 1코인으로 처리하는 것은 실제 가격이 1코인임을 입증하지 않습니다.

다음을 사용하지 마세요: donoValue || convertToUSD(...): 의도적으로 지정한 0을 무시하게 됩니다. 결제를 판별하려고 다음에서 숫자를 추출하지 마세요: chatmessage 로 결제를 감지하거나 다음 event === "donation": Facebook 스타와 일부 Cheer에는 이벤트 표시가 없습니다. 후원 목표 템플릿은 후원 유형을 먼저 고른 뒤 공용 변환기를 호출합니다.

소스: currency.js 및 페이로드 참조. 선물 메타데이터는 선택 사항이며, 예제는 캡처에 없는 필드를 만들어 내지 않습니다.

연속 선물은 한 번만 계산하기

TikTok이 같은 연속 선물의 누적 수량 1, 2, 3을 보고하면 총 6개가 아니라 3개입니다. 더하는 동작에서는 이미 받은 최대 수량이나 금액을 기억하고 증가분만 적용하세요. 같은 합계의 완료 업데이트는 아무것도 더하지 않습니다.

// All three events refer to the same streak:
// incoming total: 1, 2, 3, 3
// added to game:  1, 1, 1, 0
var newCoins = RewardStarter.increment(data, RewardStarter.coins(data), 'coins');

도우미는 사용 가능한 TikTok 고유 그룹/보낸 사람/선물 ID를 우선하고, 다음으로 meta.tiktokGiftStreakId 또는 메시지 ID를 씁니다. 일반 메시지 ID도 중복 전달을 방지합니다. 다음 필드는 repeatEnd 를 기다리지 않습니다. 브라우저가 제공하지 않을 수 있기 때문입니다. 연속 선물이 끝난 뒤 한 번만 동작해야 한다면 실제로 받는 필드를 이용해 별도 완료 규칙을 만드세요.

학습용 템플릿은 최대 2,000개 식별자를 메모리에 저장합니다. 초기화나 새로고침은 메모리와 진행을 지웁니다. 안정적인 ID가 없으면 확실한 중복 제거가 불가능하며 같은 채널의 다른 캡처도 다른 ID를 쓸 수 있습니다. 우선 캡처 경로를 하나만 사용하세요. 로켓은 플랫폼과 사용자 ID로 잔액을 구분하고 ID가 없으면 표시 이름을 쓰므로 동명이인이 잔액을 공유할 수 있습니다. 재시작 후에도 유료 보상을 유지하려면 상태 저장 및 재전송 처리를 추가하세요.

맞춤 게임 없이 보상 만들기

다음 위치에서: Event Flow에서 다음을 사용하세요: 속성 비교 포함: donoValue, 크거나 같음와 USD 기준값을 정한 다음 소리, 애니메이션, OBS 제어 등을 연결하세요. 비교는 유효한 소스 지정값을 우선하고 필요하면 기존 환율 변환을 사용합니다.

특정 TikTok 선물을 선택하려면 다음을 비교하세요: meta.giftId 또는 meta.giftName를 비교하고 흐름을 TikTok 선물 이벤트로 한정하세요. 다음 필드의 숫자 비교도 hasDonation USD로 처리되며 코인 수 직접 비교가 아닙니다. 코인 전용 규칙은 고유 메타데이터나 자체 코드를 쓰세요.

메시지별 기준값은 누적 잔액이나 연속 선물 카운터와 다릅니다. Event Flow 기준값이 템플릿의 누적 및 중복 처리를 자동으로 수행한다고 가정하지 마세요. 다음을 사용하세요: 상태 노드 로 상태를 관리하거나 게임 안에 해당 로직을 두세요.

유료 동작 연결 전에 시험하기

샘플 버튼을 사용하세요. 1 → 2 → 3 연속 선물은 3개분만 더해야 합니다. 명시적 0 예제는 USD를 더하지 않고, 가격 미상 예제는 정확한 코인 수를 더하지 않아야 합니다.
실제 소스를 연결하고 캡처된 데이터를 확인하세요. 선물 이름/ID, 금액/단위, 수량, 규칙이 기대하는 이벤트를 검증하세요. 샘플은 규칙을 확인하며 실제 플랫폼 캡처를 입증하지는 않습니다.
OBS 장면에서 반복 이벤트, 재연결, 새로고침을 확인하세요. 메모리의 진행을 유지해야 한다면 브라우저 소스를 끄거나 새로고침하지 마세요.

무인 또는 AFK 게임에서는 SSN, 소스 캡처, 게임 페이지가 계속 실행되어야 합니다. 컴퓨터 절전, 로그인 만료, 연결 끊김은 동작을 중단합니다. 템플릿은 놓친 이벤트를 복구하거나 환불을 처리하지 않습니다. 자동 반응이 무인 방송 수익화를 허용하는 것은 아닙니다. 해당 형식에 적용되는 최신 LIVE 및 수익화 규칙을 확인하세요.

아무것도 오지 않으면 SSN dock, 세션/비밀번호, 전송 설정 순서로 확인하세요. 채팅은 오는데 선물이 일치하지 않으면 데이터와 후원/이벤트 필터를 확인하세요. 팔로우와 구독 이벤트 지원은 소스마다 다릅니다. 자세한 내용: 이벤트 참고 문서. 연결에 관한 자세한 내용은 맞춤 오버레이.