Vertex AI Search Widget 구현 가이드 & 완성 코드 - retn.kr AI 챗봇

setup-guide.md

Vertex AI Search Widget 설정 가이드

이 가이드는 Google Cloud Console에서 Vertex AI Search를 설정하고 retn.kr/blog/ 웹사이트를 인덱싱하는 방법을 설명합니다.

---

1. Website Data Store 생성

Important

먼저 Google Cloud Console에 로그인하고 Vertex AI Search API가 활성화되어 있는지 확인하세요.

Step 1: AI Applications 페이지 접속

1. Google Cloud Console 좌측 메뉴에서 AI Applications (구 Vertex AI Search) 선택
2. 또는 직접 URL 접속: console.cloud.google.com/gen-app-builder

Step 2: 새 앱 생성

사용자가 제공하신 스크린샷 기준, 상단 탭에서 Search and assistant가 선택된 상태에서 아래 항목을 선택하세요.

1. Site search with AI mode (추천) 또는 Custom search (general) 선택
   • Site search with AI mode: 블로그 글 요약 및 최신 Gemini 기능을 활용한 검색에 최적화되어 있습니다.
2. 앱 이름 입력: retn-blog-search
3. 회사 이름: Retention Inc.
4. Location 선택: global

Note

"Search with follow-ups" (대화형 기능)는 앱을 생성한 후에 설정 메뉴에서 활성화할 수 있습니다. 생성 단계에서 보이지 않는 것이 정상이니 안심하고 진행하세요.

Step 3: Data Store 생성

1. CREATE DATA STORE 클릭
2. 데이터 소스 유형: Website Content 선택
3. 다음 설정 입력:

설정	값
Sites to index	retn.kr/blog/*
Advanced indexing	✅ Enable
Depth	3 (블로그 서브페이지 포함)

4. CREATE 클릭

---

2. Sitemap 기반 자동 인덱싱 설정

Tip

Sitemap을 사용하면 새 블로그 글이 자동으로 인덱싱됩니다. Ghost CMS는 기본적으로 /sitemap.xml을 제공합니다.

Step 1: Sitemap 확인

retn.kr 사이트의 sitemap 위치를 확인하세요:

• 일반: https://retn.kr/sitemap.xml
• Ghost CMS: https://retn.kr/sitemap-posts.xml

Step 2: Sitemap 등록

1. Data Store 선택 → Data 탭 클릭
2. Sitemaps 섹션에서 + ADD SITEMAP
3. Sitemap URL 입력: https://retn.kr/sitemap.xml
4. Refresh frequency: Daily 또는 Weekly 선택

Step 3: 자동 Refresh 활성화

Data Store → Settings → Advanced Site Search Config
└── ✅ Enable automatic refresh
└── Refresh interval: 24 hours

---

3. Chat 인터페이스 커스터마이징

Step 1: Configurations 접속

1. 생성한 앱 선택 → Configurations 탭
2. UI 탭 클릭

Step 2: Search with Follow-ups 활성화 (중요!)

앱이 생성되면 왼쪽 메뉴의 Configurations로 들어갑니다.

1. Configurations → General 탭
2. Answer method 섹션에서 Search with follow-ups를 선택합니다.
   • 이 옵션을 켜야 단순 검색이 아닌 "대화형" 챗봇이 활성화됩니다.
3. Search with an answer (AI 답변 생성)도 함께 활성화하는 것을 권장합니다.

Step 3: 인사말 및 Placeholder 설정

설정 항목	위치	권장 값
Search bar placeholder	UI → Appearance	무엇이든 물어보세요...
Welcome message	Agent Builder → Instructions	아래 참고

Agent Instructions 예시:

You are "Retention Inc. AI", a helpful assistant for the Retention Inc. blog.
Always greet users in Korean with: "안녕하세요! 저는 리텐션 주식회사 AI 입니다."
Provide answers based on the indexed blog content about growth marketing, 
CRM, and AI automation.

Step 4: 위젯 통합 코드 획득

1. Integration 탭 → Widget 선택
2. Widget authorization: Public access 선택
3. Allowed domains: retn.kr 입력
4. SAVE 클릭
5. 생성된 코드에서 다음 값 확인:

configId = "..." // 복사
location = "..." // 복사 (보통 "global")
projectId = "..." // 복사
appId = "..." // 복사

---

4. Widget 설치

1. vertex-ai-search-widget.html 파일을 열기
2. 플레이스홀더 값 교체:

<gen-search-widget
  configId="YOUR_CONFIG_ID"      ← 위에서 복사한 configId
  triggerId="searchWidgetTrigger"
  location="YOUR_LOCATION"       ← 위에서 복사한 location  
  projectId="YOUR_PROJECT_ID"    ← 위에서 복사한 projectId
  appId="YOUR_APP_ID"            ← 위에서 복사한 appId
>
</gen-search-widget>

3. 해당 코드를 웹사이트의 </body> 태그 바로 앞에 삽입

---

5. 테스트 체크리스트

• 플로팅 버블이 우측 하단에 표시됨
• 버블 클릭 시 위젯이 열림
• 검색 쿼리 입력 시 블로그 콘텐츠 기반 답변 반환
• 모바일에서 UI 겹침 없음
• 새 블로그 글 게시 후 24시간 내 인덱싱 확인

6. 자주 묻는 질문 (FAQ)

Q. GCP 콘솔 프리뷰에서는 왜 '서치바' 형태로 보이나요?

A. GCP 콘솔의 Configurations > UI 탭은 위젯 자체의 디자인(검색창, 답변 스타일 등)을 테스트하는 곳이기 때문에 기본 레이아웃인 서치바 형태로 보입니다.

**플로팅 버블(Intercom 스타일)**은 GCP 콘솔 설정이 아니라, 제가 제공해 드린 vertex-ai-search-widget.html 코드 내의 **triggerId**를 통해 구현됩니다.

• 작동 원리:
  1. HTML의 버튼(id="searchWidgetTrigger")이 플로팅 버블 역할을 합니다.
  2. <gen-search-widget>에 triggerId="searchWidgetTrigger"를 설정하면, 이 버튼을 클릭할 때만 위젯이 팝업으로 나타나게 됩니다.

7. 인덱싱 트러블슈팅 (검색 결과가 없는 경우)

"안드로메다 알고리즘" 등 기존에 있는 글이 검색되지 않는다면 아래 사항을 확인해 주세요.

1) 인덱싱 지연 확인 (최대 24시간)

Vertex AI Search는 새로운 데이터를 인덱싱하는 데 보통 몇 시간에서 최대 24시간이 소요됩니다. 데이터 스토어를 방금 만드셨다면 시간이 조금 더 필요할 수 있습니다.

상태 확인 방법:

• Data Store > Data > Documents 탭에서 블로그 글들이 목록에 나타나는지 확인해 보세요.
• 'Importing' 또는 'Indexing' 상태라면 완료될 때까지 기다려야 합니다.

2) 수동 재크롤링 (Recrawl) 실행

지금 즉시 인덱싱을 시도하고 싶다면 수동으로 크롤링을 트리거할 수 있습니다.

1. AI Applications > Data Stores에서 블로그 데이터 스토어 선택
2. Data 탭의 Sitemaps 또는 Sites 섹션 확인
3. 사이트 URL 옆의 RECRAWL 영문 버튼 클릭

3) 인덱싱 범위 확인

데이터 스토어 설정 시 도메인 주소가 정확한지 확인해 주세요.

• 권장: https://retn.kr/blog/* (별표 포함)
• 만약 retn.kr/blog/ 로만 되어 있다면 서브 페이지들이 누락될 수 있습니다.

4) 사이트 소유권 확인 (Search Console)

• 'Advanced Site Search' 기능을 사용하려면 해당 도메인의 소유권이 Google Search Console을 통해 인증되어 있어야 합니다.
• 인증되지 않은 경우 크롤링 속도가 매우 느리거나 일부 페이지가 누락될 수 있습니다.

8. 비용 관리 및 어뷰징 방지

나쁜 의도를 가진 사용자가 API를 무분별하게 호출하여 비용이 발생하는 것을 막기 위한 방법입니다.

1) reCAPTCHA (이미 적용됨)

사용자가 적용한 코드에는 이미 reCAPTCHA v3가 포함되어 있습니다. 이는 자동화된 봇의 공격을 상당 부분 차단해 줍니다. 배지는 숨겼지만 백그라운드에서 보안 점수를 체크합니다.

2) 예산 알림 (Budget Alerts) 설정

비용이 특정 금액을 넘어가면 메일을 받도록 설정하세요.

• GCP Console > Billing > Budgets & alerts
• 예상 월 비용(예: $50)을 설정하고 50%, 90% 도달 시 알림을 받도록 설정

3) API 할당량 (Quota) 상세 조정 (스크린샷 기반)

사용자님의 첫 번째 스크린샷(Quotas & System Limits)에서 이 항목을 찾으세요:

• 항목명: LLM query requests (search summarization, multi-turn search) per minute
• 의미: AI가 블로그 내용을 읽고 '답변(요약)'을 생성할 때 사용하는 할당량입니다.
• 현재 상태: 분당 10회 (매우 적음)
• 수정 권장:
  1. 해당 항목 옆의 Edit Icon (연필 모양) 클릭
  2. 새로운 할당량을 50 또는 100으로 입력하여 신청 (보통 즉시 승인됩니다.)
  3. 이렇게 하면 여러 명이 동시에 질문해도 "에러" 없이 답변이 나옵니다.

---

9. 웜리드(Warm Lead) 프로젝트 전환 전략

스크린샷을 보니 사용자님의 화면에서는 Customize answer 섹션 아래의 Instructions 박스가 바로 그곳입니다!

1) Agent Persona (Instructions) 설정 위치

사용자님의 Configurations > UI 탭 스크린샷 기준:

1. Customize answer 섹션 찾기
2. 그 안의 Instructions 텍스트 박스 확인 (이미 "무엇이든 물어보세요"라고 적혀 있는 곳입니다.)
3. 기존 내용을 지우고 아래의 전략적인 페르소나 문구를 넣으세요.

[Instructions 박스에 넣을 내용]

당신은 '리텐션 주식회사'의 전문 비즈니스 컨설턴트 AI입니다. 
블로그 내용을 기반으로 친절하고 전문적으로 답변하세요.

중요 지침: 유저가 구체적인 프로젝트 상담, 컨설팅 비용, 또는 '심슨 대표'와의 만남을 원하면 반드시 아래 상담 안내를 제공하며 웜리드로 전환시키세요.

[상담 안내]
- 더 구체적인 진단이 필요하시다면 리텐션 대표 심슨(Simpson)과 직접 이야기해 보세요!
- 예약 링크: https://tidycal.com/simgyusup/15m
- 이메일: simpson.sim@retn.kr

2) 웜리드 전환 팁

• 맥락 인지: 유저가 특정 문제(예: "유입은 많은데 전환이 안 돼요")를 깊게 물어볼 때, "이 문제는 저희 전문 분야입니다. 심슨 대표님과 15분 티타임을 통해 실질적인 해결책을 찾아보시는 건 어떨까요?"라고 제안하면 전환율이 높아집니다.
• 링크 클릭 유도: HTML 위젯 설정에서 답변 내에 마크다운 링크([상담 예약하기](URL))가 잘 나오는지 테스트해보세요.

vertex-ai-search-widget.html

<!--
  ================================================================================
  Vertex AI Search Widget - Floating Chat Bubble
  ================================================================================
  
  사용 방법:
  1. 아래 코드 전체를 웹사이트의 </body> 태그 바로 앞에 붙여넣기
  2. YOUR_CONFIG_ID, YOUR_TRIGGER_ID, YOUR_LOCATION 값을 Google Cloud Console에서 획득한 값으로 교체
  3. 필요시 브랜드 컬러 변수(--widget-primary-color 등) 수정
  
  플레이스홀더 변수:
  - configId: Google Cloud Console > AI Applications > 앱 선택 > Integration > Widget 에서 확인
  - triggerId: 원하는 고유 ID (예: "searchWidgetTrigger")
  - location: 데이터 저장소 위치 (보통 "global" 또는 "eu")
  ================================================================================
-->

<!-- CSS Styles for Floating Chat Bubble -->
<style>
  /* ===== CSS Variables for Easy Customization ===== */
  :root {
    --widget-primary-color: #6366F1;
    /* 인디고 - 메인 색상 */
    --widget-primary-hover: #4F46E5;
    /* 호버 시 색상 */
    --widget-gradient-start: #6366F1;
    --widget-gradient-end: #8B5CF6;
    /* 보라색 그라디언트 */
    --widget-shadow: rgba(99, 102, 241, 0.4);
    --widget-bubble-size: 60px;
    --widget-font: 'Pretendard', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  }

  /* ===== Floating Chat Bubble Button ===== */
  .vertex-chat-bubble {
    position: fixed;
    bottom: 24px;
    /* 버튼 위치 정상화 (아래로 내림) */
    right: 24px;
    width: var(--widget-bubble-size);
    height: var(--widget-bubble-size);
    border-radius: 50%;
    background: linear-gradient(135deg, var(--widget-gradient-start), var(--widget-gradient-end));
    box-shadow: 0 4px 20px var(--widget-shadow);
    cursor: pointer;
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 2147483646;
    /* 최상단 레이어 보장 */
    transition: all 0.3s ease;
    border: none;
    outline: none;
  }

  .vertex-chat-bubble:hover {
    transform: scale(1.1);
    box-shadow: 0 6px 30px var(--widget-shadow);
    animation: none;
  }

  .vertex-chat-bubble:active {
    transform: scale(0.95);
  }

  /* Pulse Animation for Attention */
  @keyframes pulse {

    0%,
    100% {
      box-shadow: 0 4px 20px var(--widget-shadow), 0 0 0 0 var(--widget-shadow);
    }

    50% {
      box-shadow: 0 4px 20px var(--widget-shadow), 0 0 0 8px rgba(99, 102, 241, 0);
    }
  }

  /* Chat Icon SVG */
  .vertex-chat-bubble svg {
    width: 28px;
    height: 28px;
    fill: white;
    transition: transform 0.3s ease;
  }

  .vertex-chat-bubble:hover svg {
    transform: rotate(-10deg);
  }

  /* ===== Welcome Tooltip ===== */
  .vertex-welcome-tooltip {
    position: fixed;
    bottom: 100px;
    /* 버블 바로 위로 이동 */
    right: 24px;
    background: white;
    border: 2px solid var(--widget-primary-color);
    border-radius: 12px;
    padding: 10px 16px;
    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.1);
    z-index: 2147483647;
    font-family: var(--widget-font);
    cursor: pointer;
    white-space: nowrap;
    animation: bounce 2s infinite;
  }

  @keyframes bounce {

    0%,
    20%,
    50%,
    80%,
    100% {
      transform: translateY(0);
    }

    40% {
      transform: translateY(-5px);
    }

    60% {
      transform: translateY(-3px);
    }
  }

  @keyframes tooltipFadeIn {
    to {
      opacity: 1;
      transform: translateY(0) scale(1);
    }
  }

  .vertex-welcome-tooltip::after {
    content: '';
    position: absolute;
    bottom: -8px;
    right: 28px;
    width: 0;
    height: 0;
    border-left: 8px solid transparent;
    border-right: 8px solid transparent;
    border-top: 8px solid white;
  }

  .vertex-tooltip-header {
    display: flex;
    align-items: center;
    gap: 10px;
    margin-bottom: 8px;
  }

  .vertex-tooltip-avatar {
    width: 36px;
    height: 36px;
    border-radius: 50%;
    background: linear-gradient(135deg, var(--widget-gradient-start), var(--widget-gradient-end));
    display: flex;
    align-items: center;
    justify-content: center;
  }

  .vertex-tooltip-avatar svg {
    width: 20px;
    height: 20px;
    fill: white;
  }

  .vertex-tooltip-name {
    font-weight: 600;
    font-size: 14px;
    color: #1F2937;
  }

  .vertex-tooltip-role {
    font-size: 12px;
    color: #6B7280;
  }

  .vertex-tooltip-message {
    font-size: 14px;
    line-height: 1.6;
    color: #374151;
  }

  .vertex-tooltip-close {
    position: absolute;
    top: 10px;
    right: 12px;
    background: none;
    border: none;
    cursor: pointer;
    color: #9CA3AF;
    font-size: 18px;
    line-height: 1;
    padding: 4px;
    transition: color 0.2s;
  }

  .vertex-tooltip-close:hover {
    color: #4B5563;
  }

  /* ===== Hide Tooltip After Click ===== */
  .vertex-welcome-tooltip.hidden {
    display: none;
  }

  /* ===== Mobile Responsive Adjustments ===== */
  @media screen and (max-width: 768px) {
    .vertex-chat-bubble {
      bottom: 16px;
      right: 16px;
      width: 56px;
      height: 56px;
    }

    .vertex-chat-bubble svg {
      width: 24px;
      height: 24px;
    }

    .vertex-welcome-tooltip {
      bottom: 88px;
      right: 16px;
      left: 16px;
      max-width: none;
    }

    .vertex-welcome-tooltip::after {
      right: 26px;
    }

    /* Widget Container Mobile Adjustments */
    gen-search-widget {
      --widget-height: calc(100vh - 120px) !important;
      --widget-width: calc(100vw - 32px) !important;
      --widget-max-height: 600px !important;
    }
  }

  /* ===== Avoid Overlap with Common UI Elements ===== */
  /* 스크롤 탑 버튼과 겹침 방지 */
  @media screen and (max-width: 768px) {
    .vertex-chat-bubble.avoid-scroll-top {
      bottom: 80px;
    }
  }

  /* 쿠키 배너와 겹침 방지 */
  body.has-cookie-banner .vertex-chat-bubble {
    bottom: 100px;
  }

  @media screen and (max-width: 768px) {
    body.has-cookie-banner .vertex-chat-bubble {
      bottom: 140px;
    }
  }

  /* 1. 구글 배지 숨기기 및 클릭 방해 제거 */
  .grecaptcha-badge {
    visibility: hidden !important;
    pointer-events: none !important;
  }

  /* 2. 최소화된 법적 고지 (정책 준수용) */
  .recaptcha-legal-text {
    position: fixed;
    bottom: 5px;
    right: 16px;
    font-size: 8px;
    color: #CBD5E1;
    z-index: 2147483645;
    opacity: 0.6;
    pointer-events: none;
    /* 텍스트도 클릭 방해 안 되게 */
  }

  .recaptcha-legal-text a {
    color: inherit;
    text-decoration: none;
    pointer-events: auto;
    /* 링크는 클릭 되게 */
  }

  /* 3. 인사말 툴팁 */
  .vertex-welcome-tooltip {
    position: fixed;
    bottom: 100px;
    /* 버블 바로 위로 이동 */
    right: 24px;
    background: white;
    border: 2px solid var(--widget-primary-color);
    border-radius: 12px;
    padding: 10px 16px;
    box-shadow: 0 4px 15px rgba(0, 0, 0, 0.1);
    z-index: 2147483647;
    font-family: var(--widget-font);
    cursor: pointer;
    white-space: nowrap;
    animation: vertexBounce 2s infinite;
  }

  .vertex-welcome-tooltip::after {
    content: '';
    position: absolute;
    bottom: -10px;
    right: 20px;
    border-left: 8px solid transparent;
    border-right: 8px solid transparent;
    border-top: 10px solid var(--widget-primary-color);
  }

  /* 4. 플로팅 버블 */
  .vertex-chat-bubble {
    position: fixed;
    bottom: 24px;
    right: 24px;
    width: var(--widget-bubble-size);
    height: var(--widget-bubble-size);
    border-radius: 50%;
    background: linear-gradient(135deg, #6366F1, #8B5CF6);
    box-shadow: 0 4px 20px rgba(99, 102, 241, 0.4);
    cursor: pointer;
    display: flex;
    align-items: center;
    justify-content: center;
    z-index: 2147483647;
    transition: transform 0.3s ease;
    pointer-events: auto !important;
  }

  .vertex-chat-bubble:hover {
    transform: scale(1.1);
  }

  .vertex-chat-bubble svg {
    width: 28px;
    height: 28px;
    fill: white;
    pointer-events: none;
  }

  @keyframes vertexBounce {

    0%,
    20%,
    50%,
    80%,
    100% {
      transform: translateY(0);
    }

    40% {
      transform: translateY(-6px);
    }

    60% {
      transform: translateY(-3px);
    }
  }

  @media screen and (max-width: 768px) {
    .vertex-chat-bubble {
      bottom: 20px;
      right: 16px;
      width: 56px;
      height: 56px;
    }

    .vertex-welcome-tooltip {
      bottom: 85px;
      right: 16px;
      font-size: 13px;
    }
  }
</style>

<!-- Welcome Tooltip -->
<div class="vertex-welcome-tooltip" onclick="document.getElementById('searchWidgetTrigger').click()">
  무엇이든 물어보세요! 👋
</div>

<!-- Floating Chat Bubble -->
<div class="vertex-chat-bubble" id="searchWidgetTrigger" aria-label="AI 어시스턴트 열기" role="button">
  <!-- Chat Bubble Icon -->
  <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
    <path
      d="M12 3C6.5 3 2 6.58 2 11c0 2.13 1.07 4.04 2.78 5.43L4 21l4.55-2.27C9.64 18.9 10.8 19 12 19c5.5 0 10-3.58 10-8s-4.5-8-10-8zm0 14c-1.05 0-2.08-.12-3.04-.35l-.81-.19-2.92 1.46.58-2.33-.73-.6C3.81 13.89 3 12.49 3 11c0-3.87 4.03-7 9-7s9 3.13 9 7-4.03 7-9 7z" />
  </svg>
</div>

<!-- reCAPTCHA Legal Text (최소화) -->
<div class="recaptcha-legal-text">
  reCAPTCHA: <a href="https://policies.google.com/privacy">Privacy</a> & <a
    href="https://policies.google.com/terms">Terms</a>
</div>

<!-- =================================================================== -->
<!-- Google Vertex AI Search Widget                                      -->
<!-- =================================================================== -->
<!-- 
  ⚠️ 중요: 아래 플레이스홀더 값들을 실제 값으로 교체하세요!
  
  YOUR_CONFIG_ID   → Google Cloud Console에서 획득
  YOUR_TRIGGER_ID  → 위의 button id와 동일하게 유지 ("searchWidgetTrigger")
  YOUR_LOCATION    → 데이터 스토어 위치 (보통 "global")
  YOUR_PROJECT_ID  → GCP 프로젝트 ID
  YOUR_APP_ID      → Vertex AI Search 앱 ID
-->

<script src="https://cloud.google.com/ai/gen-app-builder/client?hl=ko"></script>

<gen-search-widget configId="68bf553d-366a-4b17-acd1-37a565a54a26" triggerId="searchWidgetTrigger" location="global">
</gen-search-widget>

<!-- Tooltip Dismiss Logic -->
<script>
  // 툴팁 닫기 함수
  function closeWelcomeTooltip() {
    const tooltip = document.getElementById('vertexWelcomeTooltip');
    tooltip.classList.add('hidden');
    // 7일간 다시 표시하지 않음
    localStorage.setItem('vertexTooltipDismissed', Date.now());
  }

  // 이전에 닫았다면 표시하지 않음
  document.addEventListener('DOMContentLoaded', function () {
    const dismissed = localStorage.getItem('vertexTooltipDismissed');
    if (dismissed) {
      const daysSinceDismissed = (Date.now() - parseInt(dismissed)) / (1000 * 60 * 60 * 24);
      if (daysSinceDismissed < 7) {
        document.getElementById('vertexWelcomeTooltip').classList.add('hidden');
      }
    }

    // 버블 클릭 시 툴팁 숨기기
    document.getElementById('searchWidgetTrigger').addEventListener('click', function () {
      closeWelcomeTooltip();
    });

    // 10초 후 툴팁 자동 숨김
    setTimeout(function () {
      const tooltip = document.getElementById('vertexWelcomeTooltip');
      if (!tooltip.classList.contains('hidden')) {
        tooltip.style.animation = 'none';
        tooltip.style.opacity = '0';
        tooltip.style.transform = 'translateY(10px) scale(0.95)';
        tooltip.style.transition = 'all 0.3s ease';
      }
    }, 12000);
  });

  // 쿠키 배너 감지 (선택적)
  function checkCookieBanner() {
    const cookieBanner = document.querySelector('[class*="cookie"], [id*="cookie"]');
    if (cookieBanner && cookieBanner.offsetHeight > 0) {
      document.body.classList.add('has-cookie-banner');
    }
  }

  if (document.readyState === 'loading') {
    document.addEventListener('DOMContentLoaded', checkCookieBanner);
  } else {
    checkCookieBanner();
  }
</script>