Skip to Content
Sottoヘルプ

フォームをサイトに埋め込む

1 行の埋め込みコード、版を固定した改ざん検知つきのコード、JavaScript と React の SDK、自前の入力画面、サーバから送る API の使い方。

Markdownで開く

本文を選択してコピー

クリップボードを利用できません。選択された本文を端末のコピー操作でコピーしてください。

公開したフォームは、フォームの 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/forms

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

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-react
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 が受け持ちます。

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 キーはブラウザのコードに書かないでください。

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

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

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

このページの内容