claude-plugin-wordpress-manager 2.2.1 → 2.3.0

package/skills/wp-content-attribution/references/reporting-dashboards.md

@@ -0,0 +1,199 @@
+# Reporting Dashboards
+
+Use this file when setting up content attribution reporting — GA4 integration, analytics plugin configuration, dashboard KPIs, and automated reporting workflows.
+
+## WooCommerce + WordPress Analytics Correlation
+
+The core reporting methodology links three data sources:
+
+```
+WordPress Content Data          WooCommerce Order Data         Analytics Data
+(list_content, post dates)  +   (wc_list_orders, order meta) + (GA4, MonsterInsights)
+         │                              │                              │
+         └──────────── Correlate via UTM campaign = post slug ─────────┘
+```
+
+### Manual Correlation Workflow
+
+1. **Export orders** with UTM meta for the reporting period
+2. **Export content** published in the same period
+3. **Match** `_last_utm_campaign` values to post slugs
+4. **Aggregate** revenue per post, per category, per content type
+5. **Rank** by revenue, ROI, or conversion rate
+
+## Google Analytics 4 Integration
+
+### UTM → GA4 → WooCommerce Reconciliation
+
+GA4 automatically captures UTM parameters as session-level dimensions:
+
+| GA4 Dimension | UTM Parameter | Use |
+|---------------|--------------|-----|
+| Session source | `utm_source` | Where traffic came from |
+| Session medium | `utm_medium` | Channel type |
+| Session campaign | `utm_campaign` | Specific campaign/post |
+| Session manual ad content | `utm_content` | Link variant |
+| Session manual term | `utm_term` | Search keyword |
+
+**GA4 Exploration report for content attribution:**
+1. Go to Explore → Free-form
+2. Dimensions: Session campaign, Landing page
+3. Metrics: Sessions, Conversions, Revenue
+4. Filter: Session source = "blog"
+5. Sort by Revenue descending
+
+### Enhanced E-commerce Events
+
+GA4 tracks the full purchase funnel when configured:
+- `view_item` — product page view
+- `add_to_cart` — item added to cart
+- `begin_checkout` — checkout started
+- `purchase` — order completed with revenue
+
+## MonsterInsights / WooCommerce Google Analytics Plugin
+
+### MonsterInsights Setup
+
+MonsterInsights bridges WordPress content data with GA4:
+
+1. **Install:** MonsterInsights plugin (free tier sufficient for basic attribution)
+2. **Connect:** Link to GA4 property via the setup wizard
+3. **Enable:** Enhanced E-commerce tracking in MonsterInsights settings
+4. **Dashboard:** View top posts by revenue directly in WordPress admin
+
+**Key MonsterInsights reports:**
+- Top Landing Pages (awareness stage)
+- Top Outbound Links (consideration stage)
+- E-commerce Revenue by Source (attribution)
+- Top Products (conversion stage)
+
+### WooCommerce Google Analytics Plugin (Official)
+
+Alternative for sites already using GA4 without MonsterInsights:
+
+1. Install: "WooCommerce Google Analytics" (official extension)
+2. Enter GA4 Measurement ID
+3. Enable: Enhanced E-commerce events
+4. Events auto-tracked: `view_item`, `add_to_cart`, `purchase`
+
+## Custom Dashboard Options
+
+### WP Admin Dashboard Widget
+
+Create a simple attribution summary widget:
+
+```php
+add_action('wp_dashboard_setup', function () {
+    wp_add_dashboard_widget(
+        'content_attribution_widget',
+        'Content Attribution — Top 5 Posts by Revenue',
+        function () {
+            // Query recent completed orders with UTM data
+            $orders = wc_get_orders([
+                'status' => 'completed',
+                'limit'  => 100,
+                'date_created' => '>' . date('Y-m-d', strtotime('-30 days')),
+            ]);
+            $revenue_by_campaign = [];
+            foreach ($orders as $order) {
+                $campaign = $order->get_meta('_last_utm_campaign');
+                if ($campaign) {
+                    $revenue_by_campaign[$campaign] = ($revenue_by_campaign[$campaign] ?? 0) + $order->get_total();
+                }
+            }
+            arsort($revenue_by_campaign);
+            echo '<table><tr><th>Content</th><th>Revenue</th></tr>';
+            $i = 0;
+            foreach ($revenue_by_campaign as $campaign => $revenue) {
+                if ($i++ >= 5) break;
+                echo '<tr><td>' . esc_html($campaign) . '</td><td>' . wc_price($revenue) . '</td></tr>';
+            }
+            echo '</table>';
+        }
+    );
+});
+```
+
+### External BI Tools
+
+For larger operations, export data to external dashboards:
+
+| Tool | Integration Method | Cost |
+|------|-------------------|------|
+| Google Looker Studio | GA4 connector + WC data export | Free |
+| Tableau | WooCommerce REST API → CSV/database | Paid |
+| Metabase | Direct MySQL/PostgreSQL connection | Free (self-hosted) |
+| Power BI | REST API connector or CSV import | Paid |
+
+## Automated Reporting
+
+### Monthly Content Attribution Report Template
+
+```
+## Content Attribution Report — {Month} {Year}
+
+### Summary
+- Total content-attributed revenue: ${total}
+- Orders with UTM attribution: {count} ({percentage}% of total orders)
+- Top attribution model used: {model}
+
+### Top 10 Converting Content Pieces
+| Rank | Post | Revenue | Orders | Avg Order Value |
+|------|------|---------|--------|-----------------|
+| 1 | {title} | ${rev} | {n} | ${aov} |
+| ... | ... | ... | ... | ... |
+
+### Revenue by Content Category
+| Category | Revenue | Posts | Revenue/Post |
+|----------|---------|-------|-------------|
+| {cat} | ${rev} | {n} | ${rpp} |
+
+### Revenue by Source
+| Source | Revenue | Orders | CAC |
+|--------|---------|--------|-----|
+| blog | ${rev} | {n} | ${cac} |
+| newsletter | ${rev} | {n} | ${cac} |
+
+### Recommendations
+- Invest more in: {top category}
+- Reduce investment in: {lowest ROI category}
+- Content gap: {opportunity identified}
+```
+
+### Automation via WP-Cron
+
+Schedule monthly report generation:
+
+```php
+// Register cron event
+if (!wp_next_scheduled('generate_attribution_report')) {
+    wp_schedule_event(time(), 'monthly', 'generate_attribution_report');
+}
+
+add_action('generate_attribution_report', function () {
+    // Generate report data (query orders, correlate with content)
+    // Save as a private post or send via email
+    // Uses same logic as dashboard widget but for full month
+});
+```
+
+## Key KPIs Dashboard
+
+The essential metrics for an at-a-glance attribution dashboard:
+
+| KPI | Description | Update Frequency |
+|-----|-------------|-----------------|
+| **Content-Attributed Revenue** | Total revenue from orders with UTM data | Weekly |
+| **Top Converting Post** | Post with highest attributed revenue this month | Monthly |
+| **Attribution Rate** | % of orders with UTM attribution data | Weekly |
+| **Content ROI** | (Revenue - Cost) / Cost × 100% | Monthly |
+| **CAC by Source** | Customer acquisition cost per channel | Monthly |
+| **Revenue/Post Trend** | Month-over-month revenue per post | Monthly |
+
+## Decision Checklist
+
+1. Is GA4 connected and tracking enhanced e-commerce events? → Verify in GA4 Realtime report
+2. Is MonsterInsights or equivalent analytics plugin active? → Check WordPress admin dashboard
+3. Are WooCommerce orders showing UTM meta data? → Spot-check 5 recent orders
+4. Is a monthly report process defined (manual or automated)? → Set up template + schedule
+5. Are KPIs reviewed and actioned on regularly? → Schedule monthly review meeting

package/skills/wp-content-attribution/references/roi-calculation.md

@@ -0,0 +1,202 @@
+# ROI Calculation
+
+Use this file when calculating content return on investment — revenue per post, content ROI formula, customer acquisition cost, and lifetime value by content source.
+
+## Revenue Per Post
+
+The most straightforward content attribution metric.
+
+**Formula:**
+```
+Revenue Per Post = Total attributed revenue / Number of posts
+```
+
+**Per-post attribution (last-touch):**
+```
+Revenue(Post X) = SUM(order_total) WHERE _last_utm_campaign = "post-x-slug"
+```
+
+**Per-post attribution (first-touch):**
+```
+Revenue(Post X) = SUM(order_total) WHERE _first_utm_campaign = "post-x-slug"
+```
+
+### Calculating with WooCommerce MCP Tools
+
+```bash
+# Step 1: Get completed orders for the period
+wc_list_orders(status="completed", after="2025-01-01", before="2025-01-31", per_page=100)
+
+# Step 2: For each order, read utm meta
+# Group orders by _last_utm_campaign value
+# Sum order_total per campaign (campaign = post slug)
+
+# Step 3: Get content list for the same period
+list_content(type="post", status="publish", after="2025-01-01", before="2025-01-31")
+
+# Step 4: Match campaign slugs to post titles
+# Result: { post_title: "Cactus Water Benefits", slug: "cactus-water-benefits", revenue: 2500, orders: 15 }
+```
+
+### Revenue Per Post Benchmarks
+
+| Content Type | Typical Revenue/Post | Notes |
+|-------------|---------------------|-------|
+| Product review | $500–$5,000 | High intent, bottom-of-funnel |
+| How-to guide | $100–$1,000 | Indirect conversion, builds trust |
+| Comparison post | $1,000–$10,000 | Very high intent, decision-stage |
+| Category guide | $200–$2,000 | Mid-funnel, product discovery |
+| News/update | $50–$500 | Low intent, brand awareness |
+
+## Content ROI Formula
+
+**Formula:**
+```
+Content ROI = (Revenue - Content Cost) / Content Cost × 100%
+```
+
+**Example:**
+```
+Blog post cost:   $200 (writer) + $50 (images) + $30 (editing) = $280
+Revenue attributed: $1,400 (last-touch, 3 months)
+Content ROI: ($1,400 - $280) / $280 × 100% = 400% ROI
+```
+
+### Content Cost Components
+
+| Component | Typical Cost | How to Track |
+|-----------|-------------|--------------|
+| Writing | $0.10–$0.50/word | Per-post invoice or hourly rate |
+| Editing | $25–$100/post | Editor time tracking |
+| Images/media | $10–$100/post | Stock photo licenses, design time |
+| SEO optimization | $25–$75/post | SEO tool costs + specialist time |
+| Publishing/formatting | $15–$30/post | CMS time |
+| **Total typical cost** | **$100–$500/post** | Sum all components |
+
+### ROI by Content Category
+
+Track ROI by category to identify the most profitable content pillars:
+
+```
+Category        Posts  Total Cost  Total Revenue  ROI
+──────────────────────────────────────────────────────
+Product reviews   10    $3,000      $25,000       733%
+How-to guides     20    $4,000      $8,000        100%
+Company news      15    $1,500      $750          -50%
+Case studies       5    $2,500      $12,000       380%
+```
+
+**Action:** Double down on product reviews and case studies; reduce company news investment.
+
+## Customer Acquisition Cost (CAC) by Content Type
+
+**Formula:**
+```
+CAC = Total content investment / New customers acquired from content
+```
+
+**By content type:**
+```
+CAC(blog) = Blog content costs / New customers with _first_utm_source = "blog"
+CAC(email) = Email costs / New customers with _first_utm_source = "newsletter"
+CAC(social) = Social costs / New customers with _first_utm_source = "facebook|instagram"
+```
+
+### CAC Benchmarks (E-commerce)
+
+| Channel | Typical CAC | Notes |
+|---------|------------|-------|
+| Organic blog content | $20–$80 | Lower CAC, longer to build |
+| Email newsletter | $10–$40 | Lowest CAC, requires list |
+| Paid search (Google) | $30–$100 | Immediate but expensive |
+| Social media (organic) | $25–$75 | Variable, platform-dependent |
+| Social media (paid) | $15–$60 | Scalable with budget |
+
+## Lifetime Value (LTV) by Acquisition Source
+
+**Formula:**
+```
+LTV = Average Order Value × Purchase Frequency × Customer Lifespan
+```
+
+**By source:**
+```
+LTV(blog) = AOV(blog customers) × Frequency(blog customers) × Lifespan(blog customers)
+```
+
+### Calculating with WooCommerce Data
+
+```bash
+# Get top sellers to understand AOV patterns
+wc_get_top_sellers(period="year")
+
+# Get sales report for overall metrics
+wc_get_sales_report(period="year")
+# Returns: total_sales, total_orders → AOV = total_sales / total_orders
+
+# For source-specific LTV:
+# 1. Filter orders by _first_utm_source
+# 2. Group by customer_id
+# 3. Calculate per-customer: total_spent, order_count, first_order_date, last_order_date
+# 4. Average across customers from that source
+```
+
+### LTV:CAC Ratio
+
+```
+Healthy ratio: LTV:CAC > 3:1
+
+Example:
+  Blog customers: LTV = $240, CAC = $50 → Ratio = 4.8:1 ✓ Excellent
+  Paid ad customers: LTV = $180, CAC = $80 → Ratio = 2.25:1 ⚠ Below target
+```
+
+**Action:** If LTV:CAC < 3:1, either reduce acquisition cost or increase customer retention/upsell.
+
+## Content Efficiency Metrics
+
+### Revenue Per Word
+
+```
+Revenue Per Word = Total attributed revenue / Total words published
+```
+
+Useful for comparing content formats: long-form guides vs short product reviews.
+
+### Revenue Per Topic
+
+```
+Revenue Per Topic = SUM(revenue of posts in topic cluster) / Number of posts in cluster
+```
+
+Identifies which topic clusters are most commercially valuable.
+
+### Time to ROI
+
+```
+Time to ROI = Days from publish date to break-even (revenue ≥ content cost)
+```
+
+Short time to ROI = content with immediate commercial intent (product reviews).
+Long time to ROI = evergreen SEO content (compounds over months).
+
+## Using WC Reports for Date Correlation
+
+```bash
+# Monthly sales report
+wc_get_sales_report(date_min="2025-03-01", date_max="2025-03-31")
+
+# Top-selling products in the period
+wc_get_top_sellers(date_min="2025-03-01", date_max="2025-03-31")
+
+# Cross-reference with content published before the period:
+list_content(type="post", status="publish", before="2025-03-31", orderby="date", order="desc", per_page=20)
+```
+
+## Decision Checklist
+
+1. Is content cost tracked per post? → Set up cost tracking (spreadsheet or custom field)
+2. Is revenue attributed to individual posts via UTM? → Verify mu-plugin capturing data
+3. Is CAC calculated by acquisition source? → Group orders by first-touch source
+4. Is LTV:CAC ratio above 3:1? → If not, optimize acquisition or retention
+5. Are content investments being shifted to highest-ROI categories? → Review quarterly

package/skills/wp-content-attribution/references/utm-tracking-setup.md

@@ -0,0 +1,161 @@
+# UTM Tracking Setup
+
+Use this file when setting up UTM parameter capture for WooCommerce orders — parameter architecture, mu-plugin installation, naming conventions, and verification.
+
+## UTM Parameter Architecture
+
+| Parameter | Purpose | Example |
+|-----------|---------|---------|
+| `utm_source` | Where traffic originates | `blog`, `newsletter`, `google`, `facebook` |
+| `utm_medium` | Marketing channel type | `organic`, `email`, `cpc`, `social`, `referral` |
+| `utm_campaign` | Specific campaign name | `spring-sale-2025`, `product-launch-x` |
+| `utm_content` | Differentiates ad/link variants | `cta-button`, `sidebar-banner`, `post-footer` |
+| `utm_term` | Paid search keywords | `cactus-water-buy`, `zero-calorie-drink` |
+
+## mu-plugin Pattern: Capture UTM on Checkout
+
+Create a mu-plugin to automatically capture UTM parameters from the visitor session and store them as WooCommerce order meta:
+
+```php
+<?php
+/**
+ * Plugin Name: UTM Order Attribution
+ * Description: Captures UTM parameters from visitor session and stores as order meta.
+ * Version: 1.0.0
+ */
+
+// Store UTM params in session cookie on first visit
+add_action('init', function () {
+    if (!is_admin() && !wp_doing_cron()) {
+        $utm_params = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
+        foreach ($utm_params as $param) {
+            if (isset($_GET[$param]) && !empty($_GET[$param])) {
+                // Store in cookie for 30 days (first-touch attribution)
+                $cookie_name = '_wc_' . $param;
+                if (!isset($_COOKIE[$cookie_name])) {
+                    setcookie($cookie_name, sanitize_text_field($_GET[$param]), time() + (30 * DAY_IN_SECONDS), '/');
+                }
+                // Always update last-touch cookie
+                setcookie('_wc_last_' . $param, sanitize_text_field($_GET[$param]), time() + (30 * DAY_IN_SECONDS), '/');
+            }
+        }
+    }
+});
+
+// Save UTM data to order meta on checkout
+add_action('woocommerce_checkout_order_processed', function ($order_id) {
+    $order = wc_get_order($order_id);
+    if (!$order) return;
+
+    $utm_params = ['utm_source', 'utm_medium', 'utm_campaign', 'utm_content', 'utm_term'];
+    foreach ($utm_params as $param) {
+        // Save first-touch
+        $first_cookie = '_wc_' . $param;
+        if (isset($_COOKIE[$first_cookie]) && !empty($_COOKIE[$first_cookie])) {
+            $order->update_meta_data('_first_' . $param, sanitize_text_field($_COOKIE[$first_cookie]));
+        }
+        // Save last-touch
+        $last_cookie = '_wc_last_' . $param;
+        if (isset($_COOKIE[$last_cookie]) && !empty($_COOKIE[$last_cookie])) {
+            $order->update_meta_data('_last_' . $param, sanitize_text_field($_COOKIE[$last_cookie]));
+        }
+    }
+
+    // Save landing page URL (first page visited)
+    if (isset($_COOKIE['_wc_landing_page'])) {
+        $order->update_meta_data('_landing_page', sanitize_url($_COOKIE['_wc_landing_page']));
+    }
+
+    $order->save();
+});
+
+// Track landing page
+add_action('init', function () {
+    if (!is_admin() && !wp_doing_cron() && !isset($_COOKIE['_wc_landing_page'])) {
+        $landing = esc_url_raw((isset($_SERVER['HTTPS']) ? 'https' : 'http') . '://' . $_SERVER['HTTP_HOST'] . $_SERVER['REQUEST_URI']);
+        setcookie('_wc_landing_page', $landing, time() + (30 * DAY_IN_SECONDS), '/');
+    }
+});
+```
+
+**Installation:**
+1. Save as `wp-content/mu-plugins/utm-order-attribution.php`
+2. mu-plugins load automatically — no activation needed
+3. Verify by placing a test order with UTM params in the URL
+
+## UTM Naming Conventions
+
+Consistent naming is critical for accurate attribution. Adopt these rules:
+
+| Rule | Good | Bad |
+|------|------|-----|
+| Lowercase always | `utm_source=blog` | `utm_source=Blog` |
+| Hyphens for spaces | `spring-sale-2025` | `spring_sale_2025` or `spring sale` |
+| No special chars | `product-launch` | `product_launch!` |
+| Consistent source names | `newsletter` (always) | `email`, `newsletter`, `mail` (mixed) |
+| Date in campaigns | `black-friday-2025` | `black-friday` (ambiguous year) |
+
+**Recommended source taxonomy:**
+
+| Source | Medium | When to Use |
+|--------|--------|-------------|
+| `blog` | `organic` | Internal blog post links to products |
+| `blog` | `cta` | Blog post CTA buttons to products |
+| `newsletter` | `email` | Email newsletter links |
+| `google` | `cpc` | Google Ads campaigns |
+| `facebook` | `social` | Facebook organic or paid posts |
+| `instagram` | `social` | Instagram bio/stories links |
+| `partner-name` | `referral` | Partner/affiliate links |
+
+## Internal Link UTM Tagging
+
+Tag all blog-to-product links with UTMs:
+
+```html
+<!-- Blog post CTA linking to product -->
+<a href="/product/cactus-water/?utm_source=blog&utm_medium=cta&utm_campaign=cactus-water-benefits&utm_content=post-footer-button">
+  Buy Cactus Water
+</a>
+
+<!-- Sidebar widget linking to product -->
+<a href="/product/cactus-water/?utm_source=blog&utm_medium=sidebar&utm_campaign=always-on&utm_content=product-widget">
+  Try Cactus Water
+</a>
+```
+
+**Automated tagging approach:** Use a WordPress filter to append UTMs to all internal product links in post content:
+
+```php
+add_filter('the_content', function ($content) {
+    if (!is_singular('post')) return $content;
+    $post_slug = get_post_field('post_name', get_the_ID());
+    // Append UTM to internal /product/ links that don't already have UTM
+    $content = preg_replace_callback(
+        '#href="(/product/[^"]*?)(?<!\?[^"]*utm_source[^"]*)"#',
+        function ($matches) use ($post_slug) {
+            $sep = strpos($matches[1], '?') !== false ? '&' : '?';
+            return 'href="' . $matches[1] . $sep . 'utm_source=blog&utm_medium=organic&utm_campaign=' . $post_slug . '"';
+        },
+        $content
+    );
+    return $content;
+});
+```
+
+## Verification
+
+After installing the mu-plugin:
+
+1. **Test visit:** Navigate to `yoursite.com/product/example/?utm_source=test&utm_medium=test&utm_campaign=test`
+2. **Place test order** through WooCommerce checkout
+3. **Check order meta:** Use `wc_list_orders` MCP tool or WooCommerce admin → Orders → order details
+4. **Verify fields:** `_first_utm_source`, `_last_utm_source`, `_first_utm_campaign`, etc. should be populated
+5. **Check cookies:** Browser dev tools → Application → Cookies → look for `_wc_utm_*` cookies
+
+## Decision Checklist
+
+1. Is the mu-plugin installed in `wp-content/mu-plugins/`? → Verify file exists
+2. Are UTM naming conventions documented for the team? → Share taxonomy table
+3. Are internal blog→product links tagged with UTMs? → Audit sample posts
+4. Has a test order been placed with UTM params to verify capture? → Must pass before going live
+5. Is cookie duration appropriate (30 days default)? → Adjust for sales cycle length