フォームをサイトに埋め込む
1 行の埋め込みコード、版を固定した改ざん検知つきのコード、JavaScript と React の SDK、自前の入力画面、サーバから送る API の使い方。
公開したフォームは、フォームの URL をそのまま共有するほか、自社のサイトに埋め込めます。コードはフォームの上の「リンク・埋め込み」の「サイトに埋め込む」に、そのフォームの公開 ID(frm_ で始まる文字列)入りで出ます。公開の手順は フォームを作る・公開する を参照してください。
| 方法 | 向いている場合 |
|---|---|
| 1 行の埋め込みコード | HTML に貼るだけで置きたい |
| 版を固定して貼る | 読み込む script に改ざん検知(SRI)を付けたい |
JavaScript(mount)/ React(<SottoForm>) | アプリの中の決まった場所に置きたい |
自前の入力画面(createFormClient / useSottoForm) | 入力画面を自社のデザインで作りたい |
| API から送る | 自社のサーバから送信を渡したい |
どの方法で届いた回答も、同じスパム対策・顧客情報への保存・自動化を通ります。回答の詳細の「実行ログ・技術情報」には、届いた経路(フォームページ / 埋め込み / SDK / API)が出ます。
1 行の埋め込みコード
「サイトに貼る(1 行)」のコードを、フォームを置きたい場所に貼ります。
<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 にしたときの例です。
<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 のイベントが出ます。計測タグへの連携などに使えます。
window.addEventListener("sotto:submitted", (event) => {
const { formId, submissionId } = event.detail;
});版を固定して貼る(改ざん検知つき)
「版を固定して貼る(改ざん検知つき)」のコードは、中身が変わらない版のローダーを integrity 付きで読み込みます。
<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)
npm install @sotto/formsmount は、指定した要素の中にフォームを置きます。
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)
React 18 以上で使えます。
npm install @sotto/forms-reactimport { 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 が受け持ちます。
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
}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キー」で「APIキーを発行」を押します。
- 「この鍵にできること」で「フォームへ送信する(サーバから)」を選び、「使える期間」を決めて「発行する」を押します。
- 表示された鍵を控えます。この画面を閉じると二度と表示できません。
鍵は、発行したワークスペースのフォームにだけ送れます。
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 による判定)は同じに働きます。
受け付けたときの応答です。
{
"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 を受け取る を参照してください。