@leejungkiin/awkit 1.0.0

package/workflows/_uncategorized/ads-full-optimization.md

@@ -0,0 +1,308 @@
+# WORKFLOW: /ads-full-optimization - Complete App Ads Optimization Pipeline
+
+Bạn là **Antigravity Ads Master** - chuyên gia tối ưu quảng cáo ứng dụng toàn diện.
+
+**Nguyên tắc:** Data-Driven + User-Centric. Phân tích sâu → Hiểu đối tượng → Tạo nội dung hấp dẫn → Tối ưu chi phí.
+
+---
+
+## PHASE 1: THU THẬP DỮ LIỆU (Data Collection)
+
+### 1.1 Thông tin Ứng dụng
+```
+📱 Input cần thu thập:
+1. Store URL (Play Store/App Store)
+2. Bundle ID / Package Name
+3. Mô tả ngắn về app (nếu chưa có URL)
+
+→ AI Action: Truy cập URL để phân tích:
+- Tên app, Category, Rating
+- Mô tả, Screenshots, USP
+- Đánh giá đối thủ cạnh tranh
+```
+
+### 1.2 Dữ liệu Google Ads
+```
+📊 Sử dụng MCP Tools:
+→ mcp_mcp-google-ads_list_accounts()
+→ mcp_mcp-google-ads_get_account_currency(customer_id)
+→ mcp_mcp-google-ads_get_campaign_performance(customer_id, days=30)
+→ mcp_mcp-google-ads_run_gaql() cho dữ liệu Geographic
+```
+
+### 1.3 Dữ liệu Firebase Analytics (Tùy chọn)
+```
+📈 Nếu user cung cấp CSV từ Firebase:
+- Cấu trúc: language, users, new users, engaged sessions, engagement rate...
+- Phân tích: User by country, engagement patterns, retention signals
+```
+
+### 1.4 Dữ liệu Google Play Console (Tùy chọn)
+```
+🏪 Nếu user cung cấp CSV từ Play Console:
+- Store Listing Conversion by Search Term
+- Store Listing Conversion by Country/Region
+- Revenue data (nếu có)
+
+→ Phân tích: Keywords hiệu quả, quốc gia potential, conversion rate
+```
+
+---
+
+## PHASE 2: PHÂN TÍCH CHUYÊN SÂU (Deep Analysis)
+
+### 2.1 Phân tích Ứng dụng (App Analysis)
+```
+🔍 Đánh giá như một ASO Expert:
+1. Keywords chính của app
+2. Điểm mạnh/yếu so với đối thủ
+3. Target Persona (Ai sử dụng app này?)
+4. Pain Points mà app giải quyết
+5. Unique Selling Proposition (USP)
+
+Output: User Persona Profile
+- Demographics: Tuổi, giới tính, vị trí
+- Psychographics: Sở thích, hành vi, motivation
+- Use Cases: Khi nào/tại sao họ dùng app
+```
+
+### 2.2 Phân tích Hiệu suất theo Quốc gia
+```
+🌍 Cross-analyze từ nhiều nguồn:
+- Google Ads: Cost, CPI, Conversions by country
+- Firebase: Engagement, Retention by country
+- Play Console: Store Conversion by country
+
+→ Tính điểm Potential Score cho mỗi quốc gia:
+  Score = (Conversion Rate × Engagement) / CPI
+
+→ Phân loại Tier:
+| Tier | Tiêu chí | Chiến lược |
+|------|----------|------------|
+| Tier 1 | Score cao, ROAS tốt | Scale mạnh |
+| Tier 2 | Volume ổn định | Duy trì, tối ưu |
+| Tier 3 | Score thấp hoặc chưa test | Test/Cut |
+```
+
+### 2.3 Phân tích Keywords & Search Intent
+```
+🔑 Từ Play Console hoặc ASO research:
+1. Top 20 keywords hiện tại (có data)
+2. Đề xuất 20 keywords tương tự (potential)
+3. Keywords theo quốc gia có conversion tốt
+
+→ Mapping keywords vào Ad Copy strategy
+```
+
+---
+
+## PHASE 3: CHIẾN LƯỢC TỐI ƯU (Optimization Strategy)
+
+### 3.1 Chiến lược theo Loại App
+```
+📲 Tùy loại app mà áp dụng chiến lược khác:
+
+| App Type | Focus | Bidding | Creative Style |
+|----------|-------|---------|----------------|
+| Game | Installs + Engagement | tCPA/tROAS | Gameplay, Rewards |
+| Utility | Downloads + Retention | tCPA | Problem-Solution |
+| Social | Virality + DAU | Max Conversions | Community, FOMO |
+| E-commerce | Purchases + LTV | tROAS | Deals, Trust |
+| Content | Time Spent | tCPA | Preview, Curiosity |
+```
+
+### 3.2 Cấu trúc Campaign đề xuất
+```
+🏗️ Structure theo Tier + Language:
+
+Campaign: [App] - Tier 1 Expansion
+├── Ad Group: [Country1] - [Language]
+├── Ad Group: [Country2] - [Language]
+└── ...
+
+Campaign: [App] - Tier 2 Core
+├── Ad Group: [Region] - [Language]
+└── ...
+
+Campaign: [App] - Tier 3 Test
+└── Ad Group: New Markets
+```
+
+### 3.3 Chiến lược Bidding tối ưu
+```
+💰 Dựa trên dữ liệu thực tế:
+- Tính CPI trung bình hiện tại
+- Xác định LTV (từ revenue data nếu có)
+- Đề xuất Target CPA = LTV × acceptable ROAS
+
+Tier 1: Aggressive (CPA × 1.2)
+Tier 2: Balanced (CPA × 1.0)
+Tier 3: Conservative (CPA × 0.7)
+```
+
+---
+
+## PHASE 4: SẢN XUẤT NỘI DUNG (Creative Production)
+
+### 4.1 Content Strategy theo Persona
+```
+✍️ Tạo nội dung phù hợp đối tượng:
+
+1. Xác định Message Angles:
+   - Functional: Tính năng app làm được gì
+   - Emotional: Cảm xúc khi dùng app
+   - Social: Người khác nghĩ gì/dùng như thế nào
+
+2. Viết theo ngôn ngữ của Persona:
+   - Gen Z: Casual, trendy, emoji
+   - Professional: Clear, benefit-focused
+   - Parents: Trust, safety, value
+```
+
+### 4.2 Text Assets (5+ mỗi ngôn ngữ)
+```
+📝 Headlines (max 30 chars):
+| # | Type | Template |
+|---|------|----------|
+| 1 | Brand | [App Name] |
+| 2 | Benefit | [Main Benefit] |
+| 3 | Feature | [Key Feature] |
+| 4 | Social Proof | [Rating/Downloads] |
+| 5 | CTA | [Action Verb] |
+| 6 | Problem | [Pain Point Solution] |
+| 7 | Emotional | [Emotional Hook] |
+
+📝 Descriptions (max 90 chars):
+| # | Type | Template |
+|---|------|----------|
+| 1 | Overview | [What app does + CTA] |
+| 2 | Features | [Top 2-3 features] |
+| 3 | Benefit | [User outcome] |
+| 4 | Social | [Reviews/ratings] |
+| 5 | Urgency | [Download now reason] |
+
+→ Localize cho mỗi ngôn ngữ target
+```
+
+### 4.3 Image Assets (5+ mỗi concept)
+```
+🖼️ Sử dụng generate_image tool:
+
+Concepts (chọn phù hợp với app):
+1. Lifestyle: User trong context thực tế
+2. UI Showcase: Giao diện app đẹp nhất
+3. Before/After: Transformation
+4. Social: Group/Community vibe
+5. Aesthetic: Mood/Vibe của app
+6. Feature Focus: Highlight tính năng
+7. Emotional: Outcome/Feeling
+
+Sizes cần tạo:
+- 1:1 (1024x1024) - Universal
+- 1.91:1 (1200x628) - Landscape/Banner
+- 4:5 (1080x1350) - Portrait/Stories
+```
+
+### 4.4 Video Production (Veo 3.1)
+```
+🎥 Tận dụng AI Video (Optional but Recommended):
+
+Công cụ: Google Veo 3.1 (qua VideoAdEngine)
+Yêu cầu: GEMINI_API_KEY
+
+Quy trình:
+1. Image-to-Video: Dùng ảnh Lifestyle/Feature làm input.
+2. Prompt: Mô tả chuyển động nhẹ nhàng (cinematic pan, zoom, particle effects).
+3. Variations (Tự động):
+   - 16:9 (Gốc) -> YouTube
+   - 9:16 (Auto-crop) -> TikTok/Reels/Shorts
+   - 1:1 (Auto-crop) -> Feed
+   
+→ Output: Full set video assets cho mọi placement.
+```
+
+---
+
+## PHASE 5: TRIỂN KHAI (Execution)
+
+### 5.1 Upload Assets
+```
+📤 Sử dụng tools:
+→ upload_image_asset(customer_id, image_path, name)
+→ Đảm bảo đặt tên rõ ràng: "[Concept]-[Size]-[Lang]"
+```
+
+### 5.2 Tạo Ad Groups & Ads
+```
+📢 Mỗi Ad Group cần:
+- 5+ Headlines (đúng ngôn ngữ)
+- 5+ Descriptions (đúng ngôn ngữ)
+- 5+ Images (đủ tỷ lệ)
+
+→ create_app_ad(customer_id, ad_group_id, headlines, descriptions, images)
+```
+
+### 5.3 Verification
+```
+✅ Checklist:
+[ ] Mỗi Campaign có đúng Tier targeting
+[ ] Location Include/Exclude không overlap
+[ ] Mỗi Ad có 5+ text, 5+ images
+[ ] Bidding strategy đã set
+[ ] Conversion tracking active
+```
+
+---
+
+## PHASE 6: BÁO CÁO & THEO DÕI (Reporting)
+
+### 6.1 Báo cáo Tổng hợp
+```
+📊 Output Report:
+1. Tổng quan App & Persona
+2. Phân tích thị trường (Tier breakdown)
+3. Chiến lược đã áp dụng
+4. Assets đã tạo (số lượng)
+5. Đề xuất theo dõi
+```
+
+### 6.2 Metrics cần theo dõi
+```
+📈 KPIs:
+- CTR (target: >1% cho App Campaigns)
+- CPI (so với benchmark)
+- Conversion Rate by Creative
+- ROAS (nếu có revenue tracking)
+```
+
+---
+
+## 🛠 MCP TOOLS REFERENCE
+
+| Task | Tool |
+|------|------|
+| List accounts | `mcp_mcp-google-ads_list_accounts` |
+| Get currency | `mcp_mcp-google-ads_get_account_currency` |
+| Campaign data | `mcp_mcp-google-ads_get_campaign_performance` |
+| Custom query | `mcp_mcp-google-ads_run_gaql` |
+| Set ROAS | `mcp_mcp-google-ads_set_campaign_target_roas` |
+| Set CPA | `mcp_mcp-google-ads_set_campaign_target_cpa` |
+| Pause/Enable | `mcp_mcp-google-ads_pause_campaign`, `enable_campaign` |
+| Create image | `generate_image` |
+| Upload asset | `upload_image_asset` (custom) |
+| Create ad | `create_app_ad` (custom) |
+
+---
+
+## 💡 SỬ DỤNG
+
+```
+/ads-full-optimization
+```
+
+AI sẽ hỏi tuần tự:
+1. "Cung cấp Store URL hoặc Bundle ID của app"
+2. "Cung cấp Customer ID Google Ads"
+3. "Có dữ liệu Firebase/Play Console không?" (tùy chọn)
+
+Sau đó AI thực hiện phân tích và đề xuất, chờ xác nhận tại mỗi Phase quan trọng.

package/workflows/_uncategorized/ads-plan.md

@@ -0,0 +1,247 @@
+# WORKFLOW: /ads-plan - Lập kế hoạch & Preview Quảng cáo
+
+Bạn là **Antigravity Ads Planner** - lập kế hoạch quảng cáo chi tiết với preview trước khi deploy.
+
+---
+
+## 🎯 MỤC TIÊU
+
+- Lập kế hoạch chi tiết cho chiến dịch quảng cáo
+- Tạo mẫu quảng cáo (text + images + video concepts)
+- Preview để user duyệt trước khi upload
+- Export ra định dạng có thể upload bằng CLI tool
+
+---
+
+## PHASE 1: KHỞI TẠO KẾ HOẠCH
+
+### 1.1 Thu thập thông tin
+```
+📱 Input:
+1. Store URL hoặc mô tả app
+2. Target audience
+3. Budget dự kiến
+4. Số lượng ads cần tạo (min 5)
+5. Ngôn ngữ target
+```
+
+### 1.2 Tạo Plan Directory
+```
+📂 Tạo thư mục kế hoạch:
+
+→ Tạo folder: ./ads_plan_[app_name]_[date]/
+  ├── plan.json          # Kế hoạch tổng thể
+  ├── text_assets.json   # Text assets
+  ├── images/            # Ảnh đã generate
+  ├── videos/            # Video concepts
+  └── preview.html       # Preview page
+```
+
+---
+
+## PHASE 2: LẬP KẾ HOẠCH CHI TIẾT
+
+### 2.1 Cấu trúc plan.json
+```json
+{
+  "app_name": "[App Name]",
+  "customer_id": "[Google Ads Customer ID]",
+  "campaign_id": "[Target Campaign ID]",
+  "created_at": "[ISO Date]",
+  "status": "draft",
+  
+  "ad_groups": [
+    {
+      "id": "ag_1",
+      "name": "[Ad Group Name]",
+      "angle": "AIDA|PAS|BAB",
+      "language": "en|ja|th|...",
+      "status": "pending"
+    }
+  ],
+  
+  "text_assets": {
+    "ag_1": {
+      "headlines": ["...", "...", "..."],
+      "descriptions": ["...", "...", "..."]
+    }
+  },
+  
+  "image_assets": {
+    "ag_1": [
+      {"path": "images/ag1_lifestyle.png", "concept": "Lifestyle", "size": "1024x1024"},
+      {"path": "images/ag1_ui.png", "concept": "UI", "size": "1200x628"}
+    ]
+  },
+  
+  "video_concepts": {
+    "ag_1": [
+      {"description": "15s video showing...", "storyboard": "..."}
+    ]
+  }
+}
+```
+
+### 2.2 Tạo Text Assets
+```
+✍️ Cho mỗi Ad Group, tạo:
+- 5+ Headlines (30 chars)
+- 5+ Descriptions (90 chars)
+
+Lưu vào text_assets.json với format:
+{
+  "ag_1": {
+    "headlines": [...],
+    "descriptions": [...]
+  },
+  "ag_2": {...}
+}
+```
+
+---
+
+## PHASE 3: TẠO HÌNH ẢNH
+
+### 3.1 Generate Images
+```
+🖼️ Sử dụng generate_image:
+
+Cho mỗi Ad Group, tạo tối thiểu 5 ảnh:
+1. Lifestyle (1:1)
+2. Lifestyle (1.91:1)
+3. UI Showcase (1:1)
+4. Emotional (4:5)
+5. Feature Focus (1.91:1)
+
+Lưu vào folder: ./ads_plan_xxx/images/
+Naming: [ad_group_id]_[concept]_[size].png
+```
+
+### 3.2 Video Concepts (Optional)
+```
+🎬 Tạo storyboard cho video ads:
+
+{
+  "duration": "15s",
+  "scenes": [
+    {"time": "0-3s", "visual": "Hook scene", "text": "..."},
+    {"time": "3-8s", "visual": "Demo", "text": "..."},
+    {"time": "8-12s", "visual": "Benefits", "text": "..."},
+    {"time": "12-15s", "visual": "CTA", "text": "Download Now"}
+  ]
+}
+
+(Video generation sẽ cần tool khác hoặc manual)
+```
+
+---
+
+## PHASE 4: TẠO PREVIEW
+
+### 4.1 Generate Preview HTML
+```html
+<!-- preview.html template -->
+Tạo file HTML hiển thị:
+- Tất cả Ad Groups
+- Text assets (Headlines, Descriptions)
+- Image previews
+- Video concepts (storyboard)
+- Checkbox để approve/reject từng item
+```
+
+### 4.2 Preview Format
+```
+📱 Preview hiển thị như ad thực tế:
+- Mobile frame mockup
+- Text overlay trên image
+- Multiple variations
+```
+
+---
+
+## PHASE 5: DUYỆT & EXPORT
+
+### 5.1 User Review
+```
+✅ User mở preview.html và đánh dấu:
+- [x] Approve ad group 1
+- [ ] Reject ad group 2 (cần sửa)
+- [x] Approve ad group 3
+...
+```
+
+### 5.2 Export approved.json
+```json
+{
+  "approved_at": "[ISO Date]",
+  "ad_groups": ["ag_1", "ag_3"],
+  "excluded": ["ag_2"],
+  "ready_to_upload": true
+}
+```
+
+---
+
+## PHASE 6: UPLOAD VIA CLI
+
+### 6.1 Sử dụng CLI Tool
+```bash
+# Upload tất cả approved ads
+npx ads-uploader upload ./ads_plan_xxx/
+
+# Upload 1 ad group cụ thể
+npx ads-uploader upload ./ads_plan_xxx/ --group ag_1
+
+# Dry run (preview without upload)
+npx ads-uploader upload ./ads_plan_xxx/ --dry-run
+```
+
+---
+
+## 📊 OUTPUT FILES
+
+```
+./ads_plan_[app]_[date]/
+├── plan.json           # Master plan
+├── text_assets.json    # All text
+├── approved.json       # User approval
+├── images/
+│   ├── ag1_lifestyle_1024.png
+│   ├── ag1_ui_1200x628.png
+│   └── ...
+├── videos/
+│   └── storyboards.json
+└── preview.html        # Visual preview
+```
+
+---
+
+## 📜 History Tracking Rule (Bắt buộc)
+
+Sau khi hoàn thành workflow, AI **PHẢI** ghi log vào file `brain/ads_history_log.md` theo format sau:
+
+```markdown
+### [YYYY-MM-DD HH:mm] /ads-plan
+- **Action:** [Plan Creation]
+- **Target:** [App Name]
+- **Plan Status:** [Draft / Approved]
+- **Path:** [Path to plan.json]
+```
+
+**Lưu ý:** Nếu file không tồn tại, hãy tạo mới.
+
+---
+
+## 💡 SỬ DỤNG
+
+```
+/ads-plan
+```
+
+Quy trình:
+1. AI thu thập thông tin app
+2. AI tạo plan.json + text assets
+3. AI generate images
+4. AI tạo preview.html
+5. User review & approve
+6. User chạy CLI để upload