Pulse

Pulse SDK

Web、React Native、iOS、Android向けのオープンソース分析 SDK です。信頼性の高いオフラインファーストのイベントキューと、クリーンな ID によって、アプリに分析機能を追加できます。それ以外の機能はありません。

• 軽量。 Web SDK は gzip 圧縮後 10 KB 以下で、依存関係はゼロです。
• 高い信頼性。 永続化された順序付きキューにより、オフライン期間やプロセスの終了にも対応します。配信は冪等で、リトライによってイベントが重複することはありません。
• プライバシーに誠実。 自動キャプチャ、フィンガープリンティング、IDFA／GAID、広告 SDK はありません。SDK が送信するのは、呼び出し側が送信を指示したイベントだけです。
• 1 つのプロトコル、4 つのプラットフォーム。 すべての SDK が同じワイヤープロトコルを実装し、CI で同じ適合性フィクスチャに合格します。Pulse 取り込みサーバーも同じフィクスチャを再生するため、契約が両端から検証されます。

このリポジトリには TypeScript パッケージが含まれています。Swift と Kotlin の SDK は pulse-sdk-native にあります。

AI エージェント向け

インストール：npm i @pulse-circle/web を実行し、次に Pulse.init('pk_...') と Pulse.track('event', {...}) を呼び出します。パッケージは自己完結型（依存関係ゼロ、デフォルトのエンドポイントを組み込み済み）で、llms.txt を同梱しています。インストールに必要なのは npm だけです。イベントは実行時にエンドユーザーのブラウザーから配信されます。

パッケージ

パッケージ	用途	インストール
@pulse-circle/web	ブラウザー／あらゆる Web アプリ	npm i @pulse-circle/web
@pulse-circle/react-native	React Native と Expo	npm i @pulse-circle/react-native
@pulse-circle/core	プラットフォーム非依存のエンジン（上記パッケージで使用）	npm i @pulse-circle/core
@pulse-circle/mcp	ローカル（stdio）MCP サーバー — AI エージェント向けのオフライン設定／接続ガイド	claude mcp add pulse -- npx -y @pulse-circle/mcp

クイックスタート（Web）

npm install @pulse-circle/web

import { Pulse } from '@pulse-circle/web';

Pulse.init('pk_your_api_key');

// Track product events — the SDK batches, persists, and retries for you.
Pulse.track('subscription_started', { plan: 'pro' });

// Tie events to a user after login.
Pulse.identify('user_42');

// On logout, start a fresh anonymous identity.
Pulse.reset();

API はこれだけです。各パッケージの README で、プラットフォーム固有のインストール方法（script タグ、Expo など）と完全なリファレンスをご確認ください。

どこでも使える API

5 つのメソッドは、各言語に適した構文で、4 つすべてのプラットフォームで同一です。

init(apiKey, options?)      // configure once
track(event, properties?)   // queue an event
identify(userId)            // associate the current identity with a user id
reset()                     // logout: new anonymous identity
flush()                     // force-send the queue (tests, critical moments)

画面／ページの自動トラッキングや収益関連のメソッドは意図的に用意していません。収益データはサーバーサイドのコネクターから取得するため、各数値の信頼できる情報源は常に 1 つだけです。

信頼性の保証

• すべてのイベントには、track を呼び出した瞬間に idempotency_key と timestamp が付与されます。送信時ではありません。リトライ時には両方ともバイト単位で同一のまま再送され、サーバーの主キーには両方が含まれるため、不安定なネットワークが原因で重複が発生することはありません。
• キューは永続化され（Web では localStorage、モバイルではファイル）、順序が保たれます。プラットフォームごとの上限までは、再読み込み、クラッシュ、オフライン期間を経ても保持されます。上限に達した場合は、無制限に増え続けるのではなく、デバッグ警告を出して古いものから破棄します。
• リトライにはジッターを加えた指数バックオフを使用します。サーバーが拒否し続けるバッチ（「ポイズン」バッチ）は、10 回の試行後に別に移動されるため、その後ろにあるすべての処理を妨げることはありません。

規範となる詳細は protocol/PROTOCOL.md をご覧ください。

開発

npm install
npm test          # conformance fixtures + unit tests (vitest)
npm run lint
npm run typecheck
npm run build     # tsup builds for every package
npm run size -w @pulse-circle/web   # enforce the 10 KB budget

適合性フィクスチャ

protocol/fixtures が、プラットフォーム間の動作に関する信頼できる情報源です。各 JSON ファイルはシナリオ（「これらの API 呼び出しがこれらの HTTP リクエストを生成する」）を表します。すべての SDK が共通のフィクスチャランナーを使って実行し、サーバーは実際のデータ取り込みに対してそれらを再生します。動作を変更するにはフィクスチャを変更します。そうすれば、各プラットフォームの CI で、契約に準拠していない箇所がわかります。

リリース

バージョンはパッケージごとに独立しています。パッケージの package.json でバージョンを上げてから、タグをプッシュします。

core-v0.1.0 | web-v0.1.0 | react-native-v0.1.0

publish ワークフローは、タグが package.json と一致することを確認し、すべてのテスト、ビルド、サイズゲートを実行してから、プロベナンス付きで npm に公開します。

ライセンス

MIT © Pulse Circle Studio