Files
obsidian-vault/work/projects/cpm-wake-init-detection-tech-design-2026-11-10.md
T

3.8 KiB

tags, updated, status
tags updated status
work
cpm
tech-design
pixel
web-extension
2026-11-11 draft

TD: Pixel Definition: CPM Wake Init Detection (macOS/iOS + embedded web extension)

Author: Alex M Reviewer: TBD Stakeholders: Michal, Konrad, Russell Project: CPM: root-cause the stuck embedded extension messaging (macOS/iOS)

Background & Requirements

The extension's background is unloaded when idle and woken when a page needs it. Failures after such a wake are the largest group of CPM failures with no fix: on macOS 1.214 they are 39% of all failures (0.68% of DAU), on iOS 7.244 22% (0.06% of DAU).

For one page, startup has these steps: the page script sends init; the background receives it; it reads the configuration; it reads the user setting from the app; it checks the site; it answers the page and sends the app a dashboard refresh. The app sees only the last step, so every failure looks the same: no answer.

We need to find where startup stops, without changing what the extension does for the page and without collecting URLs or persistent identifiers.

Problem Statement

For every tab that the permanent breakage metric reports as silent, record the furthest startup step the extension reported.

  1. After each step the extension sends the app a short notification (extension PR #3727). It does not wait for the app's reply.
  2. For each tab the app remembers the furthest step reached (app PR #8163). The notification goes to the tabs waiting on its page, like the dashboard responses: two tabs on one page both get it. A notification that arrives up to 2 seconds before its page commits in the app counts for that page: it travels through the extension, while the commit is seen by the app directly.
  3. When a tab is reported as silent, web_extension_cpm_breakage carries that step as a new parameter, last_stage:
last_stage What the app saw last
none no notification (the page script did not send init, the message did not reach the background, or the background did not run)
background_received the background got init, the configuration or storage read did not finish
config_read the configuration was read, the user setting did not arrive
settings_checked the user setting arrived, the site check did not finish
site_checked all checks finished, no answer reached the app
response_sent the background answered the page's init, no dashboard refresh followed
  1. Both sides are behind the cpmInitProgress subfeature of autoconsent in the remote privacy configuration. The app ignores the notifications while it is off. The extension learns the flag from the settings answer of an init and keeps it in session storage, so it sends no notification until the app enables them; the first init after the flag turns on sends the notifications from settings_checked on.
  2. These notifications and the parameter are temporary and are removed when the wake failures are fixed or the investigation is closed.

Testing

Unit tests in the app and in the extension.

Additional Considerations (if applicable)

  • Privacy: New parameter last_stage on web_extension_cpm_breakage: one of six fixed values.
  • Security: None.
  • Site Breakage: None.
  • Experimentation: None.
  • Operational: The cpmInitProgress subfeature of the autoconsent feature in the privacy configuration enables and disables the notifications; they stay off until the configuration lists it as enabled. Staged rollout to a percentage of users.
  • Localization / Internationalization: None.