기타 백엔드(Node, Python 등) 연동 가이드
이 문서는 그누보드·아미나가 아닌 Node.js, Python, 기타 백엔드에서
BlueTalk(블루톡)를 연동하는 방법을 설명합니다.
예제 코드는 모두 현재 JS 구조(new BlueTalk())와 일치하며,
window.SITE_KEY / window.GLOBAL_* 패턴을 사용합니다.
백엔드 언어/프레임워크가 무엇이든, BlueTalk 연동의 핵심은 항상 같습니다.
- BlueTalk에서 발급받은 site_key를 설정한다.
- 로그인 세션/토큰에서 user_id와 nickname을 가져온다.
- 백엔드에서만 아는 비밀값(SECRET)과 함께 user_key를 생성한다.
- 렌더링되는 HTML에
window.SITE_KEY / window.GLOBAL_*로 네 값을 심어준다. - 프런트에서
new BlueTalk({ ... }).init()을 호출한다.
결국 “어디에서 user_key를 만들고, 어떻게 HTML로 전달하느냐”만 각 언어/프레임워크에 맞게 바뀔 뿐, 전체 구조는 항상 동일합니다.
가장 많이 사용하는 Node.js 백엔드 조합 중 하나인 Express + EJS를 기준으로 예제를 보여드립니다.
1) 환경변수 및 설정
// config.js 또는 별도 설정 파일
require('dotenv').config();
module.exports = {
BLT_SITE_KEY: process.env.BLT_SITE_KEY, // 발급받은 site_key
BLT_SECRET: process.env.BLT_SECRET // 서버 내부 비밀 문자열
};
2) user_key 생성 함수
// utils/bluetalk.js
const crypto = require('crypto');
const { BLT_SITE_KEY, BLT_SECRET } = require('../config');
function makeUserKey(userId) {
// 필요한 정보를 조합해 payload를 만듭니다.
const payload = `${userId}|${BLT_SITE_KEY}|${BLT_SECRET}`;
return crypto.createHash('sha256').update(payload).digest('hex');
}
module.exports = {
BLT_SITE_KEY,
makeUserKey
};
3) Express 라우터에서 값 넘기기
// routes/index.js
const express = require('express');
const router = express.Router();
const { BLT_SITE_KEY, makeUserKey } = require('../utils/bluetalk');
router.get('/', (req, res) => {
const isLogin = !!req.session.user;
const userId = isLogin ? req.session.user.id : 'guest';
const nick = isLogin ? req.session.user.nick : '손님';
const userKey = makeUserKey(userId);
res.render('index', {
bltSiteKey : BLT_SITE_KEY,
bltUserId : userId,
bltNickname: nick,
bltUserKey : userKey
});
});
module.exports = router;
4) EJS 템플릿에서 JS 초기화
<!-- views/index.ejs -->
<!doctype html>
<html lang="ko">
<head>
<meta charset="utf-8">
<title>BlueTalk 예제</title>
<script src="https://bluetalk.kr/talk/bluetalk.js"></script>
</head>
<body>
<div id="bluetalk"></div>
<script>
window.SITE_KEY = "<%= bltSiteKey %>";
window.GLOBAL_USER_ID = "<%= bltUserId %>";
window.GLOBAL_USER_KEY = "<%= bltUserKey %>";
window.GLOBAL_NICKNAME = "<%- bltNickname %>"; // XSS 필터는 실제 상황에 맞게 처리
const bt = new BlueTalk({
mode: 'global',
targetId: 'bluetalk'
});
bt.init();
</script>
</body>
</html>
이 패턴은 Express + EJS 뿐 아니라 Pug, Nunjucks 등 다른 템플릿 엔진에도 거의 동일하게 적용할 수 있습니다.
이번에는 Python 기반의 FastAPI + Jinja2 조합 예제입니다.
Django, Flask 등 다른 프레임워크에서도 기본 개념은 완전히 동일합니다.
1) 설정 및 user_key 함수
# settings.py 또는 config
import os
BLT_SITE_KEY = os.getenv("BLT_SITE_KEY", "발급받은_site_key")
BLT_SECRET = os.getenv("BLT_SECRET", "서버_비밀문자열")
def make_user_key(user_id: str) -> str:
import hashlib
payload = f"{user_id}|{BLT_SITE_KEY}|{BLT_SECRET}"
return hashlib.sha256(payload.encode("utf-8")).hexdigest()
2) FastAPI 라우터
# main.py
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse
from settings import BLT_SITE_KEY, make_user_key
app = FastAPI()
templates = Jinja2Templates(directory="templates")
@app.get("/", response_class=HTMLResponse)
async def index(request: Request):
user = request.session.get("user") if hasattr(request, "session") else None
if user:
user_id = user["id"]
nickname = user["nick"]
else:
user_id = "guest"
nickname = "손님"
user_key = make_user_key(user_id)
return templates.TemplateResponse("index.html", {
"request": request,
"blt_site_key": BLT_SITE_KEY,
"blt_user_id": user_id,
"blt_nickname": nickname,
"blt_user_key": user_key,
})
3) Jinja2 템플릿에서 JS 초기화
{# templates/index.html #}
<!doctype html>
<html lang="ko">
<head>
<meta charset="utf-8">
<title>BlueTalk FastAPI 예제</title>
<script src="https://bluetalk.kr/talk/bluetalk.js"></script>
</head>
<body>
<div id="bluetalk"></div>
<script>
window.SITE_KEY = "{{ blt_site_key }}";
window.GLOBAL_USER_ID = "{{ blt_user_id }}";
window.GLOBAL_USER_KEY = "{{ blt_user_key }}";
window.GLOBAL_NICKNAME = "{{ blt_nickname }}";
const bt = new BlueTalk({
mode: 'global',
targetId: 'bluetalk'
});
bt.init();
</script>
</body>
</html>
Flask, Django에서도 템플릿 엔진에 값 전달 → HTML에서 window.* 세팅 → new BlueTalk() 순서만 지키면 동일하게 적용할 수 있습니다.
React/Vue 같은 SPA에서는 초기 HTML은 아주 단순하고, 대부분의 화면은 JS로 렌더링됩니다.
이 경우에도 기본 원칙은 동일합니다.
- 백엔드에서 SPA의
index.html을 렌더링하거나, 초기 데이터(JSON)를 내려준다. - 로그인/유저 정보에 따라
site_key / user_id / nickname / user_key를 생성한다. - 이를 window 전역 또는 초기 상태(initial state)로 주입한다.
- React/Vue 컴포넌트에서
new BlueTalk({ ... })를 호출한다.
예를 들어 React 기준으로 가장 단순한 패턴은 다음과 같습니다.
// index.html (서버 측에서 렌더링 또는 정적 배포)
<script>
window.SITE_KEY = "__SITE_KEY_FROM_SERVER__";
window.GLOBAL_USER_ID = "__USER_ID_FROM_SERVER__";
window.GLOBAL_USER_KEY = "__USER_KEY_FROM_SERVER__";
window.GLOBAL_NICKNAME = "__NICKNAME_FROM_SERVER__";
</script>
// React 컴포넌트 (예: ChatWidget.jsx)
import { useEffect } from "react";
export default function ChatWidget() {
useEffect(() => {
if (!window.BlueTalk) return;
const bt = new window.BlueTalk({
mode: "global",
targetId: "bluetalk"
});
bt.init();
}, []);
return <div id="bluetalk" style={{ width: "100%", height: "100%" }} />;
}
SPA 환경에서는 초기 user_key를 어디에서 어떻게 주입할지만 설계해두면, 나머지 패턴은 동일합니다.
- user_key는 반드시 서버에서만 생성해야 합니다. (JS에서 생성/변조 금지)
- BLT_SECRET(비밀키)는 코드 레포지토리에 그대로 올리지 말고, 환경변수/.env/비밀 저장소를 이용해 관리하세요.
- 로그인 여부에 따라
user_id를"guest"등으로 설정하되, 사이트 정책에 맞게 게스트 권한을 조정해야 합니다. - 프런트에서는
window.SITE_KEY / window.GLOBAL_*만 보고 BlueTalk를 초기화합니다. - 실제 도메인 + site_key 조합은 BlueTalk 서버에서 검증되므로, 개발/운영 환경별로 site_key를 분리하는 것도 좋은 방법입니다.
만약 여기서 다루지 않은 스택(Go, Ruby, Java, .NET 등)을 사용하신다면,
“서버에서 site_key / user_id / nickname / user_key를 만든 뒤 HTML에 심어준다”는 기본 원칙만 기억하시고,
해당 언어의 템플릿/뷰 시스템에 맞게 예제를 옮겨서 사용하시면 됩니다.
