Skip to content

feat(install): carry campaign attribution through setup - #638

Merged
lefarcen merged 7 commits into
mainfrom
feat/install-attribution
Nov 19, 2026
Merged

lefarcen merged 7 commits into
mainfrom
feat/install-attribution

Conversation

@open-design-crew

@open-design-crew open-design-crew Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Why

ProductHunt and other campaign links currently lose their source before a user reaches the OpenMotion installer. The existing landing attribution can preserve a visit locally, but the current OpenMotion main branch has no supported installer parameter or guide Worker to carry that source into the installed runtime.

This adds a small, opt-in attribution path that keeps untagged installs and upgrades unchanged while allowing campaign cohorts to be measured through the existing installation identity.

What changed

  • Add a Cloudflare Worker under workers/install-guide/ that reads the stable or DEV guide from the existing R2 bucket and injects a validated --utm-source only into supported setup commands when the guide marker is present.
  • Add --utm-source to the npm installer. Explicit installs update only the saved source; untagged upgrades retain the existing source and installation ID.
  • Carry the current source into both utm_source and od_utm_source on subsequent OpenMotion events, and record installer start and successful installer events with a bounded host category.
  • Add deployment and measurement guidance covering the ProductHunt funnel, including the boundary that paste cannot be observed directly across apps and seven-day retention is a cohort query.
  • Include the attribution helper in the packaged application and add Worker/installer regression tests.

Validation

  • npm run check
  • npm run typecheck:backend
  • Worker and tracking tests: 26 passed after the Studio build
  • Installer funnel test: installation_started and installation_result attribution passed
  • Installer attribution test: passed
  • Installation guide and public Skill tests: 22 passed
  • git diff --check

The Worker is not deployed by this PR. The checked-in Wrangler route enables the existing test host first; the production host should be added after the stable guide contains the marker and the test URL is verified.

Surface area

  • Installer / npm package
  • Tracking schema
  • Documentation
  • Cloudflare Worker source and deployment config
  • Tests
  • Studio UI
  • MCP tool schema

Review follow-up

  • Confirm the test Worker deployment and response with ?utm_source=producthunt.
  • Add the production route only after stable guide verification.

@open-design-crew
open-design-crew Bot requested a review from qd1993102 November 19, 2026 04:19
@open-design-crew

Copy link
Copy Markdown
Contributor Author

Live verification before this PR:

  • https://open-design.ai/motion/install.md currently returns 404; the production Worker route is not active.
  • https://open-design.powerformer.net/motion/install.md returns 200 through the existing test Worker.
  • The direct and ?utm_source=producthunt test responses are byte-identical because the currently published R2 DEV guide predates the attribution marker and installer flag.

This PR adds the missing marker to the maintained guide source, carries the installer flag into the existing installation identity, and includes the Worker route/config. After merge and the next candidate/stable guide publication, deploy the test Worker, verify injection, then enable the production route.

@lefarcen
lefarcen requested a review from nettee November 19, 2026 04:21
@lefarcen lefarcen added size/M Medium change: 100-299 lines risk/medium Medium risk change type/feature Feature or new user-facing capability labels Nov 19, 2026
@lefarcen

Copy link
Copy Markdown
Contributor

Heads-up: PR #263 is also open for the same campaign-linked install attribution work, with overlapping installer, tracking, Worker, and regression-test files. Since both PRs are from the same contributor, would you like to consolidate them into one current branch? The maintainer team can then review a single integration result.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Fixed in 4ce682ad: the distribution scan rejected two internal Powerformer URL literals in the new docs/test. The Worker test now uses the public R2 URL, and deployment docs refer to the configured test route without embedding an internal domain. This was a release-scan policy failure, not an attribution logic failure.

@open-design-crew

Copy link
Copy Markdown
Contributor Author

Follow-up 232c9fd8 adds the missing funnel boundary: the installer now records installation_started before setup completion and installation_result after successful registration, while preserving the same source and installation ID. The existing landing page owns visit/copy events; OpenMotion owns install/create/preview/export and seven-day cohort measurement.

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Attribution plumbing is coherent end to end: the Worker marker gate, --utm-source parsing, identity update and sender fields line up, and the new Worker/installer tests pass plus a manual transform of docs/install.md produces the expected four command rows. Three fixes are worth making before this data is relied on: where the installation events are emitted in the setup sequence, coverage of the public /motion/install.md mapping, and the tracking contract docs that still describe this work as unimplemented.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Comment thread scripts/npm-installer.mjs Resolved
Comment thread workers/install-guide/index.ts Resolved
Comment thread tracking/events.ts Resolved

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@app/open-design-crew

Thanks for the careful follow-up here — moving recordInstallationStart ahead of plan.register() is the right shape for the funnel: a failed host registration now still reports the attributed start, while installation_result stays tied to registration success.

Repair-frontier verification for 232c9fd8..2990d275:

  • The installer reorder is the only change since the previously reviewed head.
  • saveInstallationSource runs before createAppTracking, so the source getter in shared/tracking.ts sees the explicit --utm-source on both events.
  • Attribution failures remain non-fatal: each dynamic import/tracking block is caught independently and registration proceeds.
  • npm run check, tests/install-attribution-worker.test.ts, and the full tests/npm-installer.test.ts suite pass, including the explicit-source/untagged-upgrade test.

Appreciate the focused fix and the clear end-to-end write-up in docs/install-attribution.md — this reads well.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@app/open-design-crew Reviewed the repair delta from 232c9fd to 2990d27. Moving recordInstallationStart ahead of plan.register() closes the ordering gap: attribution is persisted before any host-started MCP event can create or read the installation identity, and the untagged-upgrade preservation test still passes. I also re-ran the attribution Worker test and the full npm-installer test file locally; both are green, and the two earlier fix commits address the release-link and event-ordering feedback.

One deployment-config issue is attached inline: the new Worker's Wrangler account id is truncated, so the documented deploy command cannot resolve the account. The rest of the repair frontier looks addressed.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Comment thread workers/install-guide/wrangler.toml Resolved
@lefarcen
lefarcen requested a review from qd1993102 November 19, 2026 04:52

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One blocking packaging regression in the new early installation_started path; the inline comment carries the detail. The Worker host mapping and the corrected 32-character account id check out, and the moved installation_result now waits for onboarding persistence and public Skill installation as documented. The prior target areas are addressed: start no longer waits for host registration and the account id is complete.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

Comment thread scripts/npm-installer.mjs Resolved
@lefarcen
lefarcen requested a review from qd1993102 November 19, 2026 05:10

@qd1993102 qd1993102 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@app/open-design-crew

Repair-frontier review at 70cc62f: the delta since c9af9e6 is limited to scripts/npm-installer.mjs, and it resolves the remaining gap in the attribution path.

What changed: attribution is now loaded from the extracted application root (appRoot/shared/install-attribution.ts) after the .npm-install.json identity checks, instead of resolving ../shared/install-attribution.ts against the published installer package, which only ships scripts/. The single imported module is reused for the closing recordInstallation call, so start and result events share one implementation.

Verification I ran:

  • node --experimental-strip-types --test tests/npm-installer.test.ts — 43 pass, including setup records an explicit attribution source and preserves it on untagged upgrades (source saved, untagged upgrade preserves it, explicit new source updates only utm_source and keeps installation_id).
  • node --experimental-strip-types --test tests/install-attribution-worker.test.ts — 2 pass.
  • Packaging check by inspection: scripts/distribution.ts includes shared/install-attribution.ts explicitly and walks shared/ plus the explicit tracking/*.ts entries, so the app-root import resolves in package-built installs while the installer tarball does not need to carry it.

The fixture also now copies the real attribution/tracking modules into the fake application, so the test exercises the installed layout rather than the source checkout. Small, well-shaped fix with coverage that matches the bug — thanks for the careful follow-through. CI on this head is green.

🔁 Powered by Looper · runner=reviewer · agent=omp · An autonomous AI dev team for your GitHub repos.

@lefarcen
lefarcen merged commit 58812fe into main Nov 19, 2026
23 of 25 checks passed
@lefarcen
lefarcen deleted the feat/install-attribution branch November 19, 2026 05:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk/medium Medium risk change size/M Medium change: 100-299 lines type/feature Feature or new user-facing capability

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants