블루톡 빠른 시작 (1분 설치) > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM

빠른 시작

1. 설치 전에 준비할 것

블루톡을 붙이기 위해 필요한 것은 크게 세 가지입니다.

① site_key – 블루톡에서 발급받은 사이트 고유 키
② 도메인 – 실제 서비스에 사용할 웹사이트 주소
③ 로그인 정보 연동 – (선택) 회원 아이디/닉네임 등을 넘기기 위한 서버 코드

※ 데모용 키는 따로 제공되지 않습니다.
실제 사용하실 도메인을 기준으로 블루톡에서 site_key를 발급받고,
그 키를 이용해 바로 연동하시면 됩니다.

2. HTML/JS 5줄로 붙이는 기본 예제

가장 단순한 형태의 설치는 다음과 같이 스크립트 1줄 + 위젯 영역 1줄 + 초기화 코드로 구성됩니다.
아래 코드는 HTML 문서의 <body> 안, 적당한 위치에 넣어주시면 됩니다.

<!-- 1) 블루톡 JS SDK 로드 -->
<script src="https://bluetalk.kr/talk/bluetalk.js"></script>

<!-- 2) 채팅이 들어갈 영역 -->
<div id="bluetalk"></div>

<!-- 3) 서버에서 내려준 값으로 초기화 -->
<script>
  window.SITE_KEY          = "발급받은_site_key";
  window.GLOBAL_USER_ID    = "user123";           // 사용자 아이디 또는 PK
  window.GLOBAL_USER_KEY   = "서버에서_생성한_user_key";
  window.GLOBAL_NICKNAME   = "홍길동";            // 채팅에 보여줄 닉네임
  // 필요하다면: window.GLOBAL_AVATAR_URL, window.GLOBAL_ADMIN_KEY 등 추가 가능

  const bt = new BlueTalk({
    mode:     'global',   // 또는 'channel', 'dm'
    targetId: 'bluetalk'  // 위 div id와 동일
  });
  bt.init();
</script>

위 예제에서 중요한 값은 다음 네 가지입니다.

site_key : 블루톡에서 발급받은 사이트 키 (window.SITE_KEY로 전달)
user_id : 해당 사용자를 구분할 수 있는 고유 값 (예: 회원 아이디)
nickname : 채팅창에 표시될 닉네임
user_key : 서버에서 생성하는 서명/토큰 값 (보안용)

간단 테스트용으로는 user_id, nickname 값을 문자열로 고정해도 되지만,
실제 서비스에서는 서버에서 안전하게 생성한 토큰을 window.GLOBAL_USER_KEY에 넣어주시는 것을 권장합니다.

3. 그누보드/아미나에 삽입하기 (head.sub.php 예제)

그누보드/아미나에서는 공통 레이아웃 파일에 블루톡을 넣어두면, 사이트 전체에 동일한 채팅창을 띄울 수 있습니다.
가장 간단한 방법은 /theme/사용중인테마/ 아래의 head.sub.php 또는 레이아웃 파일에 스크립트를 추가하는 것입니다.

예시 1) head.sub.php에 공통 위젯 삽입

사이트 전체에 항상 블루톡을 보여주고 싶다면, 아래와 같이 head.sub.php에 공통 코드를 넣습니다.

<?php
// /theme/사용중인테마/head.sub.php

// 1) 블루톡 site_key / 비밀키 등은 config 또는 별도 설정에서 가져옵니다.
$blt_site_key = '발급받은_site_key';

// 2) 로그인 여부에 따라 user_id / nickname / user_key를 준비합니다.
if ($is_member) {
    $blt_user_id   = $member['mb_id'];
    $blt_nickname  = get_text($member['mb_nick']);
} else {
    $blt_user_id   = 'guest';
    $blt_nickname  = '손님';
}

// user_key는 서버에서만 생성하는 서명값입니다.
// 예시는 단순하지만, 실제로는 가입일/만료시간/비밀키 등을 섞어서 생성하는 것을 권장합니다.
$blt_secret = '서버_내부_비밀문자열';
$payload    = $blt_user_id.'|'.$blt_site_key.'|'.$blt_secret;
$blt_user_key = hash('sha256', $payload);
?>

<!-- body 영역 어딘가(예: 상단/하단)에 블루톡을 붙이고 싶을 때 -->
<div id="bluetalk"></div>

<script src="https://bluetalk.kr/talk/bluetalk.js"></script>
<script>
  // PHP에서 준비한 값을 JS 전역으로 전달
  window.SITE_KEY          = "<?php echo $blt_site_key; ?>";
  window.GLOBAL_USER_ID    = "<?php echo $blt_user_id; ?>";
  window.GLOBAL_USER_KEY   = "<?php echo $blt_user_key; ?>";
  window.GLOBAL_NICKNAME   = "<?php echo $blt_nickname; ?>";

  const bt = new BlueTalk({
    mode:     'global',
    targetId: 'bluetalk'
  });
  bt.init();
</script>

위 예시는 가장 단순한 형태이며, 실제 서비스에서는 user_key 생성 로직을 조금 더 안전하게 구성하시는 것을 추천드립니다.

예시 2) 로그인 사용자만 블루톡 표시

비회원에게는 블루톡을 숨기고, 로그인한 회원에게만 채팅창을 보여주고 싶을 때 사용할 수 있는 패턴입니다.

<?php if ($is_member) { ?>
  <div id="bluetalk"></div>

  <script src="https://bluetalk.kr/talk/bluetalk.js"></script>
  <script>
    window.SITE_KEY          = "<?php echo $blt_site_key; ?>";
    window.GLOBAL_USER_ID    = "<?php echo $member['mb_id']; ?>";
    window.GLOBAL_NICKNAME   = "<?php echo get_text($member['mb_nick']); ?>";
    window.GLOBAL_USER_KEY   = "<?php echo $blt_user_key; ?>";

    const bt = new BlueTalk({
      mode:     'global',
      targetId: 'bluetalk'
    });
    bt.init();
  </script>
<?php } ?>

예시 3) 특정 게시판(예: free)에서만 블루톡 출력

게시판이 많을 때, 예를 들어 free 게시판에서만 블루톡을 보여주고 싶다면, 아래와 같이 조건을 걸어 사용할 수 있습니다.

<?php if (isset($bo_table) && $bo_table === 'free') { ?>
  <div id="bluetalk"></div>

  <script src="https://bluetalk.kr/talk/bluetalk.js"></script>
  <script>
    window.SITE_KEY          = "<?php echo $blt_site_key; ?>";
    window.GLOBAL_USER_ID    = "<?php echo ($is_member ? $member['mb_id'] : 'guest'); ?>";
    window.GLOBAL_NICKNAME   = "<?php echo ($is_member ? get_text($member['mb_nick']) : '손님'); ?>";
    window.GLOBAL_USER_KEY   = "<?php echo $blt_user_key; ?>";

    const bt = new BlueTalk({
      mode:     'global',
      targetId: 'bluetalk'
    });
    bt.init();
  </script>
<?php } ?>

4. 다른 레이아웃/빌더에서도 동일한 패턴으로 사용

부트스트랩, 타 빌더, 직접 만든 레이아웃이라도 패턴은 완전히 동일합니다.

HTML에 <div id="bluetalk"> 같은 위젯 영역을 만든다.
bluetalk.js를 불러온다.
서버에서 준비한 site_key / user_id / nickname / user_key를 window.*로 내려준다.
new BlueTalk({ ... }).init()을 호출한다.

즉, “어디에 div를 둘지”와 “어디에서 JS를 호출할지”만 빌더 구조에 맞게 선택하시면 됩니다.

5. 다음 단계

여기까지 진행하셨다면, 이미 사이트에 블루톡 대화창이 떠 있어야 합니다.

블루톡 주요 기능 살펴보기
– 글로벌 채팅, 1:1 DM, 파일/이미지 전송, 채널/방, 제재 기능 등을 한눈에 볼 수 있습니다.
그누보드/아미나 연동 가이드
– 실제 그누보드/아미나 사이트에 적용하는 방법을 단계별로 설명합니다.
PHP 외(Node, Python 등) 스택에서의 연동
– 다양한 백엔드 환경에서 site_key / user_key를 만드는 방법을 다룹니다.

설치를 진행하시다가 “어디에 이 코드를 넣어야 할지 모르겠다” 싶으면,
사용 중인 테마/빌더 정보와 함께 Q&A 게시판에 편하게 남겨주세요.