@leejungkiin/awkit 1.7.0 → 1.7.4

package/workflows/ads/smali-ads-flow.md

@@ -0,0 +1,331 @@
+---
+description: 📺 Tích hợp Ads Flow vào APK mod (Smali) - Splash → Ads → Onboarding → Home
+---
+
+# Smali Ads Flow Integration
+
+> **🎯 Mục tiêu**: Tạo luồng quảng cáo trong APK mod bằng cách hook vào Splash Activity có sẵn.
+
+---
+
+## 📋 Flow Logic Overview
+
+### First Launch (Lần đầu)
+```
+Splash → Inter Ad (100%) → Onboarding + Native Ads → Inter Ad (100%) → Home
+```
+
+### Return Visit (Lần 2+)
+```
+Splash → Inter Ad (random mỗi 3-5 lần) → Home
+```
+
+---
+
+## 🎬 Phase 1: Phân Tích Entry Points
+
+**Prerequisites**: Đã decompile APK (xem `apk-modifier` skill)
+
+### 1.1. Xác định Splash Activity
+
+```bash
+# Tìm LAUNCHER Activity trong AndroidManifest.xml
+grep -r "android.intent.category.LAUNCHER" AndroidManifest.xml
+
+# Kiểm tra có Splash Activity riêng không
+find smali* -name "*Splash*.smali"
+```
+
+**Kết quả mong đợi:**
+- **Scenario A**: App có `SplashActivity` riêng
+- **Scenario B**: `MainActivity` là LAUNCHER (không có Splash)
+
+### 1.2. Phân tích Navigation Flow
+
+**Sử dụng jadx để hiểu logic:**
+```bash
+jadx-gui target.apk
+```
+
+**Cần xác định:**
+- Method chứa navigation logic (ví dụ: `navigateToMain()`, `goHome()`)
+- Delay mechanism (Handler.postDelayed, Timer, etc.)
+- Target activity (MainActivity class name)
+
+**Document findings:**
+```
+Current Flow: [Splash/MainActivity] → [Activity?] → [FinalActivity]
+Navigation Method: navigateToMain() / goHome() / etc.
+Target Activity: com.example.app.MainActivity
+```
+
+---
+
+## 📦 Phase 2: Thiết Kế Components
+
+### 2.1. Cấu trúc SDK cần tạo
+
+```
+{SDK_DIR}/
+├── config/
+│   └── AppPreferences.smali     # Quản lý state & random logic
+└── activities/
+    └── OnboardingActivity.smali  # Onboarding với Native Ads
+```
+
+**Note**: 
+- `{SDK_DIR}` = thư mục SDK bạn chọn (ví dụ: `smali_classes2/com/myads/`)
+- Package name tùy chỉnh theo dự án
+
+### 2.2. Config Strategy
+
+**Option 1**: JSON config file trong assets
+```json
+{
+  "ad_ids": {...},
+  "frequency": {"min": 3, "max": 5},
+  "main_activity": "com.target.app.MainActivity"
+}
+```
+
+**Option 2**: Hardcode trong Smali constants
+```smali
+.field private static final INTER_FREQUENCY_MIN:I = 0x3
+.field private static final INTER_FREQUENCY_MAX:I = 0x5
+```
+
+---
+
+## 🔧 Phase 3: Implementation Strategy
+
+### 3.1. Component: AppPreferences
+
+**Chức năng cần implement:**
+
+| Method | Mục đích | Return |
+|--------|----------|--------|
+| `isFirstLaunch()` | Kiểm tra lần đầu mở app | boolean |
+| `setFirstLaunchDone()` | Đánh dấu đã onboarding | void |
+| `incrementOpenCount()` | Tăng counter mỗi lần mở | int |
+| `shouldShowInterAd()` | Random 3-5 lần | boolean |
+
+**Storage**: SharedPreferences
+
+**Implementation**: Xem chi tiết Smali syntax trong `apk-modifier` skill
+
+---
+
+### 3.2. Injection Strategy
+
+#### Scenario A: App có SplashActivity
+
+**Hook Point 1: onCreate()**
+```
+Location: SplashActivity.smali
+Action: Inject tracking
+→ Call incrementOpenCount()
+```
+
+**Hook Point 2: Navigation Method**
+```
+Location: navigateToMain() / goHome() / etc.
+Action: Inject flow logic
+→ if isFirstLaunch() → go to Onboarding
+→ else if shouldShowInterAd() → show Inter
+→ else → go to MainActivity
+```
+
+---
+
+#### Scenario B: MainActivity là LAUNCHER
+
+**Hook Point: onCreate()**
+```
+Location: MainActivity.smali
+Action 1: Tạo method mới checkAdsFlow()
+Action 2: Inject call vào đầu onCreate()
+→ Call checkAdsFlow()
+→ Logic tương tự Scenario A
+```
+
+---
+
+### 3.3. Component: OnboardingActivity
+
+**Chức năng:**
+- ViewPager/HorizontalScrollView với N slides
+- Native Ad container (giữa hoặc cuối slides)
+- Next/Skip buttons
+- Khi complete → call `setFirstLaunchDone()`
+
+**Navigation:**
+```
+OnboardingActivity → [Show Inter Ad?] → MainActivity
+```
+
+---
+
+## 🔌 Phase 4: Integration
+
+### 4.1. AndroidManifest Changes
+
+**Thêm permissions:**
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+```
+
+**Thêm AdMob App ID:**
+```xml
+<meta-data
+    android:name="com.google.android.gms.ads.APPLICATION_ID"
+    android:value="ca-app-pub-{YOUR_PUBLISHER_ID}~{APP_ID}"/>
+```
+
+**Đăng ký OnboardingActivity:**
+```xml
+<activity 
+    android:name="{YOUR_PACKAGE}.activities.OnboardingActivity"
+    android:exported="false"
+    android:theme="@android:style/Theme.NoTitleBar.Fullscreen"/>
+```
+
+**⚠️ Quan trọng**: KHÔNG thay đổi LAUNCHER activity
+
+---
+
+### 4.2. Copy Dependencies
+
+```bash
+# Tùy project structure, có thể là smali, smali_classes2, etc.
+
+# Copy AdMob libraries (nếu chưa có)
+# Thường nằm trong com/google/android/gms/ads/
+
+# Verify method count
+find smali* -name "*.smali" | wc -l  # Phải < 60,000
+```
+
+---
+
+### 4.3. Reference Validation
+
+**Kiểm tra injection đúng:**
+```bash
+# Tìm tất cả reference đến AppPreferences
+grep -r "AppPreferences" smali*/
+
+# Tìm reference đến OnboardingActivity
+grep -r "OnboardingActivity" smali*/
+```
+
+**Expected**: Thấy reference trong Splash/MainActivity
+
+---
+
+## 📺 Phase 5: Ads Implementation
+
+> **Tách workflow riêng**: `/smali-ads-interstitial`, `/smali-ads-native`
+
+**Tổng quan:**
+1. **Interstitial Ads**
+   - Load khi Splash onCreate()
+   - Show sau Splash, sau Onboarding
+   - Show random theo `shouldShowInterAd()`
+
+2. **Native Ads**
+   - Load trong OnboardingActivity
+   - Display trong ad container
+   - Cleanup khi destroy
+
+**Chi tiết**: Xem workflows riêng
+
+---
+
+## ✅ Phase 6: Build & Test
+
+```
+
+### 6.2. Test Scenarios
+
+| Scenario | Expected Behavior | Verification |
+|----------|-------------------|--------------|
+| **First Launch** | Splash → [Inter?] → Onboarding → [Inter?] → Home | Clear app data, launch |
+| **2nd Launch** | Splash → Home (no ads) | Launch again |
+| **3rd-5th Random** | Splash → [Inter random] → Home | Launch 10+ times, observe pattern |
+| **Onboarding Skip** | Skip button works, navigate correctly | Test skip button |
+
+### 6.3. Debug Commands
+
+```bash
+# Monitor flow events
+adb logcat | grep -E "Preference|Onboarding|Navigation"
+
+# Check SharedPreferences state
+adb shell run-as {package} cat /data/data/{package}/shared_prefs/*.xml
+
+# Extract & verify counter
+# Should see: open_count, next_ad_count, first_launch values
+```
+
+---
+
+## 📋 Implementation Checklist
+
+### Pre-Implementation
+- [ ] APK đã decompile xong
+- [ ] Xác định Splash/MainActivity và navigation method
+- [ ] Document flow hiện tại
+- [ ] Backup APK gốc
+
+### Core Components
+- [ ] Tạo AppPreferences với 4 methods
+- [ ] Implement random logic (3-5 range)
+- [ ] Tạo OnboardingActivity skeleton
+- [ ] Test SharedPreferences đọc/ghi đúng
+
+### Injection
+- [ ] Hook vào onCreate() - tracking
+- [ ] Hook vào navigation method - flow logic
+- [ ] Test first launch flow
+- [ ] Test return visit flow
+
+### Integration
+- [ ] Update AndroidManifest
+- [ ] Copy dependencies (check method count)
+- [ ] Validate all references
+- [ ] Build thành công (no errors)
+
+### Testing
+- [ ] First launch: đúng flow
+- [ ] Return visit: random đúng (test 10+ lần)
+- [ ] Onboarding: skip/next works
+- [ ] No crashes, no ANR
+
+---
+
+## 🔗 Related Resources
+
+### Workflows
+- `/smali-ads-interstitial` - Interstitial Ads implementation
+- `/smali-ads-native` - Native Ads implementation
+- `/smali-ads-config` - Remote Config cho Ad settings
+
+### Skills & Docs
+- **Skill**: `apk-modifier` - Smali techniques & examples
+- **Cheatsheet**: `SMALI_CHEATSHEET.md` - Syntax reference
+- **Tool**: jadx-gui - Decompile để đọc logic
+
+---
+
+## 💡 Tips & Best Practices
+
+1. **Package Naming**: Chọn tên package phù hợp với app để tránh confusion
+2. **Method Count**: Monitor liên tục, phân bổ sang smali_classes* nếu cần
+3. **Testing**: Test với nhiều scenarios, đặc biệt random logic
+4. **Logging**: Thêm Log.d() trong Smali để debug flow
+5. **Backup**: Luôn giữ backup trước mỗi thay đổi lớn
+
+---
+
+**⚠️ Note**: Workflow này chỉ tập trung vào **FLOW LOGIC**. Chi tiết Ads implementation xem workflows riêng.

package/workflows/ads/smali-ads-interstitial.md

@@ -0,0 +1,377 @@
+---
+description: 📱 Tích hợp Interstitial Ads vào APK mod - Tận dụng library có sẵn
+---
+
+# Smali Interstitial Ads Integration
+
+> **🎯 Mục tiêu**: Tích hợp Interstitial Ads bằng cách tận dụng ads library có sẵn trong APK.
+
+---
+
+## 🔍 Phase 1: Discovery - Tìm Ads Library có sẵn
+
+### 1.1. Scan toàn bộ cấu trúc
+
+**Pattern 1: Tìm theo tên thư mục**
+```bash
+# Tìm các thư mục có chứa "ad"
+find smali* -type d -iname "*ad*"
+
+# Patterns thường gặp:
+# - */ads/, */adslib/, */admanager/
+# - */admob/, */admod/, */adsdk/
+# - */advertisement/, */adnetwork/
+```
+
+**Pattern 2: Tìm theo package Google**
+```bash
+# AdMob SDK chính thống
+find smali* -path "*/com/google/android/gms/ads/*" -type d
+
+# Firebase Ads
+find smali* -path "*/com/google/firebase/ads/*" -type d
+```
+
+**Pattern 3: Tìm theo custom wrapper**
+```bash
+# Tìm trong package chính của app
+find smali*/{main_package}/* -type d -iname "*ad*"
+```
+
+### 1.2. Identify Interstitial Components
+
+**Search Strategy:**
+```bash
+# Tìm file có chứa "Inter" và liên quan đến ad
+find smali* -name "*Inter*.smali" | xargs grep -l "Lcom/google/android/gms/ads"
+
+# Tìm theo keyword khác
+find smali* -name "*.smali" | xargs grep -l "interstitial\|InterstitialAd"
+
+# Tìm theo usage pattern
+find smali* -name "*.smali" | xargs grep -l "loadInterstitialAd\|showInterstitialAd"
+```
+
+**Common class names (chỉ tham khảo):**
+- `*InterstitialAd*.smali`
+- `*InterAd*.smali` 
+- `*FullscreenAd*.smali`
+- `*AdManager*.smali` (có thể chứa inter logic)
+
+### 1.3. Reverse Engineer Implementation
+
+**Step 1: Jadx analysis**
+```bash
+jadx-gui target.apk
+```
+
+**Tìm kiếm:**
+1. Search "InterstitialAd" trong jadx
+2. Xem existing usage trong app
+3. Document class hierarchy
+4. Note down package structure
+
+**Step 2: Document API**
+```
+[Findings Template]
+
+Ads Library Location: smali_classes*/{discovered_path}/
+Interstitial Class: {ClassName}.smali
+Package: {full.package.name}
+
+Methods Found:
+- Constructor: <init>(...)
+- Load: {methodName}(...)
+- Show: {methodName}(...)
+- Check Ready: {methodName}()
+
+Callbacks:
+- Interface: {CallbackInterfaceName}
+- Methods: onAdLoaded(), onAdClosed(), etc.
+
+Current Usage:
+- Used in: {ActivityName}.smali
+- Called from: {methodName}()
+```
+
+---
+
+## 📦 Phase 2: API Analysis
+
+### 2.1. Understand Method Signatures
+
+**Sử dụng jadx để xem Java code:**
+```java
+// Example pattern (structure varies)
+public class InterstitialAdHelper {
+    public void init(Context context, String adId);
+    public void loadAd();
+    public void show(Activity activity);
+    public boolean isReady();
+    public void setListener(AdListener listener);
+}
+```
+
+**Convert to Smali signatures:**
+```smali
+.method public init(Landroid/content/Context;Ljava/lang/String;)V
+.method public loadAd()V
+.method public show(Landroid/app/Activity;)V
+.method public isReady()Z
+.method public setListener(L{package}/AdListener;)V
+```
+
+### 2.2. Identify Dependencies
+
+**Check AdMob presence:**
+```bash
+# Core AdMob classes
+ls smali*/com/google/android/gms/ads/ 2>/dev/null
+
+# If missing, need to copy from:
+# - Another APK with AdMob
+# - Extract from Google Play Services AAR
+```
+
+**Check custom wrappers:**
+```bash
+# Tìm dependency classes
+grep -r "import.*AdRequest\|import.*InterstitialAd" smali*/ | head -20
+```
+
+---
+
+## 🔧 Phase 3: Wrapper Creation
+
+### 3.1. Tạo Wrapper Class (Option)
+
+**Mục đích**: Standardize API để dễ sử dụng
+
+```
+{SDK_DIR}/ads/InterstitialWrapper.smali
+```
+
+**Chức năng:**
+- Wrap existing library
+- Handle lifecycle
+- Provide clean API
+- Manage ad caching
+
+**Methods cần có:**
+```
+init(Context, String adId) → Initialize
+load() → Load ad
+show(Activity) → Show ad  
+isReady() → Check ready state
+destroy() → Cleanup
+```
+
+### 3.2. State Management
+
+**Track states:**
+- `NOT_LOADED` - Chưa load
+- `LOADING` - Đang load
+- `LOADED` - Đã load, ready
+- `SHOWING` - Đang hiển thị
+- `CLOSED` - Đã đóng
+
+**Implementation**: Dùng enum hoặc int constants
+
+---
+
+## 🎯 Phase 4: Integration Points
+
+### 4.1. Load Ad - Khi nào?
+
+**Strategy 1: Pre-load sớm**
+```
+Application.onCreate() → Load ad
+Splash.onCreate() → Load ad
+```
+**Pros**: Ad sẵn sàng khi cần
+**Cons**: Tốn resources nếu user không trigger
+
+**Strategy 2: On-demand**
+```
+Before navigation → Load ad → Show ad
+```
+**Pros**: Tiết kiệm resources
+**Cons**: Có delay khi show
+
+### 4.2. Show Ad - Ở đâu?
+
+**Theo `/smali-ads-flow`:**
+- Sau Splash (first launch)
+- Sau Onboarding (first launch)
+- Random 3-5 lần (return visit)
+
+**Implementation:**
+```
+Location: SplashActivity.navigateToMain()
+Action: Insert show ad logic
+→ if shouldShowAd():
+    → interstitialWrapper.show(this)
+    → onAdClosed: navigate to next screen
+→ else:
+    → navigate directly
+```
+
+### 4.3. Handle Callbacks
+
+**OnAdClosed callback:**
+- Navigate to next screen
+- Resume app flow
+- Load next ad (pre-cache)
+
+**OnAdFailedToLoad:**
+- Fallback: skip ad, continue flow
+- Log error for debugging
+- Retry với exponential backoff?
+
+---
+
+## 🔌 Phase 5: Hook Implementation
+
+### 5.1. Hook Point Template
+
+**Generic pattern:**
+```smali
+# Original code
+.method private navigateToNextScreen()V
+    # ... navigation logic ...
+.end method
+```
+
+**After injection:**
+```smali
+.method private navigateToNextScreen()V
+    # Check if should show ad
+    invoke-static {p0}, {AdHelper};->shouldShowInterAd()Z
+    move-result v0
+    
+    if-eqz v0, :skip_ad
+    
+    # Show inter ad
+    invoke-static {p0}, {InterWrapper};->show(Activity)V
+    # Ad callback will handle navigation
+    return-void
+    
+    :skip_ad
+    # Original navigation logic
+    # ...
+.end method
+```
+
+### 5.2. Callback Handler
+
+**Create callback class:**
+```
+{SDK_DIR}/ads/InterstitialCallback.smali
+```
+
+**Implement:**
+```
+onAdClosed() {
+    // Resume navigation
+    navigateToNextScreen()
+}
+
+onAdFailedToShow() {
+    // Fallback
+    navigateToNextScreen()
+}
+```
+
+---
+
+## ✅ Phase 6: Testing & Validation
+
+### 6.1. Functional Tests
+
+| Test Case | Expected | Command |
+|-----------|----------|---------|
+| **Load Success** | Ad loads, isReady=true | Monitor logcat |
+| **Show Success** | Ad displays fullscreen | Visual check |
+| **Callback Fired** | onAdClosed called | Check logs |
+| **Navigation** | Nav to next screen after ad | Flow test |
+| **No Network** | Fallback, skip ad | Airplane mode test |
+
+### 6.2. Integration Tests
+
+**With `/smali-ads-flow`:**
+- First launch: Show after Splash ✓
+- First launch: Show after Onboarding ✓
+- Return visit: Random 3-5 times ✓
+
+### 6.3. Debug Commands
+
+```bash
+# Monitor ad events
+adb logcat | grep -E "InterstitialAd|AdMob|onAd"
+
+# Test ad with test ID
+# Replace ad unit ID with test ID:
+# ca-app-pub-3940256099942544/1033173712 (Android Test Inter)
+
+# Force show ad (for testing)
+# Modify shouldShowInterAd() to always return true
+```
+
+---
+
+## 📋 Implementation Checklist
+
+### Discovery
+- [ ] Tìm được ads library trong APK
+- [ ] Xác định Interstitial class
+- [ ] Document API methods
+- [ ] Check dependencies đầy đủ
+
+### Wrapper (Optional)
+- [ ] Tạo wrapper class
+- [ ] Implement init/load/show
+- [ ] Handle state management
+- [ ] Test wrapper riêng lẻ
+
+### Integration
+- [ ] Xác định hook points (từ `/smali-ads-flow`)
+- [ ] Inject load ad logic
+- [ ] Inject show ad logic
+- [ ] Implement callbacks
+
+### Testing
+- [ ] Load ad thành công
+- [ ] Show ad thành công
+- [ ] Callback navigation đúng
+- [ ] Fallback khi no network
+- [ ] Integration với flow logic
+
+---
+
+## 🔗 Related Resources
+
+### Workflows
+- `/smali-ads-flow` - Main flow logic
+- `/smali-ads-native` - Native ads
+- `/smali-ads-config` - Remote config
+
+### Skills
+- `apk-modifier` - Smali techniques
+
+### References
+- [AdMob Interstitial Docs](https://developers.google.com/admob/android/interstitial)
+- [AdMob Test Ads](https://developers.google.com/admob/android/test-ads)
+
+---
+
+## 💡 Tips & Best Practices
+
+1. **Reuse existing library**: Tận dụng library có sẵn thay vì viết từ đầu
+2. **Test ID first**: Dùng test ad ID khi debug để tránh invalid traffic
+3. **Fallback gracefully**: Luôn có fallback khi ad fail
+4. **Pre-load smart**: Load ad sớm nhưng đừng lãng phí resources
+5. **Respect ad policies**: Không force click, không spam ads
+
+---
+
+**⚠️ Quan trọng**: Tuân thủ AdMob policies để tránh bị ban account!