# フォームをサイトに埋め込む (/docs/forms-embed)

公開したフォームは、フォームの URL をそのまま共有するほか、自社のサイトに埋め込めます。コードはフォームの上の「リンク・埋め込み」の「サイトに埋め込む」に、そのフォームの公開 ID（`frm_` で始まる文字列）入りで出ます。公開の手順は [フォームを作る・公開する](/docs/forms) を参照してください。

| 方法 | 向いている場合 |
|---|---|
| 1 行の埋め込みコード | HTML に貼るだけで置きたい |
| 版を固定して貼る | 読み込む script に改ざん検知（SRI）を付けたい |
| JavaScript（`mount`）/ React（`<SottoForm>`） | アプリの中の決まった場所に置きたい |
| 自前の入力画面（`createFormClient` / `useSottoForm`） | 入力画面を自社のデザインで作りたい |
| API から送る | 自社のサーバから送信を渡したい |

どの方法で届いた回答も、同じスパム対策・顧客情報への保存・自動化を通ります。回答の詳細の「実行ログ・技術情報」には、届いた経路（フォームページ / 埋め込み / SDK / API）が出ます。

## 1 行の埋め込みコード [#1-行の埋め込みコード]

「サイトに貼る（1 行）」のコードを、フォームを置きたい場所に貼ります。

```html
<script async src="https://forms.sotto.la/embed.js" data-sotto-form="frm_8FqK2mZp4XbN"></script>
```

- script の直前にフォームが入ります。1 つのページに複数置けます。
- フォームの高さは中身に合わせて自動で変わります。
- 置いたページの URL・UTM（`utm_` で始まるクエリ）・参照元を送信に添えます。自動化の条件に使え、回答の詳細にも残ります。
- `embed.js` は Sotto が改善を配るため、中身が変わります。改ざん検知を付けたいときは、下の「版を固定して貼る」を使ってください。

### 非表示の値を渡す [#非表示の値を渡す]

「非表示の値」の項目で「値の出どころ」を「埋め込み側から渡す値」にすると、`data-sotto-hidden-<埋め込み側で渡す名前>` で値を渡せます。名前を `plan` にしたときの例です。

```html
<script async src="https://forms.sotto.la/embed.js" data-sotto-form="frm_8FqK2mZp4XbN" data-sotto-hidden-plan="team"></script>
```

出どころを「URL のクエリ」「UTM」にした項目は、フォームを置いたページの URL から自動で読みます。

### 送信が終わったことを受け取る [#送信が終わったことを受け取る]

送信が終わると、script の親要素と `window` に `sotto:submitted` のイベントが出ます。計測タグへの連携などに使えます。

```js
window.addEventListener("sotto:submitted", (event) => {
  const { formId, submissionId } = event.detail;
});
```

## 版を固定して貼る（改ざん検知つき） [#版を固定して貼る改ざん検知つき]

「版を固定して貼る（改ざん検知つき）」のコードは、中身が変わらない版のローダーを `integrity` 付きで読み込みます。

```html
<script async src="https://forms.sotto.la/embed/v1.js" data-sotto-form="frm_8FqK2mZp4XbN" integrity="sha384-…" crossorigin="anonymous"></script>
```

- 固定した版の中身は変わりません。改善は新しい番号の版として足し、古い版も残します。
- 最新の固定版の場所と `integrity` の値は `https://forms.sotto.la/embed-manifest.json` に出ます。

## JavaScript（@sotto/forms） [#javascriptsottoforms]

```bash
npm install @sotto/forms
```

`mount` は、指定した要素の中にフォームを置きます。

```ts
import { mount } from "@sotto/forms";

const handle = mount(document.getElementById("contact")!, {
  form: "frm_8FqK2mZp4XbN",
  hidden: { plan: "team" },
  onReady: () => {},
  onSubmitted: ({ formId, submissionId }) => {},
  onError: ({ code }) => {},
});

// 画面から外すとき
handle.destroy();
```

bundler を使わないページでは、`https://forms.sotto.la/sdk/v1/sotto-forms.js` を読み込むと `window.SottoForms` から `mount` と `createFormClient` を使えます。

## React（@sotto/forms-react） [#reactsottoforms-react]

React 18 以上で使えます。

```bash
npm install @sotto/forms-react
```

```tsx
import { SottoForm } from "@sotto/forms-react";

export function Contact() {
  return (
    <SottoForm
      form="frm_8FqK2mZp4XbN"
      hidden={{ plan: "team" }}
      onSubmitted={({ submissionId }) => console.log(submissionId)}
    />
  );
}
```

`onReady`・`onError`・`className` も渡せます。

## 自前の入力画面で作る [#自前の入力画面で作る]

入力画面を自社のデザインで作るときは、`createFormClient`（React なら `useSottoForm`）を使います。検証はサーバと同じ規則で行い、ボットかどうかの確認と送信は SDK が受け持ちます。

```ts
import { createFormClient } from "@sotto/forms";

const client = createFormClient({ form: "frm_8FqK2mZp4XbN" });
const form = await client.load(); // 題名・項目・文言
const values = { email: "taro@example.jp", message: "資料をください" };

const errors = client.validate(values); // 問題が無ければ空の配列
const result = await client.submit(values, { hidden: { plan: "team" } });
if ("error" in result) {
  // result.error.code と、項目ごとの result.error.fields（key と code）
} else {
  // result.successMessage / result.redirectUrl
}
```

```tsx
import { useSottoForm } from "@sotto/forms-react";

export function ContactForm() {
  const { form, values, setValue, errors, status, submit } = useSottoForm("frm_8FqK2mZp4XbN");
  if (!form) return null;
  if (status === "submitted") return <p>{form.definition.successMessage}</p>;
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        void submit();
      }}
    >
      <input
        value={String(values.email ?? "")}
        onChange={(event) => setValue("email", event.target.value)}
      />
      {errors.email ? <p>{errors.email}</p> : null}
      <button type="submit" disabled={status === "submitting"}>
        {form.definition.submitLabel}
      </button>
    </form>
  );
}
```

- `values` のキーは項目のキーです。`client.load()`（`useSottoForm` なら `form`）の `definition.fields` に、項目ごとの `key`・`type`・`label`・`required` が入っています。
- `useSottoForm` の `status` は `loading` / `ready` / `submitting` / `submitted` / `error` です。`errors` は項目のキーごとのエラーのコード、`error` は送信全体のエラー（通信が途切れたときのコードは `network`）です。
- 送信の前に、SDK が見えない iframe で `https://forms.sotto.la/challenge` を開いてボットかどうかを確かめます。普段は何も見えず、操作が必要なときだけ画面の右下に確認の枠が出ます。自社のドメインを登録するなどの準備は要りません。
- 同じ送信を送り直しても、受け付けられるまでは 1 件にまとまります。

`client.load()` はフォームが見つからないときなどに `SottoFormsError`（`code` 付き）を投げます。`client.submit()` は下の「エラー」のコードを戻り値で返し、通信が途切れたときや想定外の応答のときだけ例外を投げます。

## API から送る（サーバから） [#api-から送るサーバから]

自社のサーバから送信を渡すときは、API キーで送ります。**API キーはブラウザのコードに書かないでください。**

1. 組織の管理者が「設定 > セキュリティ」の「APIキー」で「APIキーを発行」を押します。
2. 「この鍵にできること」で「フォームへ送信する（サーバから）」を選び、「使える期間」を決めて「発行する」を押します。
3. 表示された鍵を控えます。この画面を閉じると二度と表示できません。

鍵は、発行したワークスペースのフォームにだけ送れます。

```bash
curl -X POST https://forms.sotto.la/api/v1/forms/frm_8FqK2mZp4XbN/submissions \
  -H "Authorization: Bearer $SOTTO_API_KEY" \
  -H "Idempotency-Key: 5f0c1f7e-2b8a-4d0e-9a51-7c3e2d9b8f10" \
  -H "Content-Type: application/json" \
  -d '{"values":{"email":"taro@example.jp","message":"資料をください"}}'
```

- `Idempotency-Key` は必須です（8〜200 文字）。同じキーで送り直すと、新しい送信を作らずに最初の結果を返します。送信ごとに新しいキーを使い、再送では同じキーを使ってください。
- `values` のキーは項目のキーです。公開中のフォームの項目は `GET https://forms.sotto.la/api/v1/forms/<公開 ID>` の `definition.fields` で確かめられます。
- `context` を付けると、UTM などを添えられます: `{"utm": {"utm_source": "partner"}, "referrer": "https://…", "sourceUrl": "https://…", "locale": "ja"}`。
- 本文は 64 KB までです。
- API キーで送った送信には、ブラウザでのボットの確認を行いません。ほかの迷惑送信対策（使い捨てメールアドレス・重複・AI による判定）は同じに働きます。

受け付けたときの応答です。

```json
{
  "ok": true,
  "submissionId": "5b1d2c3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "successMessage": "送信しました。ありがとうございました。",
  "redirectUrl": null
}
```

### エラー [#エラー]

エラーは `{"error": {"code": "…", "message": "…", "fields": […]}}` の形で返ります。`fields` は `invalid_fields` のときだけ付き、`[{"key": "email", "code": "invalid_email"}]` のように項目ごとの理由が入ります。

| 状態 | code | 意味 |
|---|---|---|
| 400 | `invalid_request` | 本文の形が正しくない、64 KB を超えた、`Idempotency-Key` が無い |
| 400 | `invalid_fields` | 入力が項目の規則に合わない（`required`・`invalid_email`・`too_long`・`disposable_email` など） |
| 400 | `session_expired` | ブラウザからの送信で、ページの有効期限が切れた（SDK は自動で取り直して送り直します） |
| 400 | `challenge_failed` | ブラウザからの送信で、ボットかどうかを確かめられなかった |
| 401 | `unauthorized` | API キーが正しくない、期限切れ、または失効している |
| 403 | `unauthorized` | API キーに「フォームへ送信する（サーバから）」が無い。またはブラウザからの送信で、フォームを置けるサイトに入っていない |
| 404 | `not_found` | フォームが無い、公開されていない、または鍵と違うワークスペースのフォーム |
| 409 | `paused` | 受付停止中、または運営により停止されている |
| 429 | `over_limit` | 送信が集中している。時間をおいて送り直してください |

## フォームを置けるサイトを絞る [#フォームを置けるサイトを絞る]

「リンク・埋め込み」の「サイトに埋め込む」にある「埋め込み先の制限」で、「埋め込み許可サイト」に `https://example.com` のようにサイトを入れると（20 件まで）、次のようになります。空ならどのサイトにも置けます。

- 埋め込んだフォームは、入れたサイトの中でだけ表示されます。
- ブラウザからの送信とボットの確認は、入れたサイトからだけ通ります。
- API キーを使ったサーバからの送信には影響しません。

変更は公開し直した後に効きます。

自社のサイトで Content-Security-Policy を設定しているときは、`https://forms.sotto.la` を `script-src`（`embed.js` と SDK の読み込み）、`frame-src`（フォームと確認の枠）、`connect-src`（`createFormClient` と `useSottoForm` の送信）に足してください。

## 送信を自社のシステムで受け取る [#送信を自社のシステムで受け取る]

受け付けた回答を自社のシステムへ届けるには、自動化の処理「Webhook に送る」を使います。本文と署名の検証は [フォームの Webhook を受け取る](/docs/webhooks) を参照してください。