=== Click Analytics for Cocoon ===
Contributors: hwinote
Tags: cocoon, analytics, click, download, affiliate
Requires at least: 6.4
Requires PHP: 7.4
Stable tag: 1.2.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Cocoonのクリック解析データを読み取り専用で分析し、広告・ダウンロード・商品単位で集計します。必要な場合だけGoogle AdSense公式レポートも追加表示できます。

== Description ==

Click Analytics for Cocoon は、Cocoon が保存しているクリック解析データを読み取り専用で分析する管理画面用プラグインです。Cocoon本体のクリック解析DBへ INSERT / UPDATE / DELETE は行いません。

主な機能:

* 広告／ダウンロード分類と、商品・リンク／商品・ファイル単位の集計
* 元記事別、掲載場所別、推移（日次／月次）、ランキング
* クリック数、推定表示回数、CTR、日次ユニーク合計、平均クリック時間
* Amazon ASIN、楽天市場、Yahoo!ショッピングの商品識別
* アフィリエイト識別子の確認（Amazon tag、楽天公式リンク形式、Yahoo!ショッピングのバリューコマースsid/pid、遷移先を特定できる「もしもアフィリエイト」のa_id/p_id。方式不明は未設定と断定しない）
* 未分類リンクの確認、分類・商品の追加、商品候補の除外・復元
* Pochipp / Rinker / Cocoon / WPDM / AdRotate等の生成元・根拠確認
* WPDMの `wpdmdl` / `#unlock` とCocoon識別子を利用したダウンロード解析
* CSVエクスポート、WordPressダッシュボードウィジェット
* CCA解析画面のデフォルト表示期間を設定可能（初期値は今月）
* Cocoon互換性・動作チェック、テストデータモード
* 集計キャッシュと遅延読み込みによる管理画面負荷の抑制
* 任意のGoogle AdSense Management API連携（概要、前期間比較、日別推移、広告ユニット、広告形式・配置、デバイス）

「ダウンロード数」は、Cocoonのクリック解析に記録された対象リンクのクリック数です。実際のファイル転送完了数ではありません。

Cocoon 2.9.6 / クリック解析DB 0.8.0 のスキーマ・関連関数との互換性を確認しています。実際の利用可否は「Click Analytics → システム情報」でも確認できます。

== Installation ==

詳しい説明は同梱の `docs/INSTALLATION.md` を参照してください。正式公開前の実環境チェックは `docs/RELEASE-CHECKLIST.md`、検証・公開判断の現在地は `docs/RELEASE-STATUS.md` にまとめています。Google AdSense連携については `docs/ADSENSE.md`、問題が発生した場合は `docs/TROUBLESHOOTING.md` にまとめています。Googleの7日失効・実再接続・実DB負荷の優先手順は `docs/REAL-ENV-VALIDATION.md` を参照してください。WordPress.orgではなくHwinoteのブログからZIPで配布する版です。


1. ZIPを「プラグイン → 新規プラグインを追加 → プラグインのアップロード」からインストールします。
2. プラグインを有効化します。
3. Cocoon側のクリック解析が有効になっていることを確認します。
4. 「Click Analytics → 概要」を開きます。通常は初期設定のまま確認を始められます。
5. 「その他」に未分類リンクがある場合だけ、必要に応じて「分類・生成元を確認」→「追加」で登録します。
6. データがない場合は「システム情報」のテストデータモードでCCA側の表示を確認できます。AdSense用のテストデータは生成せず、AdSense接続時はGoogleから取得した実データを表示します。

Google AdSense連携は任意です。利用する場合だけ「設定 → AdSense」で、まず「最初に接続手順を確認する」を開いてからGoogle Cloud OAuthクライアントを設定し、読み取り専用で接続してください。Google Auth Platformの「テスト中／本番環境」はOAuthの公開ステータスであり、AdSenseデータのテスト／本番を切り替えるものではありません。ご自身のサイトでまず利用する場合は「テスト中」での接続を案内していますが、7日ごとの再接続が必要です。

== Frequently Asked Questions ==

= WordPress・PHPの必要バージョンは？ =

WordPress 6.4以上、PHP 7.4以上を最低要件としています。Cocoon 2.9.6／クリック解析DB 0.8.0を参照基準にしていますが、すべての環境での動作を保証するものではありません。サイトの「Click Analytics → システム情報」で互換性を確認してください。

= v1.2.0では集計やAdSense APIを変更しましたか？ =

いいえ。v1.2.0はv1.0.28から版数と配布文書を整理したブログ配布版です。集計・キャッシュ・AdSense API／OAuth・高速タブ・CSVなどの実処理は変更していません。

= AdSense公式ホームと「直近7日／30日」の数値が違うのはなぜですか？ =

CCAの「直近7日／30日」は今日を含む期間です。AdSense公式ホームの「過去7日間」は昨日までの7日間で、「過去28日間」は30日間とは日数も違います。比較時は期間指定で日付・アカウント・対象サイト・指標を合わせてください。

= 7日失効・再接続の動作は確認されていますか？ =

「テスト中」7日経過後の案内・Google再接続・接続日時の更新・再接続後の解析について、利用者から実環境で正常だったと報告を受けています。


= Cocoonのクリック解析データを書き換えますか？ =

いいえ。Cocoonのクリック解析テーブルは読み取り専用で利用します。分類や商品など、本プラグイン独自の設定だけをWordPressのoptionsへ保存します。

= 最初に設定画面を変更する必要がありますか？ =

通常はありません。まず「概要」を確認し、「その他」に残ったリンクや広告／ダウンロードの未登録候補だけを必要に応じて登録してください。

= 推定表示回数とCTRは実測値ですか？ =

推定表示回数はCocoonのサンプリング情報から算出した参考値です。CTRもCocoonと同じ重み付け情報を利用し、標本不足の場合は「データ不足」と表示します。

= Google AdSense解析は必須ですか？ =

いいえ。初期状態では無効です。利用者が「設定 → AdSense」で有効化し、自身のGoogle Cloud OAuthクライアントを設定して接続した場合だけGoogleへ通信します。

= AdSenseはどのように接続しますか？ =

「設定 → AdSense」の「最初に接続手順を確認する」を開くと、Google CloudでのAdSense Management API有効化、OAuth同意画面、テストユーザー、ウェブアプリケーション用OAuthクライアント、リダイレクトURI登録、CCAへのクライアント情報入力、Google接続、テスト運用時の再接続までを順番に確認できます。Google Cloudの画面構成は変更される場合があるため、同じ画面にあるGoogle公式リンクも併せて確認してください。

= Googleユーザーから複数のAdSenseアカウントが返る場合は？ =

同時に複数アカウントを解析せず、設定画面で1アカウントだけを固定して使用します。利用可能なアカウントが1件なら選択欄は表示せず、2件以上ある場合だけ使用する1件を選択します。

= 同じAdSenseアカウントで複数サイトを管理している場合は？ =

「設定 → AdSense」でデフォルト解析対象サイトを保存できます。AdSense解析画面では、その設定を書き換えずに「すべてのサイト」または個別サイトへ一時切り替えできます。

= WordPressとAdSenseで「今日」の日付が違う場合は？ =

Cocoon解析はWordPressサイトの時間帯、AdSenseはAdSenseアカウントのレポート時間帯を基準にします。「今日」の日付が異なる場合だけ注意を表示し、詳細から双方の実日付と時間帯を確認できます。

= AdSenseではどの権限を要求しますか？ =

AdSense Management APIの読み取り専用スコープ `adsense.readonly` だけを要求します。本プラグインからAdSense側の設定や広告を変更することはありません。

= AdSenseデータは30分ごとに自動更新されますか？ =

いいえ。取得したレポートを30分間キャッシュし、期限を過ぎた後にAdSense解析画面やダッシュボードを次に表示した時点でGoogleから再取得します。画面を開いていない間に30分ごとのバックグラウンド通信は行いません。最新値をすぐ確認する場合はAdSense解析画面の「再取得」を使用します。

= 「テスト中」と「本番環境」は何が違いますか？ =

これはGoogle OAuthの公開ステータスです。AdSenseレポートのテストデータ／本番データを切り替える設定ではなく、「テスト中」でもCCAは接続したAdSenseアカウントの実データを取得します。「テスト中」は登録したテストユーザーだけが認可でき、開発・テスト段階ではOAuth検証を行わずに接続確認を進めやすい一方、CCAが要求する `adsense.readonly` では認可と更新トークンが同意から7日で期限切れになります。「本番環境」はテストユーザー限定とこの7日制限がなくなりますが、アプリの設定や要求スコープによってGoogleのブランド確認・OAuth検証等が必要になる場合があります。

= なぜCCAでは「テスト中」での利用を案内していますか？ =

CCAは利用者自身のGoogle CloudプロジェクトとOAuthクライアントを使用します。ご自身のWordPressサイトでAdSense連携を利用するだけなら、まず「テスト中」にして自分のGoogleアカウントをテストユーザーへ追加する方法が、Google側の公開・検証手続きを増やさず接続確認を始めやすいためです。「テスト中」は必須ではなく、「本番環境」に切り替えるかどうかは利用者自身がGoogle側の要件を確認して選択できます。

= Google Auth Platformを「テスト中」のまま使い続けられますか？ =

はい。テストユーザーとして利用を続けることはできます。ただしCCAが要求する `adsense.readonly` は基本プロフィールだけの例外には該当しないため、「テスト中」では認可と更新トークンが同意から7日で期限切れになります。継続して使う場合は、7日ごとに「設定 → AdSense」の「Google AdSenseへ再接続」から同じGoogleアカウントで再認証してください。Google側の仕様は将来変更される可能性があります。

= AdSense接続が7日後に切れた場合は？ =

Googleから `invalid_grant` が返った場合、CCAは認証失効として専用メッセージを表示します。Google Auth Platformを「テスト中」で利用している場合は想定される7日失効の可能性があります。通常はOAuthクライアントID／シークレットを作り直す必要はなく、「設定 → AdSense」の「Google AdSenseへ再接続」から再認証すれば利用を再開できます。

= プラグインを削除すると設定も消えますか？ =

初期設定では分類や表示設定などの通常設定を残します。ただし安全のため、AdSenseの更新トークン・保存済みクライアントシークレット・一時キャッシュはプラグイン削除時に必ず削除します。「設定 → データ管理」で削除を選んだ場合は、本プラグイン自身の通常設定とユーザー別設定も削除します。Cocoon本体のクリック解析データは削除しません。

== External Services ==

Google AdSense連携を利用する場合だけGoogleの外部サービスへ通信します。AdSense連携は初期状態では無効で、利用者が「設定 → AdSense」で有効化し、自身のGoogle Cloud OAuthクライアントを設定して接続した場合に限り通信します。

通信先と用途:

* Google Accounts OAuth 2.0 (`accounts.google.com`) — 利用者によるGoogle認証。
* Google OAuth token endpoint (`oauth2.googleapis.com`) — 認証コードの交換とアクセストークン更新。
* Google AdSense Management API v2 (`adsense.googleapis.com`) — AdSenseアカウント、登録サイト、読み取り専用レポートの取得。

Googleへ送信する情報には、OAuth認証に必要なクライアント情報・認証コード／更新トークン、およびAdSenseレポート取得に必要なアカウント識別子、期間、指標、ディメンション、選択したサイトフィルタが含まれます。Cocoonのクリック解析DB、WordPress記事本文、本プラグインの分類設定をAdSense APIへ送信することはありません。要求するOAuthスコープは `https://www.googleapis.com/auth/adsense.readonly` のみです。

サービス: https://developers.google.com/adsense/management
Google APIs Terms of Service: https://developers.google.com/terms
Google Privacy Policy: https://policies.google.com/privacy
Google API Services User Data Policy: https://developers.google.com/terms/api-services-user-data-policy

== Changelog ==

= 1.2.0 =
* v1.0.28を基準としたHwinoteブログ正式配布版。Cocoon 2.9.6との互換性確認を反映し、版数・導入文書・確認状況を更新。集計・分類・AdSense API・キャッシュ等の実処理は変更なし。
* Google OAuth「テスト中」の7日失効案内、再接続、接続日時の更新、再接続後の解析は利用者実環境で確認済み。大量実DB負荷等は未確認。

= 1.0.28 =
* 設定 → AdSenseの接続・キャッシュ・解除操作を3区画に整理。成功したGoogle接続の最終接続日時と経過日数を表示。既存接続の履歴は未記録として扱う。

= 1.0.26 =
* AdSense解析の数値が公式画面と一時的に異なる場合について、取得状態の下に「詳細」付きの注意案内を追加。
* CocoonのSQL集計とキャッシュを模擬性能監査。解析・API・キャッシュ更新処理は変更なし。

= 1.0.25 =

* プラグイン削除時、外部オブジェクトキャッシュ上の現在のAdSense短期アクセストークンをWordPressのAPI経由で削除するよう改善。
* 既存の集計、認証、API、設定、CSV、管理画面UIは変更しない。

= 1.0.24 =
* Google OAuth「テスト中」の失効後表示、実際の再接続、Cocoon実DB負荷の具体的な手順と合格条件を docs/REAL-ENV-VALIDATION.md に追加。オフラインで認証失効・古いレポートの表示・接続失敗時の旧設定保持を模擬確認。既存機能のコードは変更なし。

= 1.0.23 =
* 日別推移の分割集計で、途中期間の取得元が不明な場合に不完全な結果をキャッシュしないよう修正。正常な0件の扱いは維持。
* 使用中のWordPressが7.1.3との利用者申告を記録。PHP/Cocoonとの組合せ確認が未完了のため「Tested up to」は引き続き記載しない。

= 1.0.22 =
* 正式公開前の実環境チェックリストを追加。7日失効・Google実再接続・大量実DB負荷など未確認事項と合格条件を明確化。
* 動作確認できていないWordPressの版を「Tested up to」として表記しない方針に変更。コードの実処理は変更なし。

= 1.0.21 =
* HwinoteブログからのZIP配布に向け、README・インストール／更新手順・AdSense設定・トラブルシューティングを整備。
* WordPress/PHP最低要件、Cocoon互換性の確認方法、期間プリセットの比較、7日失効と実環境未確認事項を明記。
* 実処理の変更はありません。v1.0.20からの変更は文書とバージョン表記のみです。


= 1.0.20 =
* AdSense高速タブ切り替えの回帰テストを追加。期間・サイト変更、再取得、戻る／進む、通信失敗時の標準遷移と連続クリックを検証。
* AdSense解析の初回表示URLに集計条件がない場合も、生成済みの正規タブURLをメモリへ記録し、最初の戻り操作を高速化。
* 通信待ちに訪問済みタブへ戻る場合、不要な通信を中断。Google API・集計・設定・サーバーキャッシュの処理は変更なし。

= 1.0.19 =
* AdSense解析のタブ切り替えで、一度表示したタブを短時間のページ内メモリから再表示し、繰り返しのWordPress画面読み込みを抑制。初回タブと「再取得」は通常取得。
* 戻る／進む・表示部品の再初期化に対応。サーバーのAPIキャッシュ・集計仕様は変更なし。
= 1.0.18 =
* Cocoon集計SQLが失敗してもゼロ件としてtransientへ保存していた問題を修正。データベース障害時はキャッシュせず、次の読み込みで再試行します。
* 日付分割された推移集計で途中のSQL失敗があった場合、不完全な日付範囲の結果をキャッシュしないよう改善。正常な0件のキャッシュと期間・集計仕様は維持。

= 1.0.17 =
* AdSense再接続で新しい接続先のアカウント取得を先に確認し、失敗時に以前の接続情報を維持するよう改善。正常時は一覧取得の重複通信を省略。
* テスト環境の7日失効と再接続を模擬検証。実際のGoogle認証操作と7日経過後の表示は別途確認が必要。

= 1.0.16 =
* 呼び出されていない古い表表示・テストデータ補助メソッド8件を整理。集計・設定・表示の仕様変更なし。
* READMEの旧バージョン表記を修正し、配布文書を同期。

= 1.0.15 =
* AdSenseのOAuth再接続時、新しい更新トークンが返らない場合に旧トークンを流用しないよう修正。旧接続情報は維持して再接続を案内。

= 1.0.14 =
* AdSense解析の期間案内を折りたたみ式に変更。直近7日・直近30日の選択時は公式ホームとの違いを警告し、そのほかは簡潔な詳細案内を表示します。
* 期間の選択時点で表示を切り替え、集計期間やAPI処理は変更しません。

= 1.0.13 =
* AdSense解析に集計期間の説明を追加。CCAの「直近7日／30日」は今日を含み、AdSense公式の「過去7日間／30日間」は昨日までを対象とします。
* 画面表示のみの変更です。集計期間・データ取得・広告分類の処理は従来どおりです。

= 1.0.12 =
* AdSenseのアカウント・サイト一覧が複数ページに分かれた場合も最後まで取得するよう改善。途中エラーでは不完全な一覧を保存しません。
* ブログ配布・日本語専用の開発方針を文書へ反映。既存の画面・集計・CSVは変更しません。

= 1.0.11 =
* 広告・ダウンロードCSVのUTF-8 BOMを正しく出力するよう修正。数式開始文字の前に空白・タブ・改行等がある場合も安全に出力。
* PHP 8.4のCSV出力警告対策、AdSense CSVの出力バッファ対策、AdSense期間の開始日・終了日検証を強化。

= 1.0.10 =
* Google OAuth再接続時に旧アカウント・サイトの選択が残ることを防止。AdSenseの古いレポートキャッシュをGoogle接続ごとに分離。
* GoogleのAPIエラー文に含まれる資格情報らしき値のマスクを改善。その他の主要機能・UIは維持。

= 1.0.9 =
* 設定画面のタブ・広告とダウンロードのサブタブ選択をURLへ同期し、保存後に別タブへ移動してから再読み込みしても現在のタブを維持するよう修正。
* 未保存の登録候補を他画面から開いた場合も、タブ切り替え後の再読み込みで元タブへ戻らないよう調整。

= 1.0.8 =
* 概要のアフィリエイト識別子確認をAmazon・楽天市場・Yahoo!ショッピング別に表示。Amazon tag診断を維持し、楽天の既知リンク形式、Yahooへのバリューコマースsid/pid、および遷移先が判別できる「もしもアフィリエイト」のa_id/p_idを補助診断します。確認可能な識別子は元記事別一覧に表示します。
* URLの一部非表示や直接商品リンクを誤って「識別子なし」と判定しないよう改善。その他広告サービスは確認対象外として件数のみ案内。

= 1.0.7 =
* WordPressダッシュボードの概要リンク名を「Click Analytics解析の概要を開く」に変更。

= 1.0.6 =
* WordPressダッシュボードのリンク名を「Cocoonクリック解析の概要を開く」に修正し、表示名を統一。

= 1.0.5 =
* AdSense設定画面の冒頭に「テスト中」と「本番環境」の違いを追加し、これはOAuth公開ステータスでありAdSenseデータ自体は実データであることを明示。
* CCAが自己管理サイトで「テスト中」の利用を案内する理由（テストユーザー限定・開発／テスト段階ではOAuth検証なしで接続確認しやすい）を接続ガイドへ追加。
* 「本番環境」ではテスト中の7日制限がない一方、設定やスコープによってGoogleのブランド確認・OAuth検証等が必要になる場合があることを追記。

= 1.0.4 =
* Google OAuthの `invalid_grant` を認証失効として検出し、AdSense設定画面から再接続する専用案内を追加。
* 「設定 → AdSense」の先頭に、設定前の接続手順確認と「テスト中」では7日ごとの再接続が必要であることを明示。
* AdSense接続ガイドを8ステップに更新し、テストユーザー、7日失効、再接続方法を具体化。

= 1.0.3 =
* 「設定 → AdSense」に、Google Cloud側の準備から接続完了までを案内する「接続手順を見る」を追加。
* AdSense/OAuthの注意文を現行Google公式仕様に合わせて整理し、管理画面の警告・情報表示を再監査。

= 1.0.2 =
* Cocoonリンク種別の絞り込み後も、未分類リンク一覧の閲覧位置を維持するよう改善しました。
* JavaScriptが利用できない場合も未分類リンク一覧へ戻るアンカーを追加。

= 1.0.1 =
* Cocoonリンク種別の「外部リンク」をexternalのみで厳密集計し、その他のCocoon固有種別を「特殊リンク」として分離。
* 「その他」解析にCocoonリンク種別フィルターを追加。
* 未分類リンクにCocoonリンク種別と広告／ダウンロード候補の補助案内を表示。
* リンク種別名をCocoon管理画面に合わせて統一。

= 1.0.0 =
* CCA解析画面のデフォルト表示期間を設定可能にした（初期値: 今月）。
* 正式公開前の開発基準版。
* Cocoonクリック解析DBを読み取り専用で利用する広告・ダウンロード・商品分析を提供。
* 推移、ランキング、元記事別、掲載場所別、CSV、ダッシュボード、テストデータ、互換性診断を搭載。
* 任意のGoogle AdSense読み取り専用連携として、概要、前期間比較、推移、広告ユニット、形式・配置、デバイス分析を搭載。
* AdSenseのサイト切り替え、時間帯差の案内、30分オンデマンドキャッシュ、手動再取得、CSV、ダッシュボード指標選択・並び替えに対応。


== Notes ==

CCAはCocoonが記録したクリックデータを集計します。Amazonアソシエイト等の外部サービスのクリック数と必ずしも一致せず、Cocoonが計測しなかったクリックをCCAが補完することはありません。大量データの実DB負荷試験は未実施です。
