From a2f51bac2a2f7cbb9a79fa31990a9a2d5fd50e37 Mon Sep 17 00:00:00 2001
From: goboss <goboss@frontend03>
Date: Sat, 2 May 2026 22:09:50 +0000
Subject: [PATCH] ADS: document asgsl frequency-capping gotcha (8148
 popunder/vast bug)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Real-browser probe (playwright + Chromium headless) revealed bundle
expects `global_rr:<ts>` and `n:<ts>` fields in asgsl localStorage
to set _popRr / _vastRr cooldowns. New ASG account spot 514208 is
configured with shows_limit:1 without these timestamp fields, so:
- popunder fires every pageload
- _popRr never written → popActive=false always
- mode never transitions to vast → VAST SDK never loads

Resolution requires ASG admin to enable frequency-capping rotation
on the spot (на стороні юзера). Documented detection: check
localStorage.getItem('asgsl') for 'global_rr:' or 'n:' tokens.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 docs/ADS.md | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

diff --git a/docs/ADS.md b/docs/ADS.md
index 403d310..cfc9d80 100644
--- a/docs/ADS.md
+++ b/docs/ADS.md
@@ -169,10 +169,29 @@ tb.load_frame_baner_v2("//surstrom.com/api/spots/72437?p=1","#tb0",{...},{...});
 
 ### Cooldown management
 
-- ASG локальне сховище: `localStorage.asgsl` — pipe-separated `<spot_id>=<key>:<value>` записи. Ключ `global_rr` = "remaining ratio" (timestamp до якого spot у cooldown).
+- ASG локальне сховище: `localStorage.asgsl` — pipe-separated `<spot_id>=<key>:<value>` записи. Ключі що використовуються нашим bundle:
+  - `global_rr:<timestamp>` — `_readCooldowns` parse-ить це як cooldown end time
+  - `n:<timestamp>` — impression handler копіює це у `_popRr` / `_vastRr` cookies+LS
 - Дублюючі cookies: `_popRr`, `_vastRr`. Реплікуються з asgsl при impression event.
 - Декрипт пам'яті: дві ключові події з ASG — `asgPopunderImpression`, `asgInVideoImpression` — тригерять запис cooldown.
 
+### ⚠️ ASG spot config gotcha — frequency-capping mandatory
+
+**Bug 2026-05-02 (8148, after account recreation):** popunder spot 514208 у новому ASG account-і був налаштований з `shows_limit:1` без frequency-capping rotation. Симптоми:
+
+- popunder СПрацьовує (видно `asgPopunderImpression`)
+- Але `asgsl` локально вигляд: `<spot>=keep_looping:false,tabunder:false,uuid:...,noloop:true,shows_limit:1`
+- **Нема `n:<timestamp>`** → impression handler виходить без write `_popRr`
+- **Нема `global_rr:<timestamp>`** → `_readCooldowns` повертає `popActive=false`
+- → mode завжди "pop" → popunder fires кожен pageload → VAST SDK ніколи не loadиться
+
+**Fix у ASG admin** (на стороні юзера, не у нас):
+- Відкрити spot config → знайти "Global rotation" / "Frequency capping" / "Cooldown" / "Time-based capping" / "Show frequency"
+- Встановити, наприклад, "once per 2 hours per user" — це додасть `n:` / `global_rr:` поля в asgsl
+- **Те саме для VAST spot** — інакше після популярного pop firing, VAST mode triggered але cooldown поломаний
+
+**Як перевірити:** після popunder fire відкрий DevTools → `localStorage.getItem('asgsl')` → шукай `global_rr:` або `n:`. Якщо нема → не налаштовано.
+
 ### Mode decision (`AdCore._decide`)
 
 ```