この章では、AppCotton SDK を最小実装で導入するための“土台”（PHP側・JS側）の初期化と基本設定をまとめます。ここに書かれた構成だけで、以下が成立します。
is_premium()のワンライナー評価- ライセンスの 検証（validate） / アクティベーション（activate） / 解除（deactivate） 呼び出し
- キャッシュ / タイムアウト / リトライなどの基本オプション
§0 概要（思想）
- SDKは極力“薄い”ラッパ：AppCotton REST API を安全に呼ぶための薄いヘルパ群。
- 依存を最小限に：WordPress 標準関数（
wp_remote_*/wp_nonce_*/transient）のみに依存。 - どのプラグインにも埋め込みやすい：1ファイル（もしくは小さなディレクトリ）を同梱するだけで導入可。
§1 ディレクトリと同梱物
your-plugin/
├─ your-plugin.php
└─ appcotton-sdk/
├─ sdk.php // PHPコア（初期化・HTTP・キャッシュ・is_premium）
├─ sdk-client.js // ブラウザ側ユーティリティ（任意）
└─ readme.txt
JS が不要な（サーバ側で完結する）場合は
sdk.phpのみで運用可能。
§2 PHP 初期化
2.1 最小の初期化コード（プラグイン側）
// your-plugin.php
defined('ABSPATH') || exit;
require_once __DIR__ . '/appcotton-sdk/sd k.php'; // SDK本体
add_action('plugins_loaded', function () {
AppCotton_SDK::init([
// 必須
'product_slug' => 'combpass_premium', // ←あなたの製品スラッグ
'api_base' => 'https://YOUR-LICENSE-SERVER.TLD/wp-json/appcotton/v1',
// 任意（推奨）
'request_timeout'=> 12, // 秒
'retry' => 1, // 再試行回数（0/1/2）
'cache_ttl' => 5 * MINUTE_IN_SECONDS, // validate結果の短期キャッシュ
// セキュリティ
'send_domain' => home_url(), // ドメイン正規化はSDK側で実施
'send_site_url' => home_url(),
// ログ
'enable_log' => defined('WP_DEBUG') && WP_DEBUG,
]);
});
api_baseは AppCotton側（販売サイト側） の REST ルートを指定。
1プロダクト=1 product_slug が基本。複数製品を扱う場合はAppCotton_SDK::instance('slugA')のように複数インスタンス化できる設計にします。
2.2 is_premium() のワンライナー
あなたのプラグイン内で最小に書くなら：
function yourplugin_is_premium(): bool {
$license_key = get_option('yourplugin_license_key'); // 保存場所は任意
if (empty($license_key)) return false;
return AppCotton_SDK::is_premium($license_key);
}
SDK 内部で
licenses/validateを叩き、usage/is_activated/expires_at/statusなどを総合評価してboolを返します。
高速化のため、成功レスポンスはcache_ttlの間transientで短期キャッシュ。
2.3 アクティベーション/解除 呼び出し
// 追加アクティベーション（現在ドメインで有効化）
$result = AppCotton_SDK::activate($license_key);
// 解除（現在ドメインを利用枠から開放）
$result = AppCotton_SDK::deactivate($license_key);
if (!$result['success']) {
// $result['error'], $result['message'] をUIに表示
}
SDK 側で
domain/site_url/instance_idを自動付与（オプションで上書き可）。
§3 SDK 設定パラメータ（PHP）
| キー | 型 | 既定値 | 説明 |
|---|---|---|---|
product_slug | string | (必須) | このSDKインスタンスが対象とする製品スラッグ |
api_base | string | (必須) | .../wp-json/appcotton/v1 のベースURL |
request_timeout | int | 10 | wp_remote_post/get のタイムアウト秒 |
retry | int | 0 | ネットワーク系失敗時の再試行回数 |
cache_ttl | int | 300 | validate 成功結果のキャッシュ秒 |
send_domain | string | home_url() | 送信するドメイン。SDKで正規化（example.com / sub.example.com） |
send_site_url | string | home_url() | 表示用にそのまま送るURL |
instance_id | string | null | null |
enable_log | bool | false | error_log() に簡易ログ |
§4 JS 初期化（任意）
フロントUI（購入UIや「この端末でアクティベート」ボタン等）を置きたい場合は、SDKの JS を登録して使います。
4.1 enqueue と初期化
add_action('wp_enqueue_scripts', function () {
wp_enqueue_script(
'appcotton-sdk-client',
plugins_url('/appcotton-sdk/sdk-client.js', __FILE__),
['wp-api-fetch'], '1.0', true
);
wp_localize_script('appcotton-sdk-client', 'AppCottonSDK', [
'rest' => [
'base' => 'https://YOUR-LICENSE-SERVER.TLD/wp-json/appcotton/v1/',
'nonce' => wp_create_nonce('wp_rest'), // ログイン時のみ
],
'product_slug' => 'combpass_premium',
'domain' => home_url(),
'site_url' => home_url(),
]);
});
4.2 利用例（ブラウザ）
// validate
const ok = await window.AppCotton.validate('LICENSE-XXXXX-YYYY');
if (ok.valid) {
// プレミアムUIを表示
}
// activate (current domain)
const act = await window.AppCotton.activate('LICENSE-XXXXX-YYYY');
// deactivate
const deact = await window.AppCotton.deactivate('LICENSE-XXXXX-YYYY');
認証は ログイン時は Nonce, 非ログイン時は 公開エンドポイント（サーバ側のCORS許可） を利用。
どちらを使うかはsdk-client.js内で自動判定できる設計にします。
§5 失敗時の振る舞い（要点）
- ネットワーク系：
retry回数ぶん再試行 → 失敗ならerrorにnetwork_error。 - ライセンス不正：
valid=false/error=invalid_license。 - 上限超過：
error=activation_limit_exceeded（usageも返す）。 - サーバ4xx/5xx：HTTPコードを
http_statusに格納（UIでの案内が容易）。
詳細は「エラー規約」章で定義。
§6 キャッシュ戦略
validate成功時のみtransientに短期保存。deactivate/activate実行時は、該当ライセンスのキャッシュを即パージ。- TTLは
cache_ttl（既定300秒）。管理画面ではTTL=0にして強制ミスも可能。
§7 セキュリティ・配慮事項
- ドメイン正規化は SDK 側で実施（
http/httpsや末尾スラッシュ差は無視）。 - Nonce はログインユーザの Ajax/UI 用（
wp_rest）。 - 非ログインでの公開API利用は CORS許可済みの公開ルート のみで実施。
- ライセンスキーの保存は
optionsかuser_meta。画面表示時はマスク（末尾4桁のみ表示）。
§8 便利ヘルパ（推奨）
// 保存・取得（マスク付き）
AppCotton_SDK::save_license_key('yourplugin_license_key', $plain_key);
$masked = AppCotton_SDK::mask($plain_key); // ABCD-****-WXYZ
// 使用状況の取得（used/limit/remaining/activations[]）
$usage = AppCotton_SDK::usage($license_key);
// UI向け：状態テキスト
$status_text = AppCotton_SDK::status_label($license_key);
§9 実装チェックリスト
AppCotton_SDK::init([...])を plugins_loaded で実行product_slug/api_baseを正しく設定is_premium()ワンライナーがtrueになるのを確認activate()/deactivate()が想定どおり動くvalidate()がusage/expires_at/is_activatedを返す- キャッシュが効く（TTL中に高速化）／パージも効く
- 非ログインUIでの呼出（公開REST+CORS）が成功する
以上で SDKコアの初期化と設定 は完了です。
次章では、UI自動生成・エラー規約・Webhook・公開フックの詳細仕様に進みます。