Initial commit with translated description

2026-03-29 13:13:54 +08:00
commit 8ad6a822e8
14 changed files with 3037 additions and 0 deletions
--- a/references/revenuecat-integration.md
+++ b/references/revenuecat-integration.md
@@ -0,0 +1,123 @@
+# RevenueCat Integration
+
+## Setup
+
+Add RevenueCat config to `config.json`:
+
+```json
+{
+  "revenuecat": {
+    "v1SecretKey": "sk_...",
+    "projectId": "your-project-id"
+  }
+}
+```
+
+Get the **V1 Secret API Key** from RevenueCat Dashboard → Project Settings → API Keys. Use the **secret** key (sk_), NOT the public key.
+
+## API Endpoints
+
+### Get Overview Metrics
+RevenueCat doesn't expose dashboard overview via API. Use the V1 subscriber endpoint to track individual conversions, or scrape the dashboard via browser automation.
+
+**Alternative: Webhooks.** Set up RevenueCat webhooks to log events (trial_started, initial_purchase, renewal, cancellation) to a local JSON file that the skill can read.
+
+### Get Subscriber Info (V1)
+```
+GET https://api.revenuecat.com/v1/subscribers/{app_user_id}
+Authorization: Bearer {v1SecretKey}
+```
+
+Returns: active subscriptions, entitlements, purchase history, management URL.
+
+### List Subscribers (V2 — if available)
+```
+GET https://api.revenuecat.com/v2/projects/{projectId}/customers
+Authorization: Bearer {v2SecretKey}
+```
+
+## Daily Report Script
+
+`scripts/daily-report.js` runs daily to:
+
+1. **Pull TikTok analytics** from Postiz (last 3 days of posts)
+2. **Pull conversion data** from RevenueCat webhook logs OR manual input
+3. **Cross-reference** post timing with conversion spikes
+4. **Generate report** identifying which hooks drove actual revenue
+
+### Cross-Reference Logic
+
+```
+For each day in last 3 days:
+  1. Get all TikTok posts and their view counts
+  2. Get all new trials + paid conversions from RevenueCat
+  3. Correlate: conversion spikes within 24h of high-view posts
+  4. Score each hook: (conversions in 24h window) / (views / 1000) = conversion rate per 1K views
+  5. Rank hooks by conversion rate, not just views
+```
+
+### Why 3 Days?
+- TikTok posts peak at 24-48h then tail off
+- Conversion attribution window is ~24-72h
+- Shorter = miss delayed conversions, longer = too noisy
+
+## Webhook Setup (Recommended)
+
+In RevenueCat Dashboard → Project Settings → Webhooks:
+
+1. Set webhook URL to your server OR log to file
+2. Events to track:
+   - `INITIAL_PURCHASE` — new paid subscriber
+   - `TRIAL_STARTED` — new trial
+   - `TRIAL_CONVERTED` — trial → paid
+   - `RENEWAL` — existing subscriber renewed
+   - `CANCELLATION` — subscriber cancelled
+   - `EXPIRATION` — subscription expired
+
+Store events in `tiktok-marketing/rc-events.json`:
+```json
+[
+  {
+    "event": "INITIAL_PURCHASE",
+    "timestamp": "2026-02-15T14:00:00Z",
+    "product": "fullAccessMonthly",
+    "revenue": 4.99,
+    "currency": "USD"
+  }
+]
+```
+
+If no webhook available, the user can manually update this file or the agent can prompt for daily numbers:
+- "How many new trials today?"
+- "How many paid conversions?"
+- "Current MRR?"
+
+## Report Output
+
+The daily report generates `tiktok-marketing/reports/YYYY-MM-DD.md`:
+
+```markdown
+# Daily Marketing Report — Feb 15, 2026
+
+## TikTok Performance (Last 3 Days)
+| Date | Hook | Views | Likes | Saves |
+|------|------|-------|-------|-------|
+| Feb 15 | boyfriend + catalogue | 12,400 | 340 | 67 |
+| Feb 14 | sister prison cell | 8,200 | 215 | 43 |
+| Feb 13 | nan hook | 3,100 | 89 | 12 |
+
+## Conversions (Last 3 Days)
+- New trials: 14
+- Trial → Paid: 6
+- New direct purchases: 2
+- Revenue: $47.92
+
+## Attribution
+- Feb 15 spike (8 trials) correlates with "boyfriend + catalogue" post (12.4K views)
+- Estimated conversion rate: 0.65 per 1K views (GOOD)
+
+## Recommendations
+- DOUBLE DOWN on relationship conflict hooks (boyfriend/sister/nan)
+- Drop listicle format (Feb 13 — low views, 0 correlating conversions)
+- Test: "My [person] didn't believe AI could redesign our [room]"
+```