docs: web-to-app identity bridging investigation and proposal#4543
docs: web-to-app identity bridging investigation and proposal#4543devin-ai-integration[bot] wants to merge 3 commits intomainfrom
Conversation
✅ Deploy Preview for hyprnote-storybook canceled.
|
✅ Deploy Preview for hyprnote ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
There was a problem hiding this comment.
🚩 This is an internal investigation doc published as public developer documentation
This document reads as an internal investigation and proposal (analyzing current identity systems, discussing alternative approaches, proposing a phased rollout). It's being added to content/docs/developers/ which is the public-facing developer docs at char.com/docs/developers. Other docs in this directory are how-to guides (setup, env, login, deeplinks, etc.). This investigation/proposal may not be appropriate as permanent public documentation — it describes internal analytics plumbing and PostHog implementation details. Consider whether this belongs in the public docs or in an internal document/issue instead.
Was this helpful? React with 👍 or 👎 to provide feedback.
| @@ -0,0 +1,220 @@ | |||
| --- | |||
There was a problem hiding this comment.
🟡 Duplicate order number 13 collides with existing 13.languages.mdx
The new file 13.web-to-app-identity-bridging.mdx uses order prefix 13, which is already taken by 13.languages.mdx. The docs collection extracts the numeric prefix for ordering (apps/web/content-collections.ts:287-288) and sorts docs by this order (apps/web/src/routes/_view/docs/-structure.ts:48). Having two docs with order = 13 in the same section causes non-deterministic relative ordering between "Language Support" and "Web-to-App Identity Bridging" in the docs sidebar. The next available number would be 15 (since 14.bug-report.mdx exists) or 19 (since 18.release.mdx is the highest).
Prompt for agents
The file 13.web-to-app-identity-bridging.mdx uses the numeric prefix 13, which collides with the existing 13.languages.mdx. Both files are in apps/web/content/docs/developers/ and the docs collection (apps/web/content-collections.ts lines 287-288) extracts this prefix for ordering in the sidebar. Rename the file to use the next available number. Looking at existing files: 14 is taken (bug-report), 15 is unused but 16 and 17 and 18 are taken. Consider using 15 or 19 (next after 18.release.mdx).
Was this helpful? React with 👍 or 👎 to provide feedback.
| --- | ||
| title: "Web-to-App Identity Bridging" | ||
| section: "Developers" | ||
| description: "Investigation and proposal for connecting website visitor identity to desktop app installs" |
There was a problem hiding this comment.
🚩 Frontmatter uses description but docs schema only defines summary
The docs Zod schema at apps/web/content-collections.ts:253-257 defines summary: z.string().optional() but does not define a description field. This new file uses description in its frontmatter. However, this is the established convention — virtually every other doc in the content/docs/ directory also uses description rather than summary (only 2 of ~30+ docs use summary). Zod silently strips unrecognized keys, so the field is dropped without error. This is a pre-existing inconsistency, not introduced by this PR, but it means the description text is effectively unused by the content system.
Was this helpful? React with 👍 or 👎 to provide feedback.
✅ Deploy Preview for char-cli-web ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Co-Authored-By: John <john@hyprnote.com>
Co-Authored-By: John <john@hyprnote.com>
…lision with 13.languages.mdx Co-Authored-By: John <john@hyprnote.com>
a3a9f24 to
d7499d4
Compare
Summary
Adds a developer docs page (
apps/web/content/docs/developers/13.web-to-app-identity-bridging.mdx) that investigates why 86% of app installs are unattributed and proposes a solution for bridging PostHog identity between the website and the desktop app.The document covers:
posthog.init()) vs. desktop (machine fingerprint viahypr_host::fingerprint()), how$identifycalls link them at sign-in, and what events are tracked on each side.posthog.alias()andlocalStoragepersistence; Phase 2 adds a silent browser-based attribution link during onboarding that works without sign-in.This is investigation + proposal only — no implementation changes.
Updates since last revision
-->and<--arrow characters being parsed as JSX. Replaced with Unicode arrows (→/←). CI now passes.Review & Testing Checklist for Human
apps/web/src/routes/_view/callback/auth.tsx) and desktop auth handler (apps/desktop/src/auth/context.tsx) work as described — specifically that sign-in opens in the user's default browser and that the two$identifycalls merge browser → supabaseUserId ← machineFingerprint.char.com/link) before sign-in. Confirm this is feasible within the current onboarding flow without adding friction.localStorage-based approach and server-side attribution endpoint with 30-day TTL are acceptable from a privacy/compliance perspective.Notes
apps/web/content/docs/developers/alongside the existing analytics inventory doc (12.analytics.mdx).Link to Devin session: https://app.devin.ai/sessions/62368e7c5e134597918cd1df0d7148c1
Requested by: @ComputelessComputer