Concepts

用語とライフサイクル

Quickstartで出てくる言葉と、実装時に迷いやすい境界をまとめています。

Product

販売するソフトウェア本体です。1つの Product に価格、説明、サポート先、アクティベーション上限が紐づきます。

License Key

購入後に発行されるキーです。ユーザーがアプリに入力し、アプリが Activatist API に送って検証します。ログに出してはいけません。

Activation

「この端末で使い始める」操作です。同じ端末の再アクティベーションは冪等で、別端末は activation_limit を超えると拒否されます。

Device Fingerprint

端末を見分けるための匿名IDです。メールアドレスや氏名などの個人情報を入れず、安定したランダムIDを使います。

Boundary

Activatistが提供するもの / 実装者が作るもの

Activatistが提供するもの

API base URLhttps://license.souko.work
product_idclosed beta中は、運営/adminが作成・承認したProduct IDをsellerへ共有します。
SDK package言語別zipとして配布します。
license key購入完了ページで購入者に表示されます。

実装者が作るもの

ライセンス入力UI購入者がlicense keyを入力する画面を用意します。
SDK/HTTP呼び出し初回入力時はactivate、起動時はvalidateを呼びます。
有料機能のON/OFFvalidな結果に応じてアプリ内の機能を切り替えます。
ユーザー向けエラー表示409は端末数上限として案内します。

Lifecycle

validate / activate / deactivate の使い分け

タイミング	呼ぶAPI	理由
初回ライセンス入力	`activate`	この端末を利用枠として登録します。
アプリ起動時	`validate`	seatを増やさず、revoke/refund/expiredを確認します。
24時間に1回程度	`validate`	状態変化を反映しつつ、過剰なAPI呼び出しを避けます。
ユーザーが端末解除	`deactivate`	ポリシーが許す場合に利用枠を空けます。
ネットワーク不通	短いgrace	最後の成功状態を短時間だけ使い、復旧後にvalidateします。

Device Fingerprint

端末IDの扱い

SDKを使う場合とHTTP APIを直接呼ぶ場合で、実装者がやることが変わります。

SDKを使う場合

SDKが端末IDを生成・保存します。アプリ側はユーザー入力のlicense keyを渡すだけです。UUID v4相当のランダムIDなら衝突確率は実用上ほぼ無視できます。

HTTP APIを直接使う場合

アプリ側で安定した device_fingerprint を生成・保存してください。メール、氏名、電話番号、IPアドレス、raw hardware serial は使いません。

backendは端末IDのraw値を保存せず、HMAC hashとして扱います。アプリ側でもログには出さないでください。

macOS

Application Support 配下、可能なら Keychain。ファイル保存なら権限を絞ります。

Windows

AppData 配下、可能なら Credential Manager / DPAPI を検討します。

Linux

XDG config 配下に保存し、権限は 0600 相当にします。

Android

EncryptedSharedPreferences や Jetpack Security を優先します。広告ID、電話番号、Googleアカウントなどの個人情報を使いません。

Activation

activate が内部で確認していること

activate は「ライセンスキーが使えるか」と「この端末を利用枠に登録できるか」を同時に確認します。

購入者、アプリ、Activatist Runtime API、ライセンス状態の認証概念図

成功するケース

ライセンスが active
Product が一致している
同じ端末で再実行した
別端末でも activation_limit 内

失敗するケース

キーが存在しない、または別Product用
refund / dispute / revoked / suspended / expired
別端末が上限を超えた
device_fingerprint が空、または不安定

Errors

エラー時の考え方

HTTP	意味	アプリ側の表示例
400	入力が不足、形式が不正	入力内容を確認してください。
403	キーが使えない状態	このライセンスは利用できません。
404	対象が見つからない	ライセンス情報が見つかりません。
409	アクティベーション上限超過	利用可能な端末数の上限に達しました。
429	短時間にリクエストが多すぎる	少し待ってから再試行してください。
5xx	一時的なサーバー障害	時間をおいて再試行してください。

エラーbody例

{
  "request_id": "req_example",
  "code": "activation_limit_exceeded",
  "message": "Activation limit reached"
}

request_id はサポート問い合わせやログ照合に使います。license key と一緒にログへ出さないでください。

Safety Rules

実装時にやってはいけないこと

ログに出さない

ライセンスキー、completion token、buyer email、Firebase token、Bearer token、Stripe/Resend/R2/Cloudflare の秘密情報、presigned URL はログや共有メモに出さないでください。

端末IDに個人情報を使わない

device_fingerprint にメールアドレス、氏名、電話番号、住所などを入れないでください。ランダムIDを作って端末内に保存する方式が扱いやすいです。

毎回 activate しない

起動時チェックは validate、端末登録は activate、端末解除は deactivate と役割を分けます。

対象外の商品に使わない

Activatist は first-party software license 用です。ギフトカード、ポイント、第三者キー転売、C2C resale には使えません。