SDK(software development kit)とは、ある機能を、それを使うために必要なもの一式とともに配布する開発パッケージです。1 つ以上の API、実行時の依存関係、設定と認証情報、ドキュメントとサンプル、場合によってはコマンドラインツールまで含みます。 SDK かどうかを決めるのはコード量ではなく、その機能を使うための周辺作業(認証、エラー処理、ツール)まで一緒に渡しているかです。
違いは実務ではっきりしています。ライブラリは「このロジックを書くのに疲れたなら、私を使って」を解決します。SDK は「この外部機能を繋ぎ込みたいなら、認証から失敗時の扱いまで考えてある」を解決します。
4 つの言葉を切り分ける
| 観点 |
API |
ライブラリ |
フレームワーク |
SDK |
| 呼ぶ方向 |
こちらがリクエストを送る |
こちらが呼ぶ |
向こうが呼ぶ |
こちらが呼び、向こうがツールも提供する |
| 形 |
インターフェースの契約(HTTP や関数シグネチャ) |
再利用できるコード |
骨組み+規約+ライフサイクル |
パッケージ+ドキュメント+設定+サンプル(CLI の場合も) |
| 主導権 |
すべてこちら |
すべてこちら |
フレームワークが流れを決める |
こちら(アプリ構造は奪わない) |
| 典型例 |
REST エンドポイント、GraphQL |
日付処理、グラフ描画 |
フロント/バックのフレームワーク |
クラウド SDK、決済 SDK、フィードバック SDK |
| こちらがやること |
全部 |
組み立てと呼び出し |
規約に沿って業務を書く |
認証情報の取得、ドキュメントに沿った初期化 |
覚え方としては、API は契約、ライブラリは部品、フレームワークは骨組み、SDK は「部品+説明書+配線図」です。
SDK の中身
| 構成要素 |
役割 |
欠けたときに起きること |
| API ラッパー |
HTTP の細部、リトライ、エラーコードを関数にする |
導入先ごとに再実装され、挙動がばらつく |
| ランタイムと依存関係 |
対象環境(ブラウザ、Node サーバー)で動くようにする |
バージョン衝突、バンドルサイズの肥大 |
| 設定と認証情報 |
キー、リージョン、環境、スイッチ |
秘密情報の直書き、テストと本番の混在 |
| ドキュメントとサンプル |
10 分で最初の疎通まで導く |
導入が人への質問依存になり、サポートコストが戻ってくる |
| ツール(任意) |
CLI、デバッグパネル、型定義 |
調査が推測になる |
最後の行は「あれば嬉しい」扱いされがちですが、実際には SDK の評価を決めます。型定義とデバッグ手段が揃った SDK は、導入側の手戻りが明らかに少なくなります。
3 つの配布方式とコスト
| 方式 |
バージョンの決め方 |
更新するのは誰 |
主なコスト |
| パッケージマネージャー(npm など) |
ロックファイルで固定 |
導入側が意図して更新 |
ビルド工程が必要。古いバージョンが数年残る |
| script タグ(CDN) |
URL や設定で決まる |
提供側 |
CSP でドメインを許可する必要。キャッシュ設計も必要 |
| プラットフォーム組み込み |
プラットフォームの版に従う |
プラットフォーム |
ペースをほぼ制御できない |
script タグは「訪問者にも使わせたい」ものに向きます。インストール不要、ビルド不要、1 行貼れば動きます。代わりに、バージョン互換と CSP の許可リストは自前で管理することになります。フィードバック系やサポート系の SDK がこの方式を選ぶのはそのためです。
自前 SDK の隠れたコスト
機能を SDK に包むのは簡単です。その後の 5 年が難しいのです。
後方互換性:公開後の関数名、引数、コールバックのタイミングは自由に変えられません。1 回変えれば、すべての導入先が追随します。
サイズと性能:SDK は他人のページで動きます。100KB 増えれば、そのサイトの初回描画指標が動きます。
プライバシーとコンプライアンス:何を集め、いつまで保持し、無効化できるのかを、文書化し、実際にそう動かす必要があります(私たちの境界はプライバシーポリシーにあります)。
可観測性:SDK 自体が壊れたとき、導入側は「そちらのものが壊れた」としか言いません。独自のエラー収集とバージョン分布が必要です。
ドキュメントとサンプル:ドキュメントのない SDK は SDK ではありません。コストはサポートチケットとして戻ってきます。
この 5 つのうち、最初の 3 つが「公開前は見えず、公開後は避けられない」典型です。
フィードバック SDK の実例
BugCapturer の Web SDK は 2 ステップです。コンソールでプロジェクトを作成してドメインの許可リストを設定し、ページにスクリプトを置くだけです。
html
<script>window.BugCapturerConfig={key:"bcpk_xxxxxxxx",position:"bottom-right",requireContact:false}</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>
設定項目は少なく、それぞれに明確な境界があります。
| 設定 |
役割 |
注意点 |
key |
プロジェクト識別子 |
公開前提。アクセスはドメイン許可リストで制限する |
position |
フローティング入口の位置 |
決済やサポートのボタンを覆わない |
requireContact |
訪問者に連絡先を必須にするか |
公開サイトではオフ推奨。オンにすると提出率が落ちる |
reporter |
報告者の識別情報(サイト側が渡す) |
1 人を固定で書かない。ログイン状態から入れる |
訪問者側の体験は正確に説明すべきです。拡張が入っている訪問者は取得を拡張に任せるため、許可ダイアログは一切出ません。入っていない訪問者は、1 回の報告ごとにブラウザの許可を 1 回確認し、その後にスクリーンショットを撮ります。 これはブラウザのセキュリティモデルであり、手抜きではありません。「完全に無意識のスクリーンショット」をうたう Web SDK があれば、どう実現しているかを一度聞く価値があります。
導入手順の全体は Web SDK クイックスタート にあり、本記事では繰り返しません。
SDK とブラウザ拡張は別物
どちらも「導入形態」と呼ばれますが、境界は異なります。
| 観点 |
SDK |
ブラウザ拡張 |
| 導入する人 |
サイト側(コード内) |
利用者それぞれ |
| 届く範囲 |
すべての訪問者 |
入れた人だけ |
| 権限の出どころ |
ドメイン許可リスト+報告ごとの同意 |
拡張が宣言する権限 |
| 向く場面 |
顧客からのフィードバック収集 |
社内のテストと確認 |
| 主な制約 |
サイトのコード変更が必要 |
顧客は 1 サイトのために拡張を入れない |
つまり「顧客に報告してもらう」は本質的に SDK か共有リンクの話で、拡張は社内向けです。比較はブラウザ拡張とデスクトップツールにあります。
バージョン番号の読み方
更新するのが自分ではないため、通常のライブラリより版管理が重要です。
- メジャー:非互換の変更。導入側のコード修正が必要。
script タグでは版が URL に現れます。提供側は 固定(導入側が上げる時期を決める)と 自動(常に最新)の 2 モードを用意するのが望ましいです。固定は安定、自動は楽ですが、「更新で他人のページを壊さない」自信が前提です。SDK の事故はここから生まれます。
SDK を入れる前に確認する 5 つの質問
| 質問 |
なぜ重要か |
良い答えの形 |
| どんな権限を求めるか |
スクリプトや拡張はページ内容を読める |
最小限の範囲、各項目の説明、無効化可能 |
| どんなデータを集めるか |
コンプライアンスと顧客の信頼 |
明確な一覧、機密項目のマスク、保持期間 |
| 失敗時にページを巻き込むか |
第三者スクリプトの例外は連鎖する |
タイムアウトで主導線を止めない、例外を隔離 |
| サイズと読み込みタイミング |
初回描画指標に直結 |
非同期読み込み、必要時の初期化、サイズの公開 |
| やめるときはどうするか |
移行コストは過小評価される |
データ出力、1 行で除去、残物なし |
2 番目と 5 番目が飛ばされやすく、半年後に問題になります。
自作か購入か
| 状況 |
推奨 |
| その機能が中核事業(自社が決済事業者など) |
自作。SDK 自体が製品 |
| 入口が 1 つ欲しいだけで、保守する人がいない |
購入または既存採用。工数は事業に回す |
| データを社内網から出せない |
自作または自社運用。保守コストを先に試算 |
| 開発 5 人未満、フロント基盤なし |
script タグ方式から。独自のパッケージ基盤は作らない |
判断基準は 1 つです。その機能が今後も開発ロードマップを食べ続けるか。 食べるなら自作、食べないなら「制御したい」という感覚のために長期の負債を抱えないことです。
よくある 3 つの誤解
- API を SDK と呼ぶ:ラッパーもサンプルも設定説明もないエンドポイント資料は API です。
- SDK をフレームワーク扱いする:SDK はアプリ構造を奪うべきではありません。ディレクトリ構成を強制するならフレームワークです。
- 全部入りが良い:何でもできる SDK は、大きいバンドル、広い権限、危険な更新を意味しがちです。必要なものだけ入れます。
よくある質問
SDK と API の関係は?
SDK は通常、ある API のラッパーを含みます。API が契約で、SDK はその契約をツールとドキュメント付きで実装したものです。
SDK とライブラリの違いを 1 文で?
ライブラリは自分が呼ぶコード。SDK は 1 つの機能を繋ぎ込むのに必要な一式(ライブラリ、設定、ドキュメント、ツール)です。
フロントエンドの script タグは SDK ですか?
はい。配布方式は SDK かどうかを決めません。決めるのは版と更新責任の配分だけです。
SDK はページ性能に影響しますか?
します。サイズと読み込みタイミングによります。非同期読み込みと必要時の初期化が定石で、サイズは提供側が公表すべきです。
導入にビルド設定の変更は必要ですか?
script タグなら不要です。だから公開サイトに向きます。パッケージマネージャーなら必要ですが、版の固定と型の恩恵が得られます。