SDK とは?ライブラリ・フレームワーク・API との違い

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 タグなら不要です。だから公開サイトに向きます。パッケージマネージャーなら必要ですが、版の固定と型の恩恵が得られます。