Skip to content

SETUP_GUIDE.md

Latest commit

 

History

History
429 lines (302 loc) · 12.2 KB

SETUP_GUIDE.md

File metadata and controls

429 lines (302 loc) · 12.2 KB
Raw

Google Sheets 연동 설정 가이드

KPN 웹사이트를 Google Sheets와 연동하여 참여 신청 및 커뮤니티 인사이트를 저장하는 방법을 안내합니다.

📋 목차

  1. Google Sheets 생성
  2. Google Apps Script 작성
  3. 웹 앱으로 배포
  4. 웹사이트에 URL 연결
  5. Sheets JSON 퍼블리시 (선택)

1. Google Sheets 생성

1-1. 참여 신청용 시트 만들기

  1. Google Sheets 접속
  2. 새 스프레드시트 생성: KPN_Members
  3. 첫 번째 시트 이름: 참여신청
  4. 첫 행(헤더)에 다음 항목 입력:
A1: timestamp
B1: nickname
C1: email
D1: region
E1: interests

1-2. 커뮤니티 인사이트용 시트 만들기

  1. 같은 스프레드시트에 새 시트 추가: 커뮤니티인사이트
  2. 첫 행(헤더)에 다음 항목 입력:
A1: timestamp
B1: nickname
C1: insight

2. Google Apps Script 작성

2-1. Apps Script 에디터 열기

  1. 스프레드시트에서 확장 프로그램 > Apps Script 클릭
  2. 새 프로젝트 이름: KPN_FormHandler

2-2. 스크립트 코드 작성

기존 Code.gs 파일의 내용을 삭제하고 아래 코드를 붙여넣기:

// KPN - Google Apps Script 폼 핸들러

function doPost(e) {
  try {
    const sheet = SpreadsheetApp.getActiveSpreadsheet();
    const params = e.parameter;
    
    // 참여 신청 폼인지 인사이트 폼인지 구분
    if (params.insight) {
      // 커뮤니티 인사이트
      return handleInsight(sheet, params);
    } else if (params.email) {
      // 참여 신청
      return handleJoin(sheet, params);
    } else {
      throw new Error('잘못된 요청입니다.');
    }
  } catch (error) {
    return ContentService
      .createTextOutput(JSON.stringify({
        status: 'error',
        message: error.toString()
      }))
      .setMimeType(ContentService.MimeType.JSON);
  }
}

// 참여 신청 처리
function handleJoin(sheet, params) {
  const joinSheet = sheet.getSheetByName('참여신청');
  
  if (!joinSheet) {
    throw new Error('참여신청 시트를 찾을 수 없습니다.');
  }
  
  const timestamp = new Date();
  const nickname = params.nickname || '';
  const email = params.email || '';
  const region = params.region || '';
  const interests = params.interests || '';
  
  // 새 행 추가
  joinSheet.appendRow([timestamp, nickname, email, region, interests]);
  
  return ContentService
    .createTextOutput(JSON.stringify({
      status: 'success',
      message: '참여 신청이 완료되었습니다.'
    }))
    .setMimeType(ContentService.MimeType.JSON);
}

// 커뮤니티 인사이트 처리
function handleInsight(sheet, params) {
  const insightSheet = sheet.getSheetByName('커뮤니티인사이트');
  
  if (!insightSheet) {
    throw new Error('커뮤니티인사이트 시트를 찾을 수 없습니다.');
  }
  
  const timestamp = new Date();
  const nickname = params.nickname || '익명';
  const insight = params.insight || '';
  
  // 새 행 추가
  insightSheet.appendRow([timestamp, nickname, insight]);
  
  return ContentService
    .createTextOutput(JSON.stringify({
      status: 'success',
      message: '인사이트가 공유되었습니다.'
    }))
    .setMimeType(ContentService.MimeType.JSON);
}

// GET 요청 처리 (테스트용)
function doGet(e) {
  return ContentService
    .createTextOutput('KPN Form Handler is running.')
    .setMimeType(ContentService.MimeType.TEXT);
}

2-3. 스크립트 저장

  1. 디스크 아이콘 클릭 또는 Ctrl+S (Mac: Cmd+S)
  2. 프로젝트 저장 확인

3. 웹 앱으로 배포

3-1. 배포 설정

  1. 우측 상단 배포 > 새 배포 클릭
  2. 톱니바퀴 아이콘 클릭 > 웹 앱 선택
  3. 설정:
    • 설명: KPN Form Handler v1
    • 다음 계정으로 실행: 나
    • 액세스 권한: 모든 사용자 (로그인 불필요)
  4. 배포 클릭

3-2. 권한 승인

  1. 액세스 승인 클릭
  2. Google 계정 선택
  3. 고급 > [프로젝트 이름](안전하지 않음)으로 이동 클릭
  4. 허용 클릭

3-3. 웹 앱 URL 복사

배포 완료 후 표시되는 웹 앱 URL을 복사합니다.

예시: https://script.google.com/macros/s/AKfycbz.../exec

⚠️ 이 URL을 안전하게 보관하세요!

4. 웹사이트에 URL 연결

4-1. submit.js 업데이트

data/submit.js 파일을 열고 다음 줄을 수정:

// 수정 전
const SCRIPT_URL = 'YOUR_GOOGLE_APPS_SCRIPT_URL_HERE';

// 수정 후 (복사한 웹 앱 URL 붙여넣기)
const SCRIPT_URL = 'https://script.google.com/macros/s/AKfycbz.../exec';

4-2. 테스트

  1. 웹사이트 실행 (로컬 또는 배포 환경)
  2. join.html 페이지에서 참여 신청 테스트
  3. community.html 페이지에서 인사이트 공유 테스트
  4. Google Sheets에서 데이터가 정상적으로 추가되는지 확인

5. Sheets JSON 퍼블리시 (선택)

커뮤니티 인사이트를 실시간으로 웹사이트에 표시하려면 Google Sheets를 JSON으로 퍼블리시해야 합니다.

방법 1: Google Sheets API 사용 (권장)

5-1. Google Cloud Console 설정

  1. Google Cloud Console 접속
  2. 새 프로젝트 생성: KPN_API
  3. API 및 서비스 > 라이브러리 이동
  4. Google Sheets API 검색 및 활성화

5-2. API 키 생성

  1. 사용자 인증 정보 메뉴
  2. 사용자 인증 정보 만들기 > API 키 선택
  3. API 키 복사 (안전하게 보관)

5-3. 스프레드시트 공유

  1. KPN_Members 스프레드시트 열기
  2. 우측 상단 공유 클릭
  3. 일반 액세스 > 링크가 있는 모든 사용자 선택
  4. 권한: 뷰어
  5. 스프레드시트 ID 복사 (URL의 /d/ 뒤에 있는 긴 문자열)
예시 URL: https://docs.google.com/spreadsheets/d/[SPREADSHEET_ID]/edit

5-4. fetch_insights.js 업데이트

data/fetch_insights.js 파일을 열고:

// 수정 전
const SHEETS_JSON_URL = 'YOUR_GOOGLE_SHEETS_JSON_URL_HERE';

// 수정 후
const SHEETS_JSON_URL = 'https://sheets.googleapis.com/v4/spreadsheets/[SPREADSHEET_ID]/values/커뮤니티인사이트?key=[YOUR_API_KEY]';

방법 2: 웹에 게시 (간단하지만 보안 낮음)

  1. 스프레드시트에서 파일 > 공유 > 웹에 게시
  2. 커뮤니티인사이트 시트 선택
  3. 형식: 웹 페이지 또는 CSV
  4. 게시 클릭
  5. 생성된 URL을 fetch_insights.js에 입력

🔒 보안 참고사항

  1. API 키 노출 방지: 클라이언트 사이드에서 API 키를 사용할 때는 도메인 제한 설정 필요
  2. Apps Script URL: 웹 앱 URL은 공개되어도 괜찮지만, 스팸 방지를 위해 reCAPTCHA 추가 권장
  3. 개인정보: 이메일 등 민감한 정보는 Sheets 접근 권한 철저히 관리
  4. 스팸 방지: 필요시 Apps Script에 rate limiting 추가

🛠️ 문제 해결

폼 제출이 안 돼요

  1. Apps Script URL이 올바른지 확인
  2. 브라우저 콘솔(F12)에서 에러 메시지 확인
  3. Apps Script 실행 로그 확인 (실행 > 실행 로그)
  4. CORS 문제일 경우 Apps Script 재배포

데이터가 Sheets에 안 들어가요

  1. 시트 이름이 정확한지 확인 (참여신청, 커뮤니티인사이트)
  2. 헤더 행이 올바른지 확인
  3. Apps Script 권한 재승인

인사이트가 웹사이트에 안 보여요

  1. JSON URL이 올바른지 확인
  2. 스프레드시트 공유 설정 확인 (링크가 있는 모든 사용자)
  3. 브라우저 콘솔에서 fetch 에러 확인
  4. API 키가 활성화되어 있는지 확인

5. 이메일 자동 발송 설정 (선택)

참여 신청 시 자동으로 Slack 초대 이메일을 발송하려면 Google Apps Script에 이메일 발송 함수를 추가해야 합니다.

5.1. Google Apps Script에 함수 추가

  1. Apps Script 편집기 열기

    • Google Sheets에서 확장 프로그램 → Apps Script 클릭

  2. sendWelcomeEmail 함수 추가

    • 기존 doPost 함수 아래에 다음 함수 추가:
function sendWelcomeEmail(email, nickname) {
  const subject = 'Korea Preppers Network에 오신 것을 환영합니다';
  
  const body = `안녕하세요, ${nickname}님!

Korea Preppers Network (KPN)에 참여해주셔서 진심으로 감사드립니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 KPN의 주요 소통 채널은 Slack입니다

저희는 아직 초창기 단계로, 함께 커뮤니티를 만들어가고 있습니다.
생존 지식을 나누고, 실질적인 대비 전략을 함께 고민하는 공간을 
한 걸음씩 구축해 나가고자 합니다.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📨 Slack 채널 초대장이 발송되었습니다

아래 링크를 클릭하여 KPN Slack 워크스페이스에 참여하세요:

👉 https://join.slack.com/t/koreapreppersnetwork/shared_invite/zt-3ggvvn07k-R_8iVfj6fDD0~1dNdj6HGQ

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💬 Slack에서 할 수 있는 것들:

• 다른 준비자들과 실시간 소통
• 생존 지식 및 경험 공유
• 재난 대비 질문 및 토론
• 지역별 커뮤니티 연결
• 최신 정보 및 업데이트 수신

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🌐 KPN 웹사이트: https://your-vercel-site.vercel.app
📚 생존 지식: https://your-vercel-site.vercel.app/knowledge.html
📋 시나리오: https://your-vercel-site.vercel.app/scenario.html

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

함께 준비하고, 함께 살아남읍시다.

- Korea Preppers Network 팀 드림

P.S. 이 이메일에 회신하시면 저희가 직접 답변드립니다.`;

  try {
    MailApp.sendEmail({
      to: email,
      subject: subject,
      body: body
    });
    Logger.log('Welcome email sent to: ' + email);
  } catch (error) {
    Logger.log('Email sending failed: ' + error);
  }
}
  1. doPost 함수에 이메일 발송 코드 추가
    • joinSheet.appendRow(...) 다음 줄에 추가:
// 이메일 발송
sendWelcomeEmail(email, nickname);

5.2. 권한 승인

  1. 저장 및 실행

    • 저장 아이콘 클릭 (💾)
    • doPost 함수 선택 후 "실행" 버튼 클릭

  2. 권한 검토

    • "권한 검토" 대화상자가 나타남
    • 본인의 Google 계정 선택

  3. 고급 옵션으로 진행

    • "고급" 링크 클릭
    • "[프로젝트 이름] (안전하지 않음)으로 이동" 클릭

  4. 권한 허용

    • "허용" 버튼 클릭
    • Gmail 전송 권한 승인

5.3. 웹 앱 재배포

권한을 추가한 후에는 웹 앱을 다시 배포해야 합니다:

  1. 오른쪽 상단 "배포" → "배포 관리" 클릭
  2. 현재 배포 옆의 연필 아이콘(✏️) 클릭
  3. "버전" → "새 버전" 선택
  4. "배포" 버튼 클릭

5.4. 제한사항 및 주의사항

⚠️ MailApp 제한사항:

  • 하루 100통 제한: 일반 Gmail 계정은 하루 100통까지만 발송 가능
  • 초기 단계에는 충분: MVP 단계에서는 문제없음
  • 대량 발송 시: Gmail API 또는 SendGrid 등 전문 서비스 사용 권장

💡 팁:

  • 이메일 제목과 본문은 sendWelcomeEmail 함수에서 자유롭게 수정 가능
  • Vercel URL은 실제 배포된 사이트 주소로 변경하세요
  • 이메일 전송 실패 시 Logger.log로 오류 확인 가능 (Apps Script 편집기 → "실행 로그" 탭)

5.5. 테스트

  1. 웹사이트에서 참여 신청 제출
  2. 입력한 이메일로 환영 메일 수신 확인
  3. Slack 링크 클릭하여 참여 확인

📞 추가 도움

작성일: 2025-10-18
최종 업데이트: 2025-01-19
버전: 1.1