mount() 참조

임베드를 만드는 함수의 옵션과 반환값, 정리 방법을 확인합니다.

mount()는 전달한 요소에 카나페 이벤트를 붙이고, 해당 임베드를 정리하는 객체를 반환합니다. 이 함수는 DOM이 있는 브라우저에서 호출합니다.

함수와 반환값

function mount(container: HTMLElement, options: MountOptions): EmbedInstance

interface EmbedInstance {
  destroy(): void
}

container는 임베드를 붙일 HTML 요소입니다. 브라우저 스크립트에서는 window.CanapeEmbed.mount(container, options)로 호출합니다. ES 모듈에서는 mount(container, options)를 사용합니다.

destroy()를 호출하면 그 인스턴스의 iframe과 메시지 수신기, 대기 타이머가 제거됩니다. 같은 인스턴스를 여러 번 정리해도 다른 인스턴스에는 영향이 없습니다.

옵션

옵션	타입	설명
`eventId`	`string`, 필수	이벤트 주소의 `/event/` 뒤에 있는 ID입니다. 영문자, 숫자, 하이픈, 밑줄을 사용할 수 있습니다.
`customUserId`	`string`	고객사에서 로그인한 회원을 구분하는 ID입니다. 이벤트에서 회원 ID 연동을 사용할 수 있어야 합니다.
`signupSession`	`string`	카나페에서 발급된 가입 전환 세션입니다. 가입 전환 연동에서 사용합니다.
`isParticipationBlocked`	`boolean`	`true`이면 이벤트 화면에서 참여를 제한합니다. 고객사 서비스의 참여 권한은 서버에서 검증해야 합니다.
`isForceNewSignupUser`	`boolean`	`true`이면 신규 가입자로 처리하도록 초기 상태를 전달합니다.
`onEvent`	`(event: CanapeEvent) => void`	임베드에서 보낸 이벤트 콜백을 받습니다.
`onError`	`(error: Error) => void`	이벤트 화면을 불러오거나 초기 설정을 확인하는 데 실패하면 호출됩니다.

customUserId와 signupSession을 제공할 때는 공백만 있는 문자열이나 빈 문자열을 전달할 수 없습니다. 회원 ID 연동을 사용하지 않는 이벤트는 eventId만 전달해 표시할 수 있습니다. 회원 ID나 참여 조건 등 초기 설정을 전달하면 헬퍼는 카나페가 초기 설정을 확인한 뒤 화면을 표시합니다.

사용 예제

다음 예제는 브라우저 스크립트를 불러온 뒤 홈의 샘플 이벤트를 직접 붙입니다. 표시할 위치를 없애기 전에 destroy()를 호출합니다.

<div id="canape-event"></div>
<button id="remove-canape-event" type="button">이벤트 닫기</button>

<script src="https://cdn.canape.im/_static/js/canape-embed-helper/@2.0.0/canape-embed-helper.js"></script>
<script>
  const container = document.getElementById('canape-event')
  const instance = window.CanapeEmbed.mount(container, {
    eventId: '63cb945984b6e591a5b5049e52d3d9e1d992b0f15df2fca32018af2d0cc99c68',
    onError(error) {
      console.error(error.message)
    },
  })

  document.getElementById('remove-canape-event').addEventListener('click', () => {
    instance.destroy()
  })
</script>

여러 인스턴스와 화면 전환

이벤트 ID가 같아도 서로 다른 요소에 각각 연결할 수 있습니다. 각 인스턴스는 자기 iframe의 메시지만 받습니다. 동일한 이벤트에 대한 회원의 참여 조건은 이벤트 설정을 따릅니다.

이미 임베드가 연결된 요소에 다시 mount()를 호출하면 즉시 오류가 발생합니다. 같은 위치의 이벤트나 회원을 바꾸려면 기존 인스턴스를 destroy()한 뒤 새 옵션으로 연결하세요. React에서는 화면이 교체되거나 컴포넌트가 사라질 때 정리 함수를 실행합니다. 여러 이벤트 넣기와 React에서 콜백 받기를 참고하세요.

오류 처리

이벤트 ID나 초기 설정의 형식이 잘못됐거나 이미 사용 중인 요소를 넘기면 mount() 호출 시 예외가 발생합니다. 호출을 try/catch로 감싸 입력 오류를 처리할 수 있습니다.

호출이 성공한 뒤에도 이벤트가 준비되지 않거나 초기 설정을 확인할 수 없으면 약 30초 후 임베드에 오류 문구가 표시됩니다. 이때 onError를 등록했다면 Error 객체를 받습니다. 문제를 해결한 뒤 재시도하려면 실패한 인스턴스를 정리하고 다시 mount()를 호출합니다. 문제 해결에서 표시와 연동 설정을 점검할 수 있습니다.