Affiliate Link Enrichment - Implementation Plan

This document outlines the phased implementation plan for the Affiliate Link Enrichment feature, based on the AFFILIATE_PROGRAM_ENRICHMENT.md brief and the current state of the WooNooW project.

1. Current State of the Project

Frontend (customer-spa/src/pages/Account/AffiliateDashboard.tsx): The affiliate dashboard currently only provides a single, generic storefront link: site.com/shop?ref=YOUR_CODE. This creates the "generic storefront" problem described in the brief.
Backend (includes/Modules/Affiliate/AffiliateTracker.php): The backend is highly prepared. The tracking logic natively intercepts any page visit that has the ?ref= parameter. Furthermore, it already captures UTM parameters (utm_source, utm_medium, utm_campaign, utm_content, utm_term, referrer_url) and stores them in the woonoow_ref_utm cookie, which are eventually saved to the woonoow_referrals table when an order is completed.

Phase 1: Immediate Opportunities (Low Effort, High Impact)

Because the backend already tracks referrals across the entire site and captures campaign parameters, Phase 1 can be implemented strictly via Frontend (SPA) changes, requiring no backend database migrations.

1.1 Implement a "Link Generator" UI (Customer SPA)

Add a new "Link Builder" section in the Affiliate Dashboard (AffiliateDashboard.tsx) where affiliates can:

Single Product Link: Select a specific product (via a dropdown/search) to generate a link like /product/slug?ref=CODE.
Category Link: Select a category to generate a link like /shop?category=slug&ref=CODE.
Campaign Tracking: Add custom Campaign tags (utm_campaign, utm_source, etc.) to the generated links.

1.2 Campaign Analytics UI

Since the woonoow_referrals table already stores UTM data:

Affiliate Dashboard: Update the UI to show earnings/clicks grouped by utm_campaign or utm_source.
Admin SPA: Add reports in the admin area to view referral performance by campaign, fulfilling the trackability requirement.

Phase 2: Medium-Term Opportunities (Curated Collections)

To fulfill the "Curated Collection Link" requirement (where an affiliate groups a themed set of relevant products), we need to build a new feature:

2.1 Backend Development

Create a new custom database table or Custom Post Type (e.g., woonoow_affiliate_collections) that maps an Affiliate ID to a list of Product IDs, along with a title and description.
Create REST API endpoints for affiliates to CRUD their collections.

2.2 Frontend Development

Affiliate Dashboard: Add a "My Collections" manager where affiliates can pick products, set a title, and generate a specific collection link.
Storefront: Add a new dynamic route to the customer-spa (e.g., /shop/collection/:collection_id?ref=CODE) that fetches and displays only the specific products in that collection.

Phase 3: Advanced Opportunities (Smart Rotation)

To support "Controlled Smart Rotation" (rotating a small pool of products):

3.1 Smart Router API Endpoint

Create a lightweight REST API endpoint (e.g., /wp-json/woonoow/v1/go/:rotation_id).
When a visitor clicks this link, the backend briefly evaluates the rotation rules, applies the ?ref= and UTM cookies server-side, and does a 302 redirect to the chosen product page.

3.2 UI/UX

Add configuration settings in the Affiliate Dashboard to set up these rule-based or random rotation links.

3.5 KiB Raw Blame History