수명 주기와 저장

고요한 경험은 안정적으로 작동해야 해요. 빠르게 시작하고, 보이지 않을 때는 쉬며, 저장 내용을 잃거나 두 번 기록하지 않아요.

핸드셰이크

플랫폼은 해시에 #zc_parent=…&zc_instance=…를 넣어 시작 페이지를 불러와요.
connect()는 응답을 받을 때까지 250밀리초마다 ID와 버전이 담긴 zc.ready를 보내요.
플랫폼은 승인 내용과 ID, 버전, 프로토콜을 대조해요. 컨텍스트와 비공개 포트를 담은 zc.connected로 응답하거나 연결을 거부해요.
그 뒤 모든 호출은 해당 포트를 거쳐요. 페이지를 새로 고치면 세션이 끝나고 방문자는 플랫폼에서 다시 시작해요.

15초 안에 준비 완료하기

먼저 loading.start()를 호출하고 방문자가 시작할 수 있는 즉시 loading.ready()를 호출해요. 큰 리소스는 그 뒤에 불러와요. 15초 안에 준비되지 않으면 플랫폼은 방문자에게 문제가 있다고 알려요. 시작할 수 없다면 loading.fail(message)을 호출해요.

수명 주기 명령

명령	동작
`pause`	소리, 애니메이션, 입력을 멈추고 `paused`를 보고해요.
`resume`	방문자가 멈춘 지점부터 이어서 진행하고 `running`을 보고해요.
`visibility`	연결 직후 한 번, 이후 변경될 때마다 전송돼요. `visible`이 false이면 일시 정지한 것처럼 쉬어요.
`dispose`	타이머를 멈추고 SDK가 저장을 반영하도록 해요. 응답 즉시 프레임이 제거되며, 늦어도 1초 뒤에는 제거돼요.

시간을 세지 말고 세션을 보고하기

상태가 바뀔 때마다 session.report({state, mode})를 호출하고 실행 중에는 몇 초마다 반복해요. 플랫폼은 서버에서 이 보고를 바탕으로 시간을 측정해요. paused를 받거나 12초 동안 아무 보고도 받지 않으면 측정을 멈춰요.

리비전으로 저장 보호하기

저장할 때마다 리비전이 하나씩 증가해요. 마지막으로 확인한 리비전을 전달해요. 다른 탭이나 기기에서 그 사이에 기록했다면 진행 상황을 덮어쓰지 않고 CONFLICT 오류가 발생해요.

같은 요청 ID로 재시도하기

TIMEOUT 또는 INTERNAL 오류는 기록 실패가 아니라 결과를 모른다는 뜻이에요. 같은 데이터를 같은 requestId로 다시 보내요. 서버는 중복 기록하지 않고 첫 결과를 반환해요. 다른 데이터에 ID를 재사용하면 IDEMPOTENCY_CONFLICT 오류가 발생해요.

자동 저장에 맡기는 간격

storage.createAutosave(save)는 각 간격에 함수를 최대 한 번 호출해요. 기본값은 10초이며 10초부터 5분까지 설정할 수 있어요. 내용이 바뀔 때마다 schedule()을 호출해요. 일시 정지, 숨김, 폐기 시점과 실행 완료 또는 방문자가 나가기 전에는 SDK가 즉시 저장을 반영해요. 세 번 실패하면 onError로 SAVE_UNCONFIRMED를 보고해요. 더 최신 변경 사항을 저장해야 한다면 함수에서 false를 반환해요.

채널이 닫혔을 때

onDisconnect는 한 번 실행돼요. 방문자에게 보이는 상태를 유지하고 저장을 멈춘 다음, 경험을 다시 열어 이어갈 수 있다고 차분히 알려요. 직접 재연결을 시도하지 마세요.