================================================================================
ACS Conversion Button - プラグイン仕様書
バージョン: 1.1.0
最終更新日: 2026-02-18
================================================================================

目次
────────────────────────────────────────────────────────────────────────────────
1. プラグイン概要
2. バージョン履歴
3. ファイル構成
4. 定数一覧
5. 無料版・Pro版 機能対比
6. 投稿メタフィールド一覧
7. グローバルオプション
8. クラス別仕様
   8.1  ACS_Conversion_Button (メインクラス)
   8.2  ACS_CB_License        (ライセンス管理)
   8.3  ACS_CB_Updater        (自動更新)
   8.4  ACS_CB_Metabox        (管理画面メタボックス)
   8.5  ACS_CB_Frontend       (フロントエンド表示)
   8.6  ACS_CB_Tracker        (クリック計測)
   8.7  ACS_CB_Settings       (設定ページ)
9. AJAX アクション一覧
10. REST API / ライセンスサーバー連携
11. 自動更新の仕組み
12. CSSクラス・HTML構造
13. JavaScript の仕様
14. ACS License Manager 連携設定
15. 今後の拡張に向けた注意事項


================================================================================
1. プラグイン概要
================================================================================

プラグイン名    : ACS Conversion Button
プラグインスラッグ: acs-conversion-button
テキストドメイン : acs-conversion-button
ライセンス製品   : ACSC（ライセンスキー形式: ACSC-XXXX-XXXX-XXXX-XXXX）
プラグインURI   : https://locany.net/acs-conversion-button/
Author         : Locany
Author URI     : https://locany.net
ライセンスサーバー: https://locany.net
WordPress 最低要件: 6.0
PHP 最低要件   : 7.4

概要:
  投稿・固定ページごとに最適なフローティングCTAボタンを画面下部に表示する
  "Contextual Conversion" プラグイン。
  ページ単位でボタンテキスト・URL・色を設定でき、直帰率低下・コンバージョン
  向上を目的とする。


================================================================================
2. バージョン履歴
================================================================================

v1.0.0 (2026-02-18)
  - 初回リリース
  - メインファイル・全クラス・CSS/JS 実装完了
  - ACS License Manager との連携（product_slug バグ修正: acsc → acs-conversion-button）

v1.1.0 (2026-02-18)
  - 背景設定セクションに背景色カラーピッカーを追加（Pro版）
    Post meta: _acs_cb_bg_color / デフォルト: #000000
  - ボタン下テキスト（sub_headline）フィールドを追加（Pro版）
    Post meta: _acs_cb_sub_headline
  - class-settings.php の Pro版機能リストを 5 項目に更新
    （画像ボタン / 2ボタン表示 / 背景色カスタマイズ / 背景濃度調整 / ボタン下テキスト）
  - フロントエンド HTML に .acs-cb-sub-headline 要素を出力
  - フロントエンド CSS に .acs-cb-sub-headline スタイルを追加


================================================================================
3. ファイル構成
================================================================================

acs-conversion-button/
├── acs-conversion-button.php       # メインファイル・定数定義・クラスローダー
├── includes/
│   ├── class-license.php           # ライセンス認証・検証・AJAX ハンドラ
│   ├── class-updater.php           # 自動更新チェック (WordPress update API 連携)
│   ├── class-metabox.php           # 投稿メタボックス UI・保存
│   ├── class-frontend.php          # フロントエンド HTML 出力
│   ├── class-tracker.php           # クリック数集計 (AJAX)
│   └── class-settings.php          # グローバル設定ページ・ライセンスタブ
├── assets/
│   ├── css/
│   │   ├── admin.css               # 管理画面スタイル
│   │   └── frontend.css            # フロントエンド スタイル
│   └── js/
│       ├── admin.js                # 管理画面JS (カラーピッカー・画像UP・ライセンス認証)
│       └── frontend.js             # フロントエンドJS (表示制御・クリック計測)
├── templates/                      # 将来の テンプレート拡張用（現在は空）
└── ACS_CONVERSION_BUTTON_SPEC.txt  # 本仕様書


================================================================================
4. 定数一覧
================================================================================

定数名                     デフォルト値                    説明
--------------------------  ----------------------------  --------------------
ACS_CB_VERSION             '1.1.0'                        プラグインバージョン
ACS_CB_FILE                __FILE__                       プラグイン絶対パス
ACS_CB_PATH                plugin_dir_path(__FILE__)      プラグインディレクトリ
ACS_CB_URL                 plugin_dir_url(__FILE__)       プラグインURL
ACS_CB_BASENAME            plugin_basename(__FILE__)      プラグイン識別子
ACS_CB_SLUG                'acs-conversion-button'        プラグインスラッグ
ACS_CB_LICENSE_SERVER_URL  'https://locany.net'           ライセンスサーバーURL
ACS_CB_PRODUCT_SLUG        'acs-conversion-button'        製品スラッグ

重要: ACS_CB_PRODUCT_SLUG は WooCommerce 商品メタフィールド _acs_product_slug
      と完全一致していないとライセンス認証が失敗します。


================================================================================
5. 無料版・Pro版 機能対比
================================================================================

機能                           無料版    Pro版
──────────────────────────────────────────────
テキストボタン1個表示             ✅        ✅
ボタン背景色/文字色変更           ✅        ✅
訴求テキスト（ヘッドライン）       ✅        ✅
クリック数計測（ボタン1）          ✅        ✅
表示位置設定                     ✅        ✅
アニメーション設定                ✅        ✅
画像ボタン対応                    ❌        ✅
2ボタン表示                       ❌        ✅
背景色カスタマイズ（カラーピッカー）❌        ✅
背景濃度調整（0〜100%）           ❌        ✅
ボタン下テキスト表示               ❌        ✅
クリック数計測（ボタン2）          ❌        ✅


================================================================================
6. 投稿メタフィールド一覧
================================================================================

フィールドキー                 型         Pro版   デフォルト    説明
──────────────────────────────────────────────────────────────────────────────
_acs_cb_enabled               int(0/1)   No      0           ボタン表示ON/OFF
_acs_cb_headline              string     No      ''          訴求テキスト（上部）
_acs_cb_btn1_text             string     No      ''          ボタン1 テキスト
_acs_cb_btn1_url              string     No      ''          ボタン1 URL（必須）
_acs_cb_btn1_bg_color         string     No      '#2271b1'   ボタン1 背景色
_acs_cb_btn1_text_color       string     No      '#ffffff'   ボタン1 文字色
_acs_cb_btn1_clicks           int        No      0           ボタン1 クリック数
_acs_cb_btn1_last_click       string     No      ''          ボタン1 最終クリック日時
_acs_cb_btn1_image_id         int        Yes     0           ボタン1 画像ID
_acs_cb_btn2_enabled          int(0/1)   Yes     0           ボタン2 有効/無効
_acs_cb_btn2_text             string     Yes     ''          ボタン2 テキスト
_acs_cb_btn2_url              string     Yes     ''          ボタン2 URL
_acs_cb_btn2_bg_color         string     Yes     '#06C755'   ボタン2 背景色
_acs_cb_btn2_text_color       string     Yes     '#ffffff'   ボタン2 文字色
_acs_cb_btn2_image_id         int        Yes     0           ボタン2 画像ID
_acs_cb_btn2_clicks           int        Yes     0           ボタン2 クリック数
_acs_cb_btn2_last_click       string     Yes     ''          ボタン2 最終クリック日時
_acs_cb_bg_color              string     Yes     '#000000'   帯の背景色（カラーピッカー）
_acs_cb_bg_opacity            int(0-100) Yes     50          帯の背景濃度（%）
_acs_cb_sub_headline          string     Yes     ''          ボタン下テキスト

注意事項:
  - _acs_cb_btn1_url が空の場合はフロントエンドで何も表示しない
  - _acs_cb_bg_color と _acs_cb_bg_opacity を組み合わせて RGBA に変換して
    背景色として適用（opacity=0 の場合は背景なし）
  - Pro版フィールドは save_meta() 内で $is_pro チェック後にのみ保存される


================================================================================
7. グローバルオプション
================================================================================

オプション名: acs_cb_global_settings
型: array

キー               デフォルト          有効値                   説明
───────────────────────────────────────────────────────────────────────────────
display_position   'bottom-center'     bottom-center           表示位置
                                       bottom-left
                                       bottom-right
z_index            9999                1〜99999                z-index 値
animation          'slide-up'          slide-up, fade, none    表示アニメーション
post_types         ['post','page']     公開済み投稿タイプ配列   対象投稿タイプ

その他のオプション:
  acs_cb_activated  bool     プラグイン初回有効化フラグ
  acs_cb_version    string   インストール済みバージョン

ライセンス関連オプション（ACS_CB_License が管理）:
  acs_cb_license_key     string   ライセンスキー
  acs_cb_license_status  string   ライセンス状態 (active/inactive/expired/invalid)
  acs_cb_license_data    array    ライセンス情報（製品名・有効期限・残日数等）

Transient:
  acs_cb_welcome_notice  bool（TTL: 300s）  インストール完了通知フラグ
  acs_cb_pro_status      bool（TTL: 12h）   Pro版判定キャッシュ
  acs_cb_update_info     array（TTL: 12h）  更新情報キャッシュ


================================================================================
8. クラス別仕様
================================================================================

────────────────────────────────────────────────────────────────────────────────
8.1 ACS_Conversion_Button (メインクラス)
ファイル: acs-conversion-button.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン
グローバルヘルパー: acs_conversion_button()

主要メソッド:
  load_dependencies()  includes/ の全クラスを require_once
  init_hooks()         activation/deactivation/plugins_loaded/init フック登録
  activate()           デフォルトオプション設定・ウェルカム Transient 設定
  deactivate()         flush_rewrite_rules
  load_textdomain()    翻訳ファイル読み込み
  init_components()    全クラスのシングルトンを初期化（管理画面/フロント分岐）

初期化順序（init フック 優先度10）:
  1. ACS_CB_License::get_instance()
  2. ACS_CB_Updater::get_instance()
  3. ACS_CB_Frontend::get_instance()
  4. ACS_CB_Tracker::get_instance()
  5. is_admin() の場合のみ:
     ACS_CB_Metabox::get_instance()
     ACS_CB_Settings::get_instance()


────────────────────────────────────────────────────────────────────────────────
8.2 ACS_CB_License (ライセンス管理)
ファイル: includes/class-license.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン
オプションキー:
  ACS_CB_LICENSE_KEY_OPTION    = 'acs_cb_license_key'
  ACS_CB_LICENSE_STATUS_OPTION = 'acs_cb_license_status'
  ACS_CB_LICENSE_DATA_OPTION   = 'acs_cb_license_data'
Transient: ACS_CB_PRO_STATUS_TRANSIENT = 'acs_cb_pro_status' (TTL: 12h)

公開メソッド:
  is_pro()                  bool   Pro版かどうか（Transient キャッシュあり）
  get_license_key()         string ライセンスキーを取得
  get_license_status()      string ライセンス状態を取得
  get_license_data()        array  ライセンスデータを取得
  activate_license($key)    bool   ライセンスを認証（AJAX から呼ばれる）
  deactivate_license()      bool   ライセンスを解除
  background_license_verify()     バックグラウンドで週次再検証

静的メソッド:
  get_status_label($status) string ステータスの日本語ラベル
  get_status_color($status) string ステータスカラー(HEX)

AJAX アクション（登録）:
  wp_ajax_acs_cb_activate_license    → activate_license_ajax()
  wp_ajax_acs_cb_deactivate_license  → deactivate_license_ajax()
  wp_ajax_acs_cb_check_license       → check_license_ajax()

API リクエスト（api_request メソッド）:
  エンドポイント: {ACS_CB_LICENSE_SERVER_URL}/wp-json/acs/v1/validate-license
  メソッド: POST
  HMAC 署名: sha256, キー=サイトURL
  送信フィールド:
    license_key  (string)  ライセンスキー
    product_slug (string)  'acs-conversion-button'
    site_url     (string)  home_url()
    timestamp    (int)     time()
    signature    (string)  HMAC-SHA256

ステータス値:
  'active'    - 有効なPro版
  'inactive'  - 未認証（デフォルト）
  'expired'   - 有効期限切れ
  'invalid'   - 無効なキー
  'revoked'   - 取り消し済み
  'error'     - 通信エラー


────────────────────────────────────────────────────────────────────────────────
8.3 ACS_CB_Updater (自動更新)
ファイル: includes/class-updater.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン
Transient:
  TRANSIENT_UPDATE_INFO = 'acs_cb_update_info' (TTL: 12h / エラー時: 1h)

フックへの登録:
  pre_set_site_transient_update_plugins → check_for_update()
  plugins_api                            → plugins_api_info()
  upgrader_process_complete              → after_update()

バージョン情報取得先:
  GET {ACS_CB_LICENSE_SERVER_URL}/wp-json/acs-api/v1/plugin-version/acs-conversion-button

レスポンス期待フィールド:
  version       string  最新バージョン番号
  download_url  string  ZIP ダウンロードURL
  changelog     string  変更履歴テキスト
  marketing_text string マーケティング文言（任意）
  requires      string  最低 WordPress バージョン
  tested        string  テスト済み WordPress バージョン
  requires_php  string  最低 PHP バージョン


────────────────────────────────────────────────────────────────────────────────
8.4 ACS_CB_Metabox (管理画面メタボックス)
ファイル: includes/class-metabox.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン
メタボックスID: 'acs_cb_metabox'
表示位置: normal / 優先度: high

登録フック:
  add_meta_boxes         → add_meta_boxes()
  save_post(10,2)        → save_meta()
  admin_enqueue_scripts  → enqueue_scripts()

enqueue_scripts():
  対象ページ: post.php / post-new.php
  スタイル: acs-cb-admin (admin.css) - 依存: wp-color-picker
  スクリプト: acs-cb-admin (admin.js) - 依存: jquery, wp-color-picker
  wp_enqueue_media() も呼び出し
  acsCbAdmin オブジェクト（wp_localize_script）:
    ajaxUrl     admin_url('admin-ajax.php')
    nonce       acs_cb_metabox_nonce
    isPro       bool
    proLabel    string
    selectImg   string
    removeImg   string
    upgradeUrl  string

render_metabox（$post）が取得するメタ値一覧:
  共通: _acs_cb_enabled, _acs_cb_headline
        _acs_cb_btn1_text, _acs_cb_btn1_url
        _acs_cb_btn1_bg_color (#2271b1), _acs_cb_btn1_text_color (#ffffff)
        _acs_cb_btn1_image_id, _acs_cb_btn1_clicks, _acs_cb_btn1_last_click
  Pro版: _acs_cb_btn2_enabled, _acs_cb_btn2_text, _acs_cb_btn2_url
         _acs_cb_btn2_bg_color (#06C755), _acs_cb_btn2_text_color (#ffffff)
         _acs_cb_btn2_image_id, _acs_cb_btn2_clicks, _acs_cb_btn2_last_click
         _acs_cb_bg_opacity (50), _acs_cb_bg_color (#000000)
         _acs_cb_sub_headline

UI セクション構成:
  ┌─ Pro版バナー（無料版のみ表示）────────────────────────────────────┐
  │  画像ボタン・2ボタン表示・背景色変更・背景濃度調整・ボタン下テキストは Pro版で使用可能
  └───────────────────────────────────────────────────────────────────┘
  [トグル] フローティングボタンを表示
  [セクション] 訴求テキスト（1行）
  [セクション] ボタン1設定
    - ボタン文言 / リンク先URL
    - ボタン背景色（カラーピッカー）/ ボタン文字色（カラーピッカー）
    - ボタン画像（Pro版）
  [セクション] ボタン2設定（Pro版）
    - ボタン2有効化トグル
    - ボタン2文言 / URL / 背景色 / 文字色 / 画像
  [セクション] 背景設定（Pro版）
    - 背景色（カラーピッカー）         ← v1.1.0 新規追加
    - 背景色濃度（レンジスライダー）
  [セクション] ボタン下テキスト（Pro版）← v1.1.0 新規追加
    - 補足テキスト入力
  [セクション] クリック計測（統計表示のみ）

save_meta() 保存処理:
  - Nonce 検証 ('acs_cb_save_meta')
  - DOING_AUTOSAVE / edit_post 権限チェック
  - 共通フィールド: 無条件で保存
  - Pro版フィールド: $is_pro == true の場合のみ保存
  - sanitize_hex_color で色バリデーション
  - esc_url_raw で URL サニタイズ
  - absint で画像ID サニタイズ


────────────────────────────────────────────────────────────────────────────────
8.5 ACS_CB_Frontend (フロントエンド表示)
ファイル: includes/class-frontend.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン

登録フック:
  wp_enqueue_scripts → enqueue_scripts()
  wp_footer(100)     → render_button()

表示条件 (should_display):
  - is_admin() == false
  - is_singular() == true
  - 投稿タイプがグローバル設定の post_types に含まれる

スクリプト/スタイル:
  acs-cb-frontend (frontend.css)
  acs-cb-frontend (frontend.js)
  acsCbData オブジェクト:
    ajaxUrl  string
    nonce    string (acs_cb_track)
    postId   int

render_button() 出力 HTML 構造:
  <div class="acs-cb-wrapper acs-cb-pos-{position} acs-cb-anim-{animation} [acs-cb-wrapper--pro] [acs-cb-wrapper--two-buttons]"
       id="acs-cb-wrapper"
       style="z-index: {z_index}; [background-color: rgba(r,g,b,a);]">
    <button class="acs-cb-close" id="acs-cb-close">×</button>
    [<div class="acs-cb-headline">{headline}</div>]      // 値があれば
    <div class="acs-cb-buttons">
      // ボタン1（画像または文字）
      <a class="acs-cb-btn acs-cb-btn--[image|text] acs-cb-btn--1"
         data-acs-cb-btn data-post-id="{id}" data-btn-num="1" ...>
      // ボタン2（Pro版・btn2_enabled・btn2_url がある場合のみ）
      <a class="acs-cb-btn acs-cb-btn--[image|text] acs-cb-btn--2" ...>
    </div>
    [<div class="acs-cb-sub-headline">{sub_headline}</div>]  // Pro版・値があれば
  </div>

背景色計算:
  $rgba = hex_to_rgba($bg_color, $bg_opacity / 100)
  opacity == 0 の場合は background-color スタイルを出力しない


────────────────────────────────────────────────────────────────────────────────
8.6 ACS_CB_Tracker (クリック計測)
ファイル: includes/class-tracker.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン

登録AJAXアクション:
  wp_ajax_acs_cb_track         → track_click()
  wp_ajax_nopriv_acs_cb_track  → track_click()

track_click():
  - Nonce 検証 (acs_cb_track)
  - post_id, btn（1または2）のバリデーション
  - 投稿の存在確認
  - _acs_cb_btn{N}_clicks をインクリメント
  - _acs_cb_btn{N}_last_click に現在時刻を保存
  - 最小レスポンス返却（sendBeacon 互換）

その他メソッド:
  get_stats($post_id)         配列で clicks と last_click を返す
  reset_stats($post_id)       クリック数と日時をリセット


────────────────────────────────────────────────────────────────────────────────
8.7 ACS_CB_Settings (設定ページ)
ファイル: includes/class-settings.php
────────────────────────────────────────────────────────────────────────────────

パターン: シングルトン
管理メニュー: 設定 > ACS ConvBtn
オプションページスラッグ: acs-conversion-button
設定グループ: acs_cb_settings_group

登録フック:
  admin_menu        → add_admin_menu()
  admin_init        → register_settings()
  admin_notices     → show_welcome_notice()
  admin_enqueue_scripts → enqueue_scripts()（settings_page_acs-conversion-button のみ）

タブ構成:
  ?tab=general  基本設定（表示位置・アニメーション・z-index・対象投稿タイプ）
  ?tab=license  ライセンス管理（認証・解除・Pro版機能一覧・価格テーブル）

ライセンスタブの状態分岐:
  $is_pro == false または $lic_key が空
    → ライセンス入力フォーム + 価格テーブル表示
  $is_pro == true かつ $lic_key が存在
    → 認証済みキー表示 + 解除ボタン

Pro版機能リスト（v1.1.0 時点）:
  1. 画像ボタン対応
  2. 2ボタン表示
  3. 背景色カスタマイズ（カラーピッカーで帯の背景色を自由に変更）
  4. 背景濃度調整（0%〜100%）
  5. ボタン下テキスト（免責事項・補足テキスト表示）

価格テーブル:
  1日: ¥100（キャンペーン期間限定）
  30日: ¥980（月額・短期プロジェクト）★人気
  365日: ¥9,800（年額・継続運用）


================================================================================
9. AJAX アクション一覧
================================================================================

アクション名                   権限          クラス             説明
─────────────────────────────────────────────────────────────────────────────
acs_cb_activate_license        ログイン済み  ACS_CB_License     ライセンス認証
acs_cb_deactivate_license      ログイン済み  ACS_CB_License     ライセンス解除
acs_cb_check_license           ログイン済み  ACS_CB_License     ライセンス状態確認
acs_cb_track                   全員          ACS_CB_Tracker     クリック計測

Nonce 一覧:
  acs_cb_metabox_nonce   メタボックス保存
  acs_cb_license_nonce   ライセンス操作（acsCbAdmin.licenseNonce）
  acs_cb_track           クリック計測


================================================================================
10. REST API / ライセンスサーバー連携
================================================================================

ライセンス検証エンドポイント:
  URL    : https://locany.net/wp-json/acs/v1/validate-license
  Method : POST
  必須パラメータ:
    license_key  string  ライセンスキー
    product_slug string  'acs-conversion-button'
    site_url     string  home_url()
    timestamp    int     UNIX タイムスタンプ
    signature    string  HMAC-SHA256(license_key + product_slug + site_url + timestamp, site_url)

ライセンス解除エンドポイント:
  URL    : https://locany.net/wp-json/acs/v1/deactivate-license
  Method : POST
  パラメータ: 上記と同様

バージョン情報エンドポイント:
  URL    : https://locany.net/wp-json/acs-api/v1/plugin-version/acs-conversion-button
  Method : GET
  レスポンス（JSON）:
    version       string
    download_url  string
    changelog     string
    marketing_text string（任意）
    requires      string
    tested        string
    requires_php  string


================================================================================
11. 自動更新の仕組み
================================================================================

1. WordPress が update_plugins トランジェントを更新するタイミングで
   pre_set_site_transient_update_plugins フックが発火。
2. ACS_CB_Updater::check_for_update() がバージョン情報をライセンスサーバーから取得。
3. 現在バージョン (ACS_CB_VERSION) と比較し、新バージョンがあれば
   $transient->response[ ACS_CB_BASENAME ] に情報をセット。
4. WordPress 標準のプラグイン一覧に「更新あり」バッジが表示される。
5. plugins_api フックで「詳細を表示」ポップアップに changelog 等を表示。
6. アップデート完了後、after_update() でキャッシュをクリア。

キャッシュ:
  - 更新情報は 12h キャッシュ（Transient）
  - エラー時は 1h キャッシュ（再試行間隔を空ける）


================================================================================
12. CSSクラス・HTML構造
================================================================================

─── ラッパー ───────────────────────────────────────────────────
.acs-cb-wrapper                 基本ラッパー（position: fixed, bottom: 0）
.acs-cb-pos-bottom-center       下部中央（left:0, right:0, align-items:center）
.acs-cb-pos-bottom-left         下部左（left:16px, max-width:360px）
.acs-cb-pos-bottom-right        下部右（right:16px, max-width:360px）
.acs-cb-wrapper--pro            Pro版専用クラス（追加スタイルなし・識別用）
.acs-cb-wrapper--two-buttons    2ボタン時のボタン幅調整用

─── アニメーション ──────────────────────────────────────────────
.acs-cb-anim-slide-up           初期: translateY(100%) opacity:0
.acs-cb-anim-fade               初期: opacity:0
.acs-cb-anim-none               アニメーションなし
.acs-cb-visible                 表示状態（JSが付与）
.acs-cb-hidden                  非表示（translateY(110%)）

─── 子要素 ──────────────────────────────────────────────────────
.acs-cb-close                   閉じるボタン（absolute, top:6px, right:10px）
.acs-cb-headline                上部訴求テキスト（font-weight:600, color:#fff）
.acs-cb-buttons                 ボタンコンテナ（flex, gap:10px）
.acs-cb-btn                     ボタン共通
.acs-cb-btn--text               テキストボタン（min-width:200px）
.acs-cb-btn--image              画像ボタン（Pro版）
.acs-cb-btn--1 / .acs-cb-btn--2 ボタン番号識別
.acs-cb-sub-headline            ボタン下テキスト（Pro版, font-size:12px）

─── 管理画面 ────────────────────────────────────────────────────
.acs-cb-metabox                 メタボックス全体
.acs-cb-pro-banner              Pro版告知バナー
.acs-cb-pro-badge               ⭐ Pro バッジ
.acs-cb-section                 設定セクション（背景:#fafafa, border-radius:8px）
.acs-cb-section--stats          統計セクション（背景:#f0f6fc）
.acs-cb-pro-field               Pro版フィールド
.acs-cb-pro-locked              ロック状態（opacity:0.55, pointer-events:none）
.acs-cb-toggle                  トグルスイッチ
.acs-cb-color-picker            カラーピッカーターゲット
.acs-cb-image-picker            画像ピッカーコンテナ
.acs-cb-range                   レンジスライダー
.acs-cb-bg-preview              背景色プレビュー（スウォッチ付き）


================================================================================
13. JavaScript の仕様
================================================================================

─── frontend.js ────────────────────────────────────────────────────────────

初期化タイミング: DOMContentLoaded または即時実行

処理フロー:
  1. #acs-cb-wrapper を取得（なければ終了）
  2. 300ms 後に .acs-cb-visible クラスを付与（アニメーション開始）
  3. #acs-cb-close クリックで .acs-cb-hidden 付与 + sessionStorage に記録
  4. ページロード時に sessionStorage を確認 → 閉じていれば hidden のまま
  5. [data-acs-cb-btn] クリックで post_id と btn 番号を取得
  6. navigator.sendBeacon で AJAX に追跡データを送信（フォールバック: fetch）

─── admin.js ────────────────────────────────────────────────────────────────

initMetabox():
  - #acs_cb_enabled の変更でフィールド群の表示/非表示 slideDown/slideUp
  - #acs_cb_btn2_enabled の変更でボタン2フィールドの表示/非表示
  - #acs_cb_bg_opacity の input イベントで #acs_cb_bg_opacity_val を更新
  - .acs-cb-color-picker に wpColorPicker を初期化

initImageUploader():
  - .acs-cb-image-select クリックで wp.media フレームを開く
  - 選択後に hidden input に ID をセット、プレビュー更新、削除ボタン追加
  - .acs-cb-image-remove クリックで input/preview/ボタンをクリア

initLicenseManager():
  - #acs_cb_activate_btn: ライセンスキーを AJAX で認証 → 成功後リロード
  - #acs_cb_deactivate_btn: 確認ダイアログ → AJAX 解除 → リロード
  - #acs_cb_check_btn: AJAX で状態確認 → 結果表示


================================================================================
14. ACS License Manager 連携設定
================================================================================

ACS License Manager に以下の設定が必要:

▼ class-generator.php ($prefix_map に追加):
  'acs-conversion-button' => 'ACSC'

▼ class-update-notifier.php (get_supported_products に追加):
  'acs-conversion-button' => 'ACS Conversion Button'

▼ WooCommerce 商品の設定:
  商品メタフィールド _acs_product_slug = 'acs-conversion-button'
  (この値とACS_CB_PRODUCT_SLUG が一致しないと認証エラーになります)

バージョン管理:
  License Manager 管理画面 > アップデート管理 から
  スラッグ 'acs-conversion-button' で登録し、
  download_url に ZIP のダウンロードURLを設定する。

License Manager 更新バージョン: v1.1.0
  (class-generator.php と class-update-notifier.php に上記内容が追加済み)


================================================================================
15. 今後の拡張に向けた注意事項
================================================================================

1. 新しい投稿メタを追加する場合:
   a) class-metabox.php の render_metabox() に表示 HTML を追加
   b) class-metabox.php の save_meta() に保存処理を追加
   c) class-frontend.php の render_button() に出力処理を追加
   d) 本仕様書（セクション6）のメタフィールド一覧を更新

2. Pro版フィールドを追加する場合:
   - save_meta() の `if ( $is_pro )` ブロック内に追加
   - render_metabox() でも Pro 版ロック状態を正しく設定

3. ライセンスサーバーのエンドポイントを変更する場合:
   ACS_CB_LICENSE_SERVER_URL 定数を更新（acs-conversion-button.php）

4. 自動更新の製品スラッグを変更してはいけない:
   ACS_CB_PRODUCT_SLUG は WooCommerce 商品の _acs_product_slug と
   完全一致させること。変更するとライセンス認証が破壊される。

5. バージョン番号の変更箇所:
   - acs-conversion-button.php: Version ヘッダー / ACS_CB_VERSION 定数
   - 本仕様書のバージョン履歴（セクション2）

6. CSS クラス命名規則:
   プレフィックス .acs-cb- を必ず使用すること（他プラグインとの衝突防止）

7. nonce の管理:
   - メタボックス保存: 'acs_cb_save_meta' / フィールド名 'acs_cb_nonce'
   - ライセンス操作: 'acs_cb_license_nonce' → JS では acsCbAdmin.licenseNonce
   - クリック計測: 'acs_cb_track' → JS では acsCbData.nonce

8. テンプレート拡張（templates/ ディレクトリ）:
   将来的には templates/floating-button.php 等を利用した
   テンプレートオーバーライドを実装予定。
   現在はフロントエンド HTML をすべて class-frontend.php に直書きしている。

================================================================================
以上
================================================================================
