Add Mintegral playable checker
This commit is contained in:
155
TODO.md
Normal file
155
TODO.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# Mintegral Checker — TODO
|
||||
|
||||
## Task Overview
|
||||
|
||||
Build a local VS Code webview equivalent of the Mintegral PlayTurbo checker
|
||||
(`https://www.playturbo.com/review`). Validates a Mintegral playable ad ZIP against
|
||||
PlayTurbo requirements. Two check categories:
|
||||
|
||||
- **Static** — parse `index.html` + ZIP structure without running the ad.
|
||||
- **Runtime** — load the ad in a sandboxed `srcdoc` iframe, inject a monitoring stub,
|
||||
and detect whether lifecycle callbacks (`gameReady`, `gameEnd`, `gameStart`,
|
||||
`gameClose`, `install`) actually fire.
|
||||
|
||||
---
|
||||
|
||||
## Finished
|
||||
|
||||
- [x] Pure-Node ZIP parser (EOCD → Central Directory → Local File Headers, zlib DEFLATE)
|
||||
- [x] All 9 static checks:
|
||||
- HTML Requirements (charset, viewport, single-file)
|
||||
- CTA Method (`window.install` reference in scripts)
|
||||
- Game End / Game Ready / Game Start / Game Close (regex on scripts)
|
||||
- File Handling (no external URLs, base64 assets)
|
||||
- File Spec (ZIP ≤ 5 MB, single `index.html`)
|
||||
- Storage (no `localStorage.setItem` / `sessionStorage.setItem`)
|
||||
- [x] Device-frame simulator (phone mockup around `srcdoc` iframe)
|
||||
- [x] Event log panel showing runtime events as they fire
|
||||
- [x] Runtime timer with 60s timeout and per-check waiting badges
|
||||
- [x] `__ping__` handshake → "Simulator connected" in event log (confirms stub runs)
|
||||
- [x] Dual notification channels: polling `__hplMtgEvents` + `parent.__hplMtgNotify`
|
||||
- [x] `MW_INIT` interceptor (wraps `emitCheckData`, forces `_hasReview`/`_isPreview`)
|
||||
- [x] `window.postMessage` override (catches `previewer:gameReady` self-posts)
|
||||
- [x] `mkAccess` — `Object.defineProperty` accessor with undefined getter so AD's
|
||||
`typeof window.gameReady === 'undefined'` guard passes, setter wraps assignment
|
||||
- [x] Capture-phase `load` safety net — wraps any SDK function declarations that
|
||||
overwrote accessors, fires before `body.onload`
|
||||
- [x] Mute button UI (shows on ZIP load, hidden on reset, toggles Mute/Unmute label)
|
||||
- [x] Diagnostic lifecycle logging (`post-parse`, `DOMContentLoaded`, `load`,
|
||||
`load+500ms`, callback assignment/call traces)
|
||||
- [x] AudioContext construction proxy for mute/unmute of closure-owned engine audio
|
||||
|
||||
---
|
||||
|
||||
## Bugs
|
||||
|
||||
### 1. Callbacks never fire (critical, diagnostics added)
|
||||
|
||||
**Symptom:** Event log shows "Simulator connected" (`__ping__` fires) but no lifecycle
|
||||
events appear. The same ZIP passes all checks on the real PlayTurbo site.
|
||||
|
||||
**Root cause candidates (narrowed down but not confirmed):**
|
||||
|
||||
A. **`body.onload` vs capture `load` ordering on `window`** — When the event target is
|
||||
`window` itself, capture and bubble listeners both run at the "at target" phase in
|
||||
registration order. Our stub is in `<head>` and registers first, so it should fire
|
||||
before the body's `onload`. But this assumes no edge-case behaviour in VS Code's
|
||||
Chromium sandbox / srcdoc context.
|
||||
|
||||
B. **SDK function declaration closes over a local reference** — If the ad does:
|
||||
```js
|
||||
var gameReady = function() { ... };
|
||||
window.gameReady = gameReady;
|
||||
```
|
||||
and `body.onload="gameReady()"` resolves to the local var (via closure), then
|
||||
reassigning `window.gameReady` in our load-time wrapper has no effect.
|
||||
|
||||
C. **CSP in VS Code webview blocks stub execution silently** — The webview panel has
|
||||
an implicit CSP. The stub is injected into `srcdoc`; it might run in a restricted
|
||||
context that prevents property interception or `parent` access for later events (even
|
||||
though `__ping__` works because it runs synchronously at parse time).
|
||||
|
||||
D. **Ad calls `gameReady()` before load** — If the ad boots via DOMContentLoaded and
|
||||
calls `gameReady()` there (rather than body.onload), our load-event safety net fires
|
||||
too late. The `mkAccess` accessor should still catch it, but only if the ad assigns
|
||||
`window.gameReady` first.
|
||||
|
||||
**What's been added:**
|
||||
- Injected diagnostic logging for lifecycle function `typeof` at post-parse,
|
||||
DOMContentLoaded, load capture before/after wrapping, and 500 ms after load.
|
||||
- Logs callback assignment/wrapping and wrapper call paths to the event log.
|
||||
- Logs dynamic `document.createElement('script')` calls to help trace script injection.
|
||||
|
||||
**What's still needed if callbacks still do not fire:**
|
||||
- Check if the ad bundles `preview-util.js` inside `index.html` or references it
|
||||
externally (would fail file-handling check anyway).
|
||||
- Compare the diagnostic timeline against the real PlayTurbo execution path.
|
||||
|
||||
---
|
||||
|
||||
### 2. Mute button does nothing (fixed in monitor stub)
|
||||
|
||||
**Symptom:** Clicking Mute/Unmute changes the label but has no audible effect.
|
||||
|
||||
**Root cause:** The current approach searches `Object.keys(cw)` for an `AudioContext`
|
||||
instance. AudioContexts are almost always created in closures (inside Phaser or the ad
|
||||
IIFE) and are never assigned as window properties — `Object.keys` will never find them.
|
||||
`cw.Phaser.game.sound` also likely fails because Phaser stores the game instance
|
||||
internally, not at `window.Phaser.game`.
|
||||
|
||||
**Fix applied:**
|
||||
Intercepts `AudioContext`/`webkitAudioContext` construction in the monitoring stub,
|
||||
stores captured contexts/gain nodes on `window.__hplAudioContexts` and
|
||||
`window.__hplMasterGains`, and routes `ctx.destination` through a master gain when
|
||||
possible. The mute button now sets captured master gain values first, then falls back
|
||||
to suspending/resuming captured contexts and exposed Phaser/global game sound objects.
|
||||
|
||||
---
|
||||
|
||||
## Improvements / Nice-to-Have
|
||||
|
||||
- [ ] **Inject SDK alongside ad** — The real PlayTurbo checker loads `preview-util.js`
|
||||
next to the ad. Bundling (or downloading once) the 265 KB SDK and injecting it into
|
||||
the srcdoc would let `MW_INIT`/`emitCheckData` fire natively, which is the most
|
||||
reliable callback path and matches what the real checker does.
|
||||
|
||||
- [ ] **Diagnostic mode** — A "Debug" toggle that logs `typeof` of each lifecycle
|
||||
function at key moments (post-parse, DCL, load, 500ms after load) to the event log,
|
||||
making root-cause analysis faster.
|
||||
|
||||
- [ ] **Replay button** — Reload only the iframe (not the full ZIP re-parse) to retest
|
||||
without re-picking the file.
|
||||
|
||||
- [ ] **Portrait / landscape toggle** — Flip the device frame aspect ratio.
|
||||
|
||||
- [ ] **Multiple HTML entry points** — Some ZIPs have `playable.html` instead of
|
||||
`index.html`; add a fallback search.
|
||||
|
||||
- [ ] **Orientation lock detection** — Check for `screen.orientation.lock()` calls
|
||||
(Mintegral requires the ad to handle both orientations).
|
||||
|
||||
- [ ] **Version bump and changelog entry** — Once callbacks are working, bump to 0.1.8
|
||||
and add a changelog entry for the Mintegral Checker tool.
|
||||
|
||||
---
|
||||
|
||||
## Known Issues / Constraints
|
||||
|
||||
- VS Code `WebviewPanel` runs in a sandboxed Chromium process. `srcdoc` iframes are
|
||||
same-origin with the webview, so `parent` access works — but the webview's implicit
|
||||
CSP may still block certain APIs inside nested iframes.
|
||||
|
||||
- The `Object.defineProperty` accessor approach (`mkAccess`) is the only way to let the
|
||||
AD's `typeof window.X === 'undefined'` guard pass while still intercepting the
|
||||
assignment. Any early concrete assignment (even `undefined`) breaks the guard in some
|
||||
runtimes.
|
||||
|
||||
- SDK `function` declarations at brace-depth 0 are `[[DefineOwnProperty]]` calls at
|
||||
parse time; they overwrite our configurable accessors unconditionally. The load-time
|
||||
safety net is the only recovery path for that scenario.
|
||||
|
||||
- The `applyStaticResults` function sets `runtimeStatus = null` for lifecycle checks
|
||||
that already failed statically. `handleRuntimeEvent` only transitions
|
||||
`runtimeStatus === 'waiting'` → `'pass'`; it silently ignores `null`. This means a
|
||||
static-fail check can't be runtime-rescued via the direct lifecycle path (though the
|
||||
`handleSdkCheck` path does handle `null`). Intentional, but worth documenting.
|
||||
Reference in New Issue
Block a user