사용 설명서 > 개발자 문서 > SDK(FC) 레퍼런스
SDK 호출 목록
이 글의 목차
앱 안에서는 전역 FC 객체만 서버와 통신하는 통로입니다. 아래 목록에 없는 호출은 검증에서 거절되며, 있어도 필요한 권한을 manifest.permissions 에 선언해야 합니다. 서버는 호출마다 권한·한도·크레딧을 다시 검사합니다.
| 호출 | 필요 권한 | 반환 | 설명 |
|---|---|---|---|
| FC.ready(callback?) | 필요 없음 | Promise<void> | 앱 초기화 시점. 콜백을 주면 즉시 실행한다. 콜백 없이 await FC.ready() 로 써도 된다. 권한이 필요 없다. |
| FC.contact.create(data, options?) | contacts.write | Promise<object> | 연락처를 만든다. data 는 { email, first_name, last_name, phone, ... } 처럼 단순 값 객체다. 같은 요청을 재시도할 때 중복 생성되지 않게 options 로 { operationId: "UUID" } 를 줄 수 있다(같은 operationId 는 한 번만 처리된다). operationId 는 UUID(소문자 36자) 형식이어야 한다. |
| FC.contact.tag(tagKey, options?) | contacts.tag | Promise<object> | 방금 만든 연락처에 태그를 붙인다. tagKey 는 앱 소유자가 설치 때 허용한 태그 키여야 한다. 허용되지 않은 키는 거절된다. |
| FC.event.emit(name, payload?, options?) | events.emit | Promise<object> | manifest.events 에 선언한 이름·필드와 정확히 맞는 이벤트를 기록한다. 선언하지 않은 필드나 타입이 다르면 거절된다. FC.event.track 은 같은 함수의 별칭이다. |
| FC.event.track(name, payload?, options?) | events.emit | Promise<object> | FC.event.emit 의 별칭. |
| FC.automation.trigger(name, payload?, options?) | automation.trigger | Promise<object> | 자동화를 깨우는 이벤트를 보낸다. manifest.events 에 같은 이름을 선언하고 automation.trigger 권한을 선언해야 한다(events.emit 은 자동으로 함께 승인된다). |
| FC.page.redirect(url) | page.redirect | Promise<object> | 방문자를 이동시킨다. 이동 가능한 주소는 서버가 검사한다. |
| FC.form.get() | forms.read | Promise<object> | 앱에 연결된 Form 의 필드 구성을 읽는다. 앱 소유자가 허용한 Form 에 한한다. |
| FC.form.submit(data, options?) | forms.submit | Promise<object> | 연결된 Form 로 제출한다. manifest.form_binding.field_map 으로 앱 필드를 Form 필드·연락처 항목에 연결한다. |
| FC.search.web(query, { action, request_key? }) | search.web | Promise<{ query, results: [{ title, url, domain, snippet, published_at, image, source_type }], mocked }> | manifest.actions 의 search.web Action 으로 웹을 검색한다. 결과의 url 은 링크(<a href>)로만, 제목·요약은 textContent 로 넣는다(innerHTML 금지). |
| FC.ai.generate(input, { action, request_key? }) | ai.generate | Promise<{ text, mocked }> (output "json" 이면 { data, mocked }) | 입력글(4000자 이내)을 ai.generate Action 의 지시문대로 처리한다. 모델·키·비용은 서버가 정한다. 실패하면 거절되며 오류의 reason·message 를 쓸 수 있다. |
| FC.ai.chat(messages, { action, request_key? }) | ai.generate | Promise<{ text, mocked }> | 대화형 Action("mode":"chat") 전용. messages 는 [{ role: "user"|"assistant", content }] 이고 최대 20개, 마지막은 user, 합쳐 4000자 이내다. 대화 기록은 앱이 들고 있다가 매번 전부 보낸다. |
| FC.image.generate(prompt, { action, request_key?, reference? }) | image.generate | Promise<{ dataUrl, mime, mocked }> | AI 이미지를 만든다. dataUrl 은 data:image/…;base64,… 문자열이며 JS 로 만든 <img> 의 src 에만 넣는다. HTML 정적 마크업의 src·href 에는 쓸 수 없다. reference 는 upload.file(purpose ai_input) 로 올린 파일 id 다. |
| FC.pdf.generate(document, { action, request_key? }) | pdf.generate | Promise<{ handle, filename, size }> | 문서 객체({ title, subtitle, meta, sections, footer, filename })를 서버가 PDF 로 그린다. 글자·표·목록만 가능하고 HTML·이미지·링크는 안 된다. 파일은 바깥 화면이 보관하고 앱에는 handle 만 준다. |
| FC.pdf.save(handle) | pdf.generate | Promise<{ ok: true }> | FC.pdf.generate 가 준 handle 의 파일을 방문자가 저장하게 한다. 버튼 클릭 같은 사용자 동작 안에서 부른다. |
| FC.upload.send(file, { action, request_key?, note? }) | upload.file | Promise<{ id, filename, size, kind, mime }> | 방문자가 고른 File 을 올린다. 올리기 전에 바깥 화면이 보관 안내와 동의를 받는다. 이미지(8MB)·PDF(10MB)만 받으며 서버가 파일 내용으로 확인한다. |
| FC.webhook.send(data, { action, request_key? }) | webhook.send | Promise<{ ok: true, mocked }> | 선언한 fields 만 앱 소유자의 Webhook 주소로 POST 한다. 주소·헤더·재시도는 서버가 정하고 응답 본문은 돌려주지 않는다. |
| FC.state.get(name) | 필요 없음 | string | number | boolean | null | format_version 2 전용. manifest.state 에 선언한 값을 읽는다. 서버로 나가지 않고 새로고침하면 초기화된다. |
| FC.state.set(name, value) | 필요 없음 | void | format_version 2 전용. 선언한 이름·타입과 맞아야 한다(맞지 않으면 STATE_TYPE_MISMATCH). |
| FC.state.reset(name?) | 필요 없음 | void | format_version 2 전용. 이름을 주면 그 값만, 안 주면 전부 선언한 기본값으로 되돌린다. |
실패 처리
서버 호출은 모두 Promise 이며 실패하면 거절됩니다. 오류 객체의 code·reason·message 를 읽을 수 있고, message 는 방문자에게 그대로 보여 줘도 되는 문구입니다. HTTP 상태가 있는 오류는 status 가 4xx(408·429 제외)이면 입력을 고쳐야 하는 영구 실패, 그 외(네트워크·5xx·408·429)는 같은 요청을 다시 시도해도 되는 일시 실패로 다루면 됩니다.
지원하지 않는 호출
FC.contact.update, FC.storage.*, FC.http.request, FC.payment.checkout 은 현재 지원하지 않으며 검증에서 거절됩니다(unsupported_sdk_api).