@hungvv/super-ads-skills 1.0.0 → 1.1.0

package/skills/super-ads-upgrade/templates/changelog-template.md

@@ -0,0 +1,39 @@
+# Changelog nâng cấp SuperAds
+
+Điền từ kết quả thật; mục không áp dụng ghi "Không".
+
+## Tổng quan
+- App / module: <tên>
+- SuperAds: <từ> -> <lên>
+- Artifact đã nâng (core + plugin, cùng version): <danh sách>
+- Nhánh git: <tên>
+
+## Import đã đổi
+| File | Import cũ | Import mới |
+|---|---|---|
+
+## Logic đã đổi
+| File | Thay đổi | Lý do (mục `MIGRATION.md`) |
+|---|---|---|
+
+## Config JSON
+| Key | Thêm / Xoá / Đổi tên / Đổi giá trị | Patch đã duyệt |
+|---|---|---|
+
+## Thay đổi hành vi
+- <mục hành vi và có ảnh hưởng app hay không>
+
+## Đã kiểm
+| Việc | Lệnh / tool | Kết quả thật |
+|---|---|---|
+| Build | | |
+| Mọi artifact cùng version | | |
+| validate_config | | |
+| Thiết bị (super-ads-adb-test) | | |
+
+## Bỏ qua và việc còn lại cho user
+- <bước bỏ qua kèm lý do>
+- <việc user cần làm, vd publish artifact, kiểm bản phát hành>
+
+## Lỗi / vấn đề gặp
+- <mô tả và cách xử lý>

package/skills/super-ads-add-placement/references/call-site-snippets.md

@@ -1,90 +0,0 @@
-# Call site theo nhóm format
-
-> Authority: code SDK. `SA/` = `super-ads/src/main/java/com/android/fullhd/super_ads/`.
-> App đã có wrapper (vd `AdsUtils`, extension `showAdView`) thì **gọi qua wrapper**, không gọi `Ads.show` trực tiếp bên cạnh. Mẫu wrapper: [../../adspro-to-superads/references/wrapper-template.md](../../adspro-to-superads/references/wrapper-template.md).
-
-## API dùng chung
-
-| API | Chữ ký / hành vi | Nguồn |
-|---|---|---|
-| `Ads.show` | `show(placementId, activity, target = AdTarget.AdFull, callback = LoggerAdsCallback())`; callback chạy trên main; gọi trước khi init xong thì xếp hàng chờ | `SA/api/Ads.kt:200-217` |
-| `AdTarget` | `AdFull` (fullscreen) hoặc `AdView(container, lifecycleOfViewOwner = null)` (inline) | `SA/api/model/AdTarget.kt:7-15` |
-| `AdsCallback` | `onAdImpression`, `onAdShowedFull`, `onAdDismissedFull`, `onAdCollapsibleDismiss`, `onAdFailed`, `onUserEarnedReward`, `onAdClicked` (đều có thân mặc định) | `SA/api/callback/AdsCallback.kt:32-120` |
-| `NavAdCallback` | gọi `onNav` một lần theo `mode.navigate`; fail thì `NavResult.Failed` | `SA/api/callback/AdsCallback.kt:122-191` |
-| `RewardAdCallback` | gọi `onReward` một lần lúc dismiss; `Premium` coi là `Success` | `SA/api/callback/AdsCallback.kt:194-266` |
-| `Ads.dispatchEvent` | preload các adItem có `preload.eventActive` chứa event | `SA/api/Ads.kt:247-249` |
-| `Ads.destroyByPlacement` / `Ads.dismissByPlacement` | huỷ ad + cache của placement / đóng ad đang hiện và dừng reload | `SA/api/Ads.kt:225-237` |
-
-## 1. Fullscreen có điều hướng (INTER, NATIVE_FULL_ACTIVITY)
-
-```kotlin
-Ads.show("<placement>", activity, callback = NavAdCallback { result ->
-    goNext()   // gọi cho cả Success và Failed: ad lỗi không được chặn luồng người dùng
-})
-```
-
-Thời điểm `onNav` do key `mode.navigate` quyết định, SDK không tự điều hướng (tra `mode.navigate` trong `tools/ai_agent_tools/data/ads_key_knowledge.json`).
-
-## 2. Reward / Reward Interstitial
-
-```kotlin
-Ads.show("<placement>", activity, callback = RewardAdCallback(applyForAnyAdFull = false) { result ->
-    when (result) {
-        is RewardResult.Success -> grantReward()
-        is RewardResult.Failed -> showNoReward()
-    }
-})
-```
-
-`applyForAnyAdFull = true` (mặc định) cho thưởng cả khi đóng ad mà không nhận reward (`SA/api/callback/AdsCallback.kt:194-199`). Chọn giá trị là **quyết định sản phẩm**, phải hỏi user.
-
-## 3. Inline: banner, native, collapsible
-
-```kotlin
-// Activity
-Ads.show("<placement>", this, AdTarget.AdView(binding.adContainer, lifecycle), object : AdsCallback {
-    override fun onAdFailed(placementId: String, error: AdError) { binding.adContainer.isVisible = false }
-})
-
-// Fragment: dùng lifecycle của VIEW, không phải của fragment
-Ads.show("<placement>", requireActivity(), AdTarget.AdView(binding.adContainer, viewLifecycleOwner.lifecycle))
-```
-
-- Mẫu thật: `app/src/main/java/com/android/hd/ads2026/test/BaseTestActivity.kt:79-84`.
-- SDK theo dõi lifecycle chủ view chỉ với collapsible và banner collapsible. Banner/native thường **không** theo dõi (`SA/presentation/presenter/InlinePresenter.kt:23-27`). Dọn ad khi màn hình chết thì theo cách app đang làm ở các màn khác; chưa có tiền lệ thì hỏi user.
-
-## 4. Inline trong danh sách (RecyclerView / Epoxy)
-
-Mẫu: `app/src/main/java/com/android/hd/ads2026/test/NativeTestActivity.kt:49-65`.
-- Gọi `Ads.show` lúc bind item quảng cáo, với container của chính item đó.
-- Trả placement khi unbind (`AdPlacementController.recyclePlacement`, `app/src/main/java/com/android/hd/ads2026/AdPlacementController.kt:131`). Đây là helper của app mẫu, không thuộc SDK.
-
-## 5. Preload theo event
-
-```kotlin
-Ads.dispatchEvent(activity, "<event>")   // event phải nằm trong preload.eventActive của adItem
-```
-
-- Mẫu: `app/src/main/java/com/android/hd/ads2026/test/BaseTestActivity.kt:87-92`.
-- `mode.show = SHOW_LOADED` thì show **chỉ** dùng ad đã preload; chưa có thì fail `LOAD:208`. Muốn load lúc show thì dùng `LOAD_AND_SHOW` (tra `mode.show` trong file tri thức).
-
-## 6. App Open khi quay lại app
-
-```kotlin
-// Application.onCreate, sau Ads.init
-// appOpenAllowed: cờ của app, chỉ bật sau callback consent và sau lần vào app đầu (splash).
-AppLifecycleMonitor(
-    onForeground = {
-        if (appOpenAllowed) {
-            Ads.config.getActivityProvider()?.getActivityOnTopNotAds()?.let { Ads.show("<app_open_placement>", it) }
-        }
-    },
-    onBackground = {},
-).register()
-```
-
-**Không bỏ guard:** `onForeground` chạy cả ở `ON_START` đầu tiên lúc mở app lạnh (`SA/api/lifecycle/AppLifecycleMonitor.kt:19-21`), tức trước khi consent ở Activity đầu kịp trả về. Không có guard thì App Open gửi request trước consent. App mẫu chặn tạm bằng thời gian (`app/src/main/java/com/android/hd/ads2026/MyApplication.kt:61`).
-
-- `AppLifecycleMonitor` chỉ chuyển `onStart`/`onStop` của `ProcessLifecycleOwner` (`SA/api/lifecycle/AppLifecycleMonitor.kt:9-29`). Mẫu đăng ký: `app/src/main/java/com/android/hd/ads2026/MyApplication.kt:58-72`.
-- Guard sau fullscreen (`appOpen.guardAfterFullscreenMs`) chặn App Open ngay sau khi đóng một fullscreen (`POLICY:108`, `SA/engine/rules/FullscreenRules.kt:74-97`).
-- Điều kiện thêm (màn splash, không show lần mở đầu…) là logic của app: theo cách app đang làm, chưa có thì hỏi user.