그누보드 · 아미나 연동 가이드 > BlueTalk::블루톡 무료 실시간 채팅 위젯 · 1:1 DM

그누보드 연동

1. 개요

그누보드/아미나에서 블루톡을 사용하는 기본 흐름은 다음과 같습니다.

블루톡에서 발급받은 site_key 를 설정한다.
그누보드의 $member / $is_member를 이용해 user_id / nickname을 결정한다.
user_key를 서버(PHP)에서 생성한다. (user_id + 비밀키 조합)
위 값들을 window.SITE_KEY / window.GLOBAL_* 에 넣는다.
new BlueTalk({ ... }).init() 으로 JS를 초기화한다.
원하는 레이아웃 파일(예: head.sub.php)에 출력 조건을 걸어 사용한다.

이 문서는 위 과정을 그누보드/아미나 기준으로 어떻게 구현하는지 예제와 함께 보여줍니다.

2. site_key 설정 (config.php 또는 별도 설정 파일)

먼저 블루톡에서 발급 받은 site_key를 그누보드/아미나에서 공통으로 사용할 수 있도록 설정합니다.

예시 1) /config.php 또는 공통 include 파일에 정의

// /config.php 또는 공통 include 파일 상단

// BlueTalk site_key (블루톡에서 발급받은 값을 넣어주세요)
$blt_site_key = '여기에_발급받은_site_key_값';

// BlueTalk user_key 생성을 위한 비밀키 (서버에서만 알고 있는 값)
$blt_secret   = '서버_내부_비밀문자열_예시';

실제 서비스에서는 $blt_secret 값을 .env 파일 또는 DB/별도 설정 파일에 보관하고, 직접 소스에 노출되지 않도록 관리하는 것을 권장합니다.

3. 회원 정보 매핑 (user_id / nickname / user_key)

그누보드/아미나에서는 $member, $is_member 변수를 통해 로그인 여부와 회원 정보를 확인할 수 있습니다. 이를 이용해 user_id, nickname, user_key를 준비합니다.

예시 2) 공통 부분에서 PHP 변수 준비

<?php
// /head.sub.php 또는 공통 레이아웃 파일 내

// 1) 로그인/비로그인 구분하여 user_id / nickname 설정
if ($is_member) {
    $blt_user_id  = $member['mb_id'];
    $blt_nickname = get_text($member['mb_nick']);
} else {
    $blt_user_id  = 'guest';
    $blt_nickname = '손님';
}

// 2) user_key 생성 (예: SHA-256)
//    실제로는 가입일, 만료시간, 추가 정보 등을 payload에 포함하는 것을 권장
$payload      = $blt_user_id.'|'.$blt_site_key.'|'.$blt_secret;
$blt_user_key = hash('sha256', $payload);
?>

위 예시는 가장 단순한 형태이며,
실제 보안 요구사항에 맞춰 payload에 만료 시각, 가입일, IP 일부 등을 더 섞어 user_key를 생성할 수 있습니다.

4. head.sub.php에 블루톡 위젯 삽입 (사이트 공통 출력)

가장 단순한 연동은 /theme/사용중인테마/head.sub.php 에 블루톡 위젯을 넣는 방식입니다. 이렇게 하면 해당 테마를 사용하는 모든 페이지에서 블루톡이 공통으로 표시됩니다.

예시 3) head.sub.php에 공통 채팅창 넣기

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

// (앞부분에서 $blt_site_key, $blt_secret, $blt_user_id, $blt_user_key, $blt_nickname 등을 준비해 두었다고 가정)

// 블루톡 위젯을 어디에 둘지 위치를 정합니다.
// 예: 상단 또는 하단 레이아웃 한 켠에 div 영역을 배치
?>

<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; ?>";

  // 필요하면 아바타 이미지, 관리자키 등도 함께 내려줄 수 있습니다.
  // window.GLOBAL_AVATAR_URL = '...';
  // window.GLOBAL_ADMIN_KEY  = '...';

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

위 예제는 현재 bluetalk.js 실제 구조와 완전히 일치하는 코드입니다.
(예전 문서에 있던 Bluetalk.init({...}) 형식은 사용하지 않습니다.)

5. 특정 페이지 / 게시판에서만 블루톡 사용하기

모든 페이지에 채팅이 필요하지 않을 수도 있습니다.
이 경우 조건문으로 감싸서 특정 페이지/게시판에서만 블루톡을 표시할 수 있습니다.

예시 4) 메인(index) 페이지에서만 블루톡 출력

<?php if (defined('_INDEX_')) { ?>
  <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 $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>
<?php } ?>

예시 5) 특정 게시판(예: free)에서만 출력

<?php
$show_bluetalk = false;

// 특정 게시판에서만 표시하고 싶을 때
if (isset($bo_table) && $bo_table === 'free') {
    $show_bluetalk = true;
}

// 또는 메인에서도 보이고 싶다면:
// if (defined('_INDEX_')) {
//     $show_bluetalk = true;
// }
?>

<?php if ($show_bluetalk) { ?>
  <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 $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>
<?php } ?>

위와 같이 $show_bluetalk 플래그를 사용하면,
조건이 점점 복잡해지더라도 출력 위치는 한 군데로 깔끔하게 관리할 수 있습니다.

6. 화면 오른쪽 하단 플로팅 형태로 사용하기

많은 사이트에서 쓰는 “오른쪽 하단에 작게 떠 있는 채팅 버튼/창” 형태 역시 CSS와 블루톡 위젯 조합만으로 쉽게 구현할 수 있습니다.

예시 6) 심플한 플로팅 레이아웃

<style>
/* 오른쪽 하단 플로팅 컨테이너 */
#bluetalk-floating {
  position: fixed;
  right: 10px;
  bottom: 10px;
  width: 360px;
  max-width: 100%;
  height: 480px;
  max-height: calc(100vh - 80px);
  z-index: 9999;
  box-shadow: 0 12px 30px rgba(15,23,42,0.55);
  border-radius: 12px;
  overflow: hidden;
}

/* 필요 시, 버튼/토글 형태로도 구성 가능 */
</style>

<div id="bluetalk-floating">
  <div id="bluetalk"></div>
</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 $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>

실제 예제 HTML은 플로팅 레이아웃 예제에서 전체 소스 코드와 함께 제공할 예정입니다.

7. 정리

그누보드/아미나에서 블루톡을 쓰려면 site_key, user_id, nickname, user_key 네 가지가 핵심입니다.
site_key와 비밀키는 config 또는 별도 설정 파일에 보관합니다.
user_id / nickname은 $member / $is_member를 이용해 쉽게 가져올 수 있습니다.
user_key는 PHP에서만 생성하며, JS에서 임의로 만들거나 수정하지 않습니다.
페이지/게시판별 출력 제어는 defined('_INDEX_'), $bo_table 등을 이용해 조건문으로 관리합니다.
JS 쪽은 항상 window.SITE_KEY / window.GLOBAL_* + new BlueTalk({...}).init() 패턴을 사용합니다.