페이지 작업

호스트 작업 등록하기#

페이지 작업은 웹사이트의 UI를 열거나 허용된 페이지로 이동합니다. 최신 임베드를 설치하고 스크립트 로드가 끝난 뒤 등록하세요. 핸들러는 웹사이트에 남으며 에이전트에는 이름, 설명, 매개변수 정의만 전달됩니다.

MakeAgentFast.registerAction("show_details", {
  description: "현재 페이지의 상세 정보 표시",
  params: { section: { type: "string", description: "delivery 또는 returns 사용" } },
  confirm: true
}, async ({ section }) => {
  const sections = {
    delivery: document.getElementById("delivery-details"),
    returns: document.getElementById("returns-details")
  };
  if (!Object.hasOwn(sections, section) || !sections[section]) {
    throw new Error("알 수 없는 섹션");
  }
  sections[section].scrollIntoView({ block: "start" });
  return { shown: section };
});

// 페이지 컴포넌트가 해제될 때 실행:
// MakeAgentFast.unregisterAction("show_details");

두 메서드는 등록·해제 접수 여부를 불리언으로 반환합니다. 이름은 소문자로 시작하는 2–40자의 소문자·숫자·밑줄입니다. 사용자 지정 작업 9개와 기본 open_page를 사용할 수 있습니다. 작업별 문자열 매개변수는 최대 5개이며 모두 필수이고 값은 200자 이내입니다. 설명도 200자 이내입니다. 핸들러는 10초 내 최대 2 KB의 문자열 또는 JSON으로 직렬화 가능한 값을 반환해야 합니다.

대시보드에서 허용하기#

설치한 웹사이트를 열어 작업 이름과 설명을 보고한 뒤 에이전트 → 작업 → 페이지 작업을 엽니다. 기능을 켜고 사용할 작업을 각각 허용하세요. 보고된 설명은 신뢰되지 않은 웹사이트 메타데이터이며 발견만으로 허용되지 않습니다. 설정은 자동 저장됩니다.

현재 등록되어 있고 소유자가 허용한 작업만 제안할 수 있습니다. 실행 전 고객에게 카드가 표시됩니다. 소유자가 안전한 작업으로 지정하지 않으면 확인이 필요하며, 호스트 코드의 confirm: true는 항상 버튼 확인을 요구합니다. confirm: false만으로 소유자 정책을 우회할 수 없습니다. 안전 모드는 단순 UI 변경에만 사용하세요.

기본 open_page는 핸들러가 필요 없습니다. 대시보드에서 허용하면 에이전트의 허용 오리진에 속한 상대 경로나 HTTP(S) URL을 받습니다. 상대 경로는 현재 웹사이트 오리진도 허용되어야 합니다. 임의의 외부 주소로 이동할 수 없습니다.

track으로 이벤트 보고하기#

MakeAgentFast.track("form_error", { formId: "contact" });
MakeAgentFast.track("checkout_help", { step: "delivery" });

임베드 로드 후 해당 이벤트가 실제 발생했을 때 호출하세요. 후속 알림에 일치하는 이벤트 이름을 설정합니다. 이름은 같은 2–40자 형식이며 선택적 데이터는 최대 1 KB의 JSON 객체입니다. 입력값, 자격 증명, 결제 정보를 보내지 마세요. 규칙은 이벤트·경로·지연 시간으로 판단합니다. 메타데이터는 저장하거나 모델에 보내거나 전환 근거로 쓰지 않습니다. true는 로더가 접수했다는 뜻이며 메시지 표시를 뜻하지 않습니다.

안전성과 검증#

실제 웹사이트 위젯에서만 작동하며 메시징 채널, 소유자 리허설, 실시간 음성에서는 사용할 수 없습니다. 로더와 프레임은 오리진, 메시지 출처, 슬러그, 대기 요청 ID를 확인합니다. 결과는 신뢰되지 않은 브라우저 데이터로 채팅에 돌아오며 서버 기록 변경의 증거가 아닙니다. 핸들러·백엔드에서 인증과 권한 검사를 유지하고 중요한 업무 변경에는 변경 작업을 사용하세요.

시간 초과는 핸들러를 취소하거나 미실행을 증명하지 않습니다. 결과가 불명확한 작업을 자동 재시도하지 마세요. 페이지 컴포넌트가 사라지면 등록을 해제하세요. 캐시된 기존 임베드는 이 API를 위해 로더 버전 20261014-page-actions로 갱신해야 합니다.

이 API는 결제나 Shopify 커넥터를 제공하지 않습니다.