헤드리스 프론트엔드에 온라인 폼 통합하기

자체 웹사이트 프론트엔드를 구축할 때, "문의하기" 또는 "상담 신청" 폼을 만들기 위해 타사 폼 서비스를 통합할 필요가 없습니다. 대시보드의 마케팅 › 온라인 폼에서 직접 폼을 만들고, Content Delivery API를 통해 커스텀 프론트엔드에서 필드를 가져오고 응답을 제출할 수 있습니다.

폼이 제출되면 Kanorio는 자동으로 봇 보호, 스팸 필터링, 연락처 생성 또는 병합, 제출자에게 확인 이메일 발송, 팀에게 알림 발송을 처리하며, 동시에 customers.form.submitted 웹훅을 트리거합니다.

전체 엔드포인트 및 오류 코드 사양(SSOT): 3가지 폼 엔드포인트에 대한 매개변수 세부 정보, 필드 구조 및 오류 코드는 Content Delivery API 참조(폼 그룹)를 참조하십시오.

준비 사항

1. 폼을 만들고 폼 ID 가져오기: 대시보드의 마케팅 › 온라인 폼으로 이동하여 폼을 만듭니다. formId는 URL 또는 데이터 및 기록 › 데이터 테이블에서 확인할 수 있습니다.
2. CORS 허용 오리진 등록: 프론트엔드에서 브라우저를 통해 직접 API를 호출하는 경우(자체 백엔드를 통해 프록시하지 않는 경우), 웹사이트 설정 › 개발자로 이동하여 프로덕션 도메인(예: https://www.example.com)을 "허용된 오리진"에 추가하십시오(로컬 개발을 위한 localhost는 기본적으로 허용되므로 별도 설정이 필요 없습니다).

통합 3단계

1단계: 폼 정의 가져오기 (GET /api/v1/forms/{id})

페이지 로드 또는 빌드 시 폼 제목, 필드, 개인정보 및 마케팅 동의 설정, 현재 사용 가능 상태를 가져옵니다.

• availability.accepting이 false인 경우(예: 폼이 보관되었거나 마감 기한이 지난 경우), 프론트엔드에서 입력 필드를 렌더링하는 대신 종료 메시지를 표시할 수 있습니다.
• 프론트엔드에 폼 필드를 하드코딩할 수도 있습니다. 단, field.id가 대시보드의 설정과 일치하는지 확인하십시오.

2단계: 안티 스팸 챌린지 가져오기 (GET /api/v1/forms/{id}/challenge)

방문자가 번거로운 CAPTCHA를 풀지 않고도 자동화된 스팸 봇을 차단하기 위해, Kanorio는 가벼운 작업 증명(Proof-of-Work) 챌린지를 사용합니다.

• 방문자가 폼에 포커스를 맞추거나 제출 버튼을 클릭하기 전에 브라우저에서 GET /api/v1/forms/{id}/challenge를 호출합니다(이 엔드포인트는 no-store이며 매번 새로운 챌린지를 반환합니다).
• 챌린지를 프론트엔드 유효성 검사기에 전달하여 solution 문자열을 계산하고(또는 @kanorio/sdk에 포함된 헬퍼 함수 사용), 제출 시 포함하십시오.

3단계: 폼 응답 제출하기 (POST /api/v1/forms/{id}/submit)

방문자의 answers(필드 id를 키로 하는 객체), 안티 스팸 솔루션, 마케팅 동의 상태를 /api/v1/forms/{id}/submit으로 POST 합니다.

async function submitContactForm(siteUrl: string, formId: string, answers: Record<string, unknown>) {
  // 1. 안티 스팸 챌린지 가져오기 및 솔루션 계산
  const challengeRes = await fetch(`${siteUrl}/api/v1/forms/${formId}/challenge`, {
    cache: "no-store",
  });
  const challenge = await challengeRes.json();
  const token = await solveFormChallenge(challenge);

  // 2. 폼 응답 제출
  const res = await fetch(`${siteUrl}/api/v1/forms/${formId}/submit`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      answers,
      challengeToken: token,
      marketingConsent: true,
      pagePath: window.location.pathname,
    }),
  });

  if (!res.ok) {
    const { error } = await res.json();
    throw new Error(error?.message ?? "제출 실패");
  }
  return res.json();
}

자동화된 백엔드 워크플로우

/submit이 200 OK를 반환하면 Kanorio는 백그라운드에서 자동으로 다음을 실행합니다.

1. 연락처 속성 지정: 폼에 이메일이나 전화번호 필드가 포함된 경우, 자동으로 를 일치시키거나 생성하며, 커스텀 필드를 연락처 속성에 매핑하거나 폼 응답에 저장합니다.
2. 확인 및 알림: 설정에 따라 제출자와 팀에게 자동으로 이메일을 발송합니다.
3. 웹훅 푸시: customers.form.submitted 이벤트를 구독 중인 경우, 시스템은 즉시 외부 시스템이나 자동화 워크플로우로 응답을 푸시합니다.

관련 문서