codymaster 4.1.0

package/skills/cm-ads-tracker/references/platforms-api.md

@@ -0,0 +1,238 @@
+# Platform Server-Side APIs Reference
+
+## Why Server-Side APIs Matter
+
+Browser-side pixels face increasing signal loss due to:
+- Ad blockers (15-40% of users block tracking scripts)
+- iOS 14+ and browser privacy restrictions (Safari ITP, Firefox ETP)
+- Cookie deprecation timeline
+
+Server-side APIs (CAPI, Events API) send events directly from your server to the platform — bypassing browser restrictions entirely. Combined with browser pixels and deduplication via event_id, this gives you the best possible signal quality.
+
+Typical uplift from adding server-side APIs:
+- Meta CAPI: +10-20% more matched conversions
+- TikTok Events API: +8-15% uplift
+- Google Enhanced Conversions: +15-25% conversion recovery
+
+---
+
+## 1. Meta Conversions API (CAPI)
+
+### Setup Methods (choose one)
+
+**Option A: Via Server-Side GTM (recommended for non-developers)**
+- Set up GTM Server-Side container (hosted on Google Cloud or Stape.io)
+- Route website events through server GTM → server GTM sends to Meta CAPI
+- No backend code changes needed
+
+**Option B: Direct API Integration (for developers)**
+- Endpoint: https://graph.facebook.com/v18.0/{pixel_id}/events
+- Authentication: System User Access Token from Meta Business Manager
+- Server sends HTTP POST for each conversion event
+
+### Required Fields for Every CAPI Event
+
+```
+{
+  "data": [{
+    "event_name": "Purchase",         // Standard Meta event name
+    "event_time": 1703123456,         // Unix timestamp (server time)
+    "event_id": "uuid-generated-at-conversion",  // CRITICAL for dedup
+    "action_source": "website",       // Required
+    "event_source_url": "https://yoursite.com/thank-you",
+    "user_data": {
+      "em": ["sha256_of_lowercase_email"],    // Hashed email
+      "ph": ["sha256_of_digitsonly_phone"],   // Hashed phone
+      "client_ip_address": "123.456.789.0",   // Server-detected IP
+      "client_user_agent": "Mozilla/5.0...",  // From request headers
+      "fbp": "_fb.1.1234567890.abcdefg",     // _fbp cookie value
+      "fbc": "fb.1.1234567890.AbCdEfGhIj"   // _fbc cookie value (from fbclid)
+    },
+    "custom_data": {
+      "value": 500000,
+      "currency": "VND",
+      "content_ids": ["PROD-123"],
+      "content_type": "product",
+      "contents": [{"id": "PROD-123", "quantity": 1, "item_price": 500000}],
+      "num_items": 1,
+      "order_id": "ORDER-20240101-001"
+    }
+  }],
+  "access_token": "EAAxxxxxxxxxxxx"
+}
+```
+
+### Deduplication Logic
+
+When your browser pixel AND CAPI both fire for the same conversion:
+- Both include identical `event_id` value
+- Meta's system receives both events within 48-hour window
+- Meta matches them by event_id and counts as ONE conversion
+- You see "Matched events" count in Events Manager
+
+The `event_id` MUST be:
+- Generated ONCE per conversion (not per request)
+- Identical in both browser dataLayer.push() and CAPI payload
+- Unique across all conversions (use UUID v4)
+
+### How to Get CAPI Access Token
+
+1. Go to Meta Business Manager → Events Manager
+2. Select your Pixel → Settings
+3. Scroll to "Conversions API"
+4. Click "Generate Access Token" (or use System User token from Business Settings)
+5. Copy token — treat it as a secret (never expose in browser-side code)
+
+### Testing CAPI Events
+
+Use Meta's Test Events tool in Events Manager → Test Events tab.
+Set test_event_code in payload during development:
+Add "test_event_code": "TEST12345" to the payload root (not inside data array).
+
+---
+
+## 2. TikTok Events API
+
+### Setup Methods
+
+**Option A: Via Server-Side GTM with TikTok template**
+- Use community TikTok Events API GTM server-side template
+- Route events through server GTM
+
+**Option B: Direct API Integration**
+- Endpoint: https://business-api.tiktok.com/open_api/v1.3/event/track/
+- Authentication: Access Token from TikTok Events Manager
+
+### Required Fields for Every Events API Event
+
+```
+{
+  "pixel_code": "CXXXXXXXXXX",
+  "event": "CompletePayment",           // TikTok standard event name
+  "event_id": "uuid-generated-at-conversion",  // For dedup with pixel
+  "timestamp": "2024-01-15T10:30:00+07:00",
+  "context": {
+    "page": {
+      "url": "https://yoursite.com/thank-you",
+      "referrer": "https://yoursite.com/checkout"
+    },
+    "user": {
+      "email": "sha256_of_lowercase_email",
+      "phone_number": "sha256_of_digits_only_phone"
+    },
+    "ip": "123.456.789.0",
+    "user_agent": "Mozilla/5.0..."
+  },
+  "properties": {
+    "value": 500000,
+    "currency": "VND",
+    "content_ids": ["PROD-123"],
+    "content_type": "product",
+    "contents": [
+      {
+        "content_id": "PROD-123",
+        "content_name": "Product Name",
+        "content_type": "product",
+        "quantity": 1,
+        "price": 500000
+      }
+    ]
+  }
+}
+```
+
+Authentication header: "Access-Token: [your access token]"
+Content-Type: application/json
+
+### Getting TikTok Events API Access Token
+
+1. TikTok Ads Manager → Assets → Events
+2. Select your Pixel → Set Up Web Events → Events API
+3. Generate Access Token
+4. Store securely server-side
+
+### TikTok Deduplication
+
+Works identically to Meta: same event_id sent from both pixel and Events API.
+TikTok matches within 48-hour window.
+
+---
+
+## 3. Google Enhanced Conversions
+
+### How It Works
+
+Unlike Meta CAPI and TikTok Events API (which are standalone APIs), Google Enhanced Conversions supplements your existing Google Ads conversion tag with hashed user data.
+
+The existing GTM Google Ads tag is enhanced with a user_data object containing:
+- email_address (raw — Google hashes it)
+- phone_number (raw — with country code prefix e.g. "+84912345678")
+- address.first_name, address.last_name, address.country, address.postal_code
+
+IMPORTANT: Google hashes the data itself (unlike Meta/TikTok where you pre-hash).
+Do NOT SHA256 hash for Enhanced Conversions — pass raw data.
+
+### Setup in GTM
+
+In your existing Google Ads Conversion Tracking tag:
+1. Scroll to "Enhanced conversions"
+2. Enable "Include user-provided data from your website"
+3. Under "User-provided data variable", create a new variable:
+   - Type: User-Provided Data
+   - Enter email variable: [DataLayer variable for email]
+   - Enter phone variable: [DataLayer variable for phone]
+
+The DataLayer push should include raw (unhashed) email and phone:
+email: "customer@email.com"
+phone: "+84912345678"
+
+Or if privacy is a concern: pre-hash with SHA256 and mark as "sha256_email_address" in the enhanced conversions config.
+
+### Google Tag API (Server-Side Enhanced Conversions)
+
+For server-side Enhanced Conversions via the Google Ads API:
+- Use the Google Ads API ConversionUploadService
+- Send click conversion with hashed user identifiers
+- Match window: same as your conversion window setting
+
+---
+
+## 4. Attribution Accuracy Benchmark
+
+After implementing pixel + server-side API for all platforms, expect:
+
+| Scenario | Pixel Only | Pixel + CAPI/Events API |
+|---|---|---|
+| iOS 14+ users | 30-50% signal loss | Full signal recovery |
+| Ad blocker users | 0% tracking | 80-90% recovery |
+| Overall conversion match rate | 60-70% | 85-95% |
+| ROAS accuracy | Understated by 20-40% | Near-accurate |
+
+### Validating Server-Side Setup
+
+**Meta:** Events Manager → Pixel → Overview → Check "Event match quality" score
+- Score 6-7: Good
+- Score 8+: Excellent
+- Below 5: Missing user_data fields (em, ph, fbp, fbc)
+
+**TikTok:** Ads Manager → Assets → Events → Pixel → Data Details
+- Check "Match rate" percentage
+- Target: 60%+ match rate
+
+**Google:** Google Ads → Conversions → View column "Enhanced conv." count
+- Compare with standard conversion count
+- Uplift of 15-25% is typical and expected
+
+---
+
+## 5. Priority Implementation Order
+
+If budget/time is limited, implement in this order:
+
+1. Browser pixels via GTM (Phase B) — covers 60-70% of users
+2. First-touch cookie + UTM tracking — attribution clarity
+3. Meta CAPI — highest ROI platform, biggest uplift from server-side
+4. Google Enhanced Conversions — easy to add, 15-25% uplift
+5. TikTok Events API — add once other platforms are stable
+
+Never implement CAPI without also keeping the browser pixel — you need both for deduplication to work. If you only have CAPI, you lose browser-generated signals like fbp cookie.

package/skills/cm-ads-tracker/templates/capi-payload.md

@@ -0,0 +1,79 @@
+# Facebook/Meta CAPI Server-Side Template
+
+## Required Payload Fields
+
+```json
+{
+  "data": [{
+    "event_name": "Purchase",
+    "event_time": 1700000000,
+    "event_id": "uuid-same-as-pixel-event-id",
+    "action_source": "website",
+    "event_source_url": "https://example.com/thank-you",
+    "user_data": {
+      "em": ["sha256_hashed_email"],
+      "ph": ["sha256_hashed_phone_digits_only"],
+      "client_ip_address": "1.2.3.4",
+      "client_user_agent": "Mozilla/5.0...",
+      "fbp": "_fbp cookie value",
+      "fbc": "fb.1.timestamp.fbclid_value"
+    },
+    "custom_data": {
+      "value": 299000,
+      "currency": "VND",
+      "order_id": "ORD-12345",
+      "content_ids": ["prod_001", "prod_002"],
+      "content_type": "product",
+      "num_items": 2
+    }
+  }]
+}
+```
+
+## API Endpoint
+
+```
+POST https://graph.facebook.com/v21.0/{PIXEL_ID}/events?access_token={CAPI_ACCESS_TOKEN}
+```
+
+## Deduplication
+
+Both browser Pixel and CAPI send the SAME `event_id`. Meta matches within 48h and counts once.
+
+## Enhanced Matching Priority (hash with SHA256)
+
+1. `em` — email (lowercase, trim whitespace)
+2. `ph` — phone (digits only, include country code)
+3. `fn` — first name (lowercase)
+4. `ln` — last name (lowercase)
+5. `fbp` — Facebook browser cookie
+6. `fbc` — Facebook click ID cookie
+
+## TikTok Events API Equivalent
+
+```
+POST https://business-api.tiktok.com/open_api/v1.3/event/track/
+Headers: Access-Token: {TIKTOK_ACCESS_TOKEN}
+```
+
+```json
+{
+  "pixel_code": "TIKTOK_PIXEL_ID",
+  "event": "CompletePayment",
+  "event_id": "same-uuid-as-pixel",
+  "timestamp": "2025-01-15T10:30:00+07:00",
+  "context": {
+    "user_agent": "Mozilla/5.0...",
+    "ip": "1.2.3.4"
+  },
+  "properties": {
+    "value": 299000,
+    "currency": "VND",
+    "content_id": "prod_001",
+    "content_type": "product",
+    "contents": [
+      {"content_id": "prod_001", "content_name": "Product A", "quantity": 1, "price": 299000}
+    ]
+  }
+}
+```

package/skills/cm-ads-tracker/templates/datalayer-push.js

@@ -0,0 +1,104 @@
+// DataLayer Push Templates — CM Ads Tracker v2
+// Copy and customize these for your project.
+// Developer writes ONE push per event. GTM does the rest.
+
+// ═══════════════════════════════════════════
+// PURCHASE (E-commerce, Courses, SaaS)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_purchase',
+  event_id: '[UUID generated server-side — same value sent to CAPI]',
+  transaction_id: '[order_id]',
+  value: 0, // numeric order total — NOT string
+  currency: 'VND', // ISO 4217 code
+  content_type: 'product',
+  content_ids: ['product_id_1', 'product_id_2'],
+  contents: [
+    { content_id: 'id', content_name: 'name', content_type: 'product', quantity: 1, price: 0 }
+  ],
+  num_items: 1,
+  email_hashed: '[SHA256(lowercase(email))]',
+  phone_hashed: '[SHA256(digits-only phone)]'
+});
+
+// ═══════════════════════════════════════════
+// LEAD / FORM SUBMIT  (Lead Gen, B2B, Education)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_lead',
+  event_id: '[UUID]',
+  lead_id: '[unique lead identifier]',
+  content_name: '[form_name or page_name]',
+  value: 0, // lead_value_if_known — optional
+  currency: 'VND',
+  email_hashed: '[SHA256(lowercase(email))]',
+  phone_hashed: '[SHA256(digits-only phone)]'
+});
+
+// ═══════════════════════════════════════════
+// VIEW CONTENT (Product/Service page)
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_view_content',
+  event_id: '[UUID]',
+  content_ids: ['product_id'],
+  content_type: 'product',
+  content_name: '[Product Name]',
+  value: 0,
+  currency: 'VND'
+});
+
+// ═══════════════════════════════════════════
+// ADD TO CART
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_add_to_cart',
+  event_id: '[UUID]',
+  content_ids: ['product_id'],
+  content_type: 'product',
+  content_name: '[Product Name]',
+  value: 0,
+  currency: 'VND',
+  quantity: 1
+});
+
+// ═══════════════════════════════════════════
+// INITIATE CHECKOUT
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_initiate_checkout',
+  event_id: '[UUID]',
+  value: 0,
+  currency: 'VND',
+  num_items: 1,
+  content_ids: ['product_id_1']
+});
+
+// ═══════════════════════════════════════════
+// REGISTRATION / SIGNUP
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_registration',
+  event_id: '[UUID]',
+  status: 'complete',
+  email_hashed: '[SHA256]',
+  phone_hashed: '[SHA256]'
+});
+
+// ═══════════════════════════════════════════
+// PHONE CALL CLICK
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_phone_call',
+  event_id: '[UUID]',
+  phone_number: '[phone number clicked]'
+});
+
+// ═══════════════════════════════════════════
+// SEARCH
+// ═══════════════════════════════════════════
+dataLayer.push({
+  event: 'cro_search',
+  event_id: '[UUID]',
+  search_string: '[user search query]'
+});

package/skills/cm-ads-tracker/templates/gtm-variables.js

@@ -0,0 +1,56 @@
+// GTM Variables — Full Configuration Reference
+// Create ALL of these in GTM > Variables > User-Defined Variables
+
+// ═══════ DataLayer Variables ═══════
+// Variable Name           | Type              | DataLayer Variable Name
+// DL - event_id           | Data Layer Variable | event_id
+// DL - order_id           | Data Layer Variable | transaction_id
+// DL - order_value        | Data Layer Variable | value
+// DL - currency           | Data Layer Variable | currency
+// DL - content_ids        | Data Layer Variable | content_ids
+// DL - content_type       | Data Layer Variable | content_type
+// DL - content_name       | Data Layer Variable | content_name
+// DL - email_hashed       | Data Layer Variable | email_hashed
+// DL - phone_hashed       | Data Layer Variable | phone_hashed
+
+// ═══════ First-Touch Cookie Variables ═══════
+// Variable Name           | Type              | Cookie / Key
+// FTC - source            | 1st-Party Cookie  | Cookie: _ftc, key: src
+// FTC - medium            | 1st-Party Cookie  | Cookie: _ftc, key: med
+// FTC - campaign          | 1st-Party Cookie  | Cookie: _ftc, key: cmp
+
+// ═══════ URL Parameters ═══════
+// Variable Name           | Type              | Query Parameter
+// URL - utm_source        | URL               | utm_source
+// URL - utm_medium        | URL               | utm_medium
+// URL - utm_campaign      | URL               | utm_campaign
+// URL - fbclid            | URL               | fbclid
+// URL - ttclid            | URL               | ttclid
+// URL - gclid             | URL               | gclid
+
+// ═══════ First-Touch Cookie Capture (Custom HTML Tag) ═══════
+// Trigger: All Pages
+// Fire once: Only if _ftc cookie does NOT exist
+<script>
+(function(){
+  if (document.cookie.indexOf('_ftc=') !== -1) return;
+  var params = new URLSearchParams(window.location.search);
+  var ftc = {
+    src: params.get('utm_source') || '',
+    med: params.get('utm_medium') || '',
+    cmp: params.get('utm_campaign') || '',
+    cnt: params.get('utm_content') || '',
+    trm: params.get('utm_term') || '',
+    fbclid: params.get('fbclid') || '',
+    ttclid: params.get('ttclid') || '',
+    gclid: params.get('gclid') || '',
+    ref: document.referrer ? new URL(document.referrer).hostname : '',
+    ts: new Date().toISOString()
+  };
+  var expiry = new Date();
+  expiry.setDate(expiry.getDate() + 90);
+  document.cookie = '_ftc=' + encodeURIComponent(JSON.stringify(ftc))
+    + ';expires=' + expiry.toUTCString()
+    + ';path=/;SameSite=Lax';
+})();
+</script>