@kiyakuto/js

利用規約への同意管理を Web サイトに組み込むための JavaScript SDK です。 ダイアログ形式で利用規約を表示し、ユーザーの同意を取得できます。

インストール

IIFE（script タグ）

ビルド済みの widget.js を <script> タグで読み込みます。 グローバル変数 Kiyakuto が公開されます。

<script src="https://js.kiyakuto.com/v1/widget.js"></script>
<script>
  Kiyakuto.init({
    projectId: "your-project-id",
    userId: "current-user-id",
    publicKey: "your-public-key",
  });
</script>

ESM（npm パッケージ）

npm install @kiyakuto/js

import { init, show, embed } from "@kiyakuto/js";

注意: ESM ビルドでは react と react-dom が peerDependencies です。 ホストアプリケーション側で React 18 または 19 をインストールしてください。

基本的な使い方

SDK の API はすべて、SDK を読み込むサイトのオリジンが Console のプロジェクト設定「許可オリジン設定」に登録されていることを前提に動作します。未登録のオリジンからのリクエストは 403 で拒否されます。開発環境で試す場合は http://localhost:3000 のような開発サーバーのオリジンも登録してください。

1. 初期化

init() で SDK を初期化します。show() を呼び出す前に必ず実行してください。

Kiyakuto.init({
  projectId: "your-project-id",   // プロジェクト ID（必須）
  userId: "current-user-id",      // ユーザー ID（consent モードで show() を使う場合は必須）
  publicKey: "your-public-key",   // パブリックキー（必須）
  skipConsented: true,             // true の場合、既に同意済みの規約はダイアログに表示されない（省略時: true）
});

2. 同意ダイアログの表示

show() を呼び出すと同意ダイアログが表示されます。 ユーザーが操作を完了すると ConsentResult で解決される Promise を返します。

規約が複数ある場合は 1 件ずつ表示され、「同意して次へ」を押すたびにその規約への同意がその場で記録されます。途中でダイアログを閉じても記録済みの同意はサーバーに残り、次回の show() では未同意の規約だけが表示されます（skipConsented: true の場合）。

const result = await Kiyakuto.show();

if (result.success) {
  // ユーザーが全ての規約に同意した
  console.log("同意完了", result.agreements);
} else if (result.error) {
  // エラーが発生した
  console.error(result.error.message);
} else {
  // ユーザーがダイアログを閉じた（同意せずキャンセル）
  console.log("キャンセル");
}

userId を init() に渡さずに show() を呼ぶと、consent モードでは userId が必須のため例外がスローされます。閲覧専用で使う場合は show({ mode: "view" }) を呼んでください。

閲覧専用モード（view）

show({ mode: "view" }) は同意を記録せず、公開中の規約をダイアログで閲覧するためのモードです。init() は必須ですが、userId は不要です。consent モードと同じく、ダイアログに表示されるのは同意対象の規約のみです（Console で「表示のみ」に設定した規約は表示されません。それらの掲示には embed() を使ってください）。

Kiyakuto.init({
  projectId: "your-project-id",
  publicKey: "your-public-key",
});

const result = await Kiyakuto.show({ mode: "view" });

if (result.success) {
  console.log("閲覧完了", result.agreements);
}

ダイアログをどの方法で閉じても（閉じるボタン、Escape キー、オーバーレイクリック）、success: true と取得した公開規約の全件が返ります。取得時にエラーが発生した場合のみ success: false と error が返ります。

show() の多重呼び出し時の振る舞い

show() を連続して呼び出した場合、最後の呼び出しのみが有効になります。

前回の show() が返した Promise がまだ未解決の状態で新たに show() を呼び出すと、前回の Promise は以下の結果で自動的に resolve されます。

{
  success: false,
  agreements: [],
  error: new Error("[Kiyakuto] Superseded by a new show() call")
}

具体例

// 1回目の呼び出し
const firstPromise = Kiyakuto.show();

// 2回目の呼び出し（1回目はまだ未解決）
const secondPromise = Kiyakuto.show();

// 1回目は即座に resolve される
const firstResult = await firstPromise;
console.log(firstResult.success);        // false
console.log(firstResult.agreements);     // []
console.log(firstResult.error?.message); // "[Kiyakuto] Superseded by a new show() call"

// 2回目のみがアクティブなダイアログとして動作する
const secondResult = await secondPromise;

判定方法

前回の呼び出しがキャンセルされたかどうかは、error プロパティの有無で判定できます。

const result = await Kiyakuto.show();
if (!result.success && result.error) {
  // 新しい show() 呼び出しによってキャンセルされた
  // または他のエラーが発生した
}

ConsentResult

show() が返す Promise の解決値です。

interface ConsentResult {
  /** 同意が正常に完了したかどうか */
  success: boolean;
  /** 同意対象の規約一覧 */
  agreements: Agreement[];
  /** エラー情報（エラー時のみ） */
  error?: Error;
}

| パターン | success | agreements | error | |---|---|---|---| | 全規約に同意完了 | true | 完了時に同意している規約の全集合 | undefined | | ユーザーがキャンセル | false | [] | undefined | | 多重呼び出しによるキャンセル | false | [] | Error ("[Kiyakuto] Superseded by a new show() call") | | view モードで正常閲覧 | true | 取得した公開規約の全件 | undefined | | view モードで取得エラー | false | [] | Error |

ユーザーが途中でキャンセルした場合、agreements は空配列になりますが、キャンセルまでに記録された同意は取り消されずサーバーに残ります。

Agreement

interface Agreement {
  id: string;
  title: string;
  currentVersion: AgreementVersion;
  consented?: boolean;
  createdAt: string;
  updatedAt: string;
}

interface AgreementVersion {
  id: string;
  label: string;
  content: string;
  publishedAt: string;
}

規約の埋め込み（embed()）

embed() は公開中の規約本文を指定した要素の中に描画する、閲覧専用の埋め込み機能です。同意ダイアログとは異なり同意を記録しないため、init() は不要です。規約ページやフッターなど、規約を常設で表示したい場所での利用を想定しています。show() と異なり、Console で「表示のみ」に設定した規約（特定商取引法に基づく表記など、同意を求めない掲示用の文書）も含めた全公開規約を表示します。

function embed(options: EmbedOptions): EmbedInstance;

interface EmbedOptions {
  projectId: string;              // プロジェクト ID（必須）
  publicKey: string;              // パブリックキー（必須）
  target: string | HTMLElement;   // 描画先。CSS セレクタ文字列または要素
  agreementId?: string;           // 指定した 1 件のみ表示（省略時は公開中の全規約）
}

interface EmbedInstance {
  unmount(): void;                // 埋め込みを取り外す
}

使い方

<div id="terms"></div>

<script src="https://js.kiyakuto.com/v1/widget.js"></script>
<script>
  var instance = Kiyakuto.embed({
    projectId: "your-project-id",
    publicKey: "your-public-key",
    target: "#terms",
  });

  // 不要になったら取り外す
  // instance.unmount();
</script>

target には CSS セレクタ文字列と HTMLElement のどちらも渡せます。セレクタ文字列が要素にマッチしない場合は同期的に例外をスローします。指定した要素の既存の中身は保持したまま、その内側に規約が追加で描画されます。

agreementId を指定すると、その規約 1 件だけを表示します（省略時は公開中の全規約）。不存在・非公開・他プロジェクトの ID を渡した場合はエラーにはならず、空の表示になります。

同じ target に対して embed() を再度呼び出すと、以前の埋め込みは自動的に取り外され、新しい内容へ張り替わります。埋め込みを完全に取り除くには、戻り値の unmount() を呼び出してください。

iframe 埋め込み（GET /embed）との使い分け

規約の埋め込みには 2 つの方式があります。ホストページの DOM に直接描画する embed() と、Worker が返す HTML ページを <iframe> で読み込む方式（GET /embed/{projectId}）です。ホストページの DOM やスタイルから完全に分離したい場合は iframe を、ページと一体でスクロールさせたい・ページの文脈になじませたい場合は embed() を選んでください。embed() は Shadow DOM 内に描画するため、いずれの方式でもホストページの CSS の影響は受けません。

オリジンの登録

embed() は公開規約 API を呼び出します。この API はリクエストの Origin ヘッダーを、Console で設定した許可オリジン（allowedOrigins）と照合します。埋め込みを設置するホストページのオリジンを、あらかじめ Console の許可オリジンに登録してください。

注意: 許可オリジン（allowedOrigins）が 1 つも登録されていないプロジェクトでは、すべてのリクエストが 403 で拒否されます（fail-closed）。オリジンが未登録・不許可の場合、embed() は読み込みエラーの表示になり、ブラウザのコンソールに登録を促す警告が出力されます。

リクエストの真正性と方式の選択

SDK（init() + show() / embed()）は publicKey 方式で動作します。publicKey は配布される JavaScript に含まれる公開値のため、Worker はリクエストが「ブラウザから送られた同意である」ことは扱えますが、送信元が正規の利用者であることを暗号学的に識別することはできません。Worker は Console で登録された許可オリジン（allowedOrigins）とリクエストの Origin を照合し、許可外のサイトからのブラウザ経由リクエストを遮断します（ただし許可オリジン上の XSS や、curl 等によるサーバーからの直接送信は遮断対象外です）。

より強い真正性が必要な場合は、Pro プランの JWT 方式をサーバーサイド統合で利用できます。secret key をサーバーで保持して JWT を発行し、Authorization: Bearer で送信すると Worker が署名を検証します。JWT はサーバー間統合のための方式であり、SDK（init() / show() / embed()）からは利用しません（SDK は publicKey 方式のみ）。secret key はクライアントサイド JavaScript に含めないでください。

なお、publicKey 方式は Origin ヘッダを持たないリクエストを常に遮断するため、サーバーからの publicKey 直送はできません。サーバーサイドで同意を送信する構成では JWT 方式（Pro）を利用してください。