Skip to content

docs(sdk-spec): document optional appToken for Cloud install scoping#25

Merged
onamfc merged 1 commit intomainfrom
docs/sdk-spec-app-token
May 4, 2026
Merged

docs(sdk-spec): document optional appToken for Cloud install scoping#25
onamfc merged 1 commit intomainfrom
docs/sdk-spec-app-token

Conversation

@onamfc
Copy link
Copy Markdown
Member

@onamfc onamfc commented May 4, 2026

Companion to #24 (1.15.0 release) and the four SDK PRs.

`SDK_SPEC.md` is the canonical contract that contributors building new LinkForty SDKs read first. Today it doesn't mention `appToken` — so any new SDK (community or otherwise) would skip it and customers using that SDK with Cloud would silently lose organic-install attribution.

What changed

  • Section 2 (Deferred Deep Linking) — new "App token (Cloud only)" sub-section explaining:
    • Where to find the token (Cloud Dashboard → Workspace Settings)
    • Format (`at_<32 hex>`) and the public-token safety model
    • Self-hosted Core ignores the field
    • Attribution behavior with vs. without a token
    • Example install request body
  • Section 11 (Configuration) — adds `App token` row to the Optional config table.
  • API Endpoints Reference — notes `POST /api/sdk/v1/install` body accepts optional `appToken`.

The four official SDKs (RN, Expo, iOS, Android) already implement this in their open PRs.

Out of scope

Test plan

  • Read Section 2 → "App token (Cloud only)" — checks the spec is internally consistent
  • Verify Optional configuration table renders and the in-page link to `#app-token-cloud-only` resolves
  • Confirm API Endpoints Reference table reads cleanly

Adds the appToken config field that was shipped in v1.15.0 (#24) to the
canonical SDK specification, so contributors building new SDKs include
it in their install request body.

Updates:
- Section 2 (Deferred Deep Linking): new "App token (Cloud only)" sub-section
  explaining where to find it, the at_<32 hex> format, the public-token
  safety model, self-hosted Core ignoring the field, and the 'organic-only'
  attribution gap when omitted. Mirrors the example install body.
- Section 11 (Configuration): adds App token row to the Optional config table.
- API Endpoints Reference: notes that POST /api/sdk/v1/install accepts the
  optional appToken field for Cloud workspace scoping.

The four official SDKs (RN, Expo, iOS, Android) already implement this in
their open PRs — this brings the spec in sync.
@codecov
Copy link
Copy Markdown

codecov Bot commented May 4, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@onamfc onamfc merged commit 9bf399c into main May 4, 2026
12 of 13 checks passed
@onamfc onamfc deleted the docs/sdk-spec-app-token branch May 4, 2026 22:55
@github-actions github-actions Bot locked and limited conversation to collaborators May 4, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant