ai_ml_operations/monica_site
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Mint campaign UTM links through the piha.li shortener #9

New Issue
Closed
opened 2026-08-30 13:12:22 -07:00 by westfarn · 1 comment
westfarn commented 2026-08-30 13:12:22 -07:00
Owner
Copy Link
Copy Source

Campaign composer should mint tracked homepage links and register them with the standalone URL shortener so SMS/postcard QR get a short piha.li URL instead of a long query string.

Tracked UTM (composer)

  • Auto-insert a site link when composing a campaign. Do not make the realtor paste UTM params.
  • utm_source=monica
  • utm_medium=email|sms|postcard (channel)
  • utm_campaign = hyphenated campaign name
  • Email: HTML <a> with visible host label (MKDRealtor.com)
  • SMS: plain-text URL in the body (phones cannot render HTML links; preview can linkify)
  • Postcard: QR of the tracked URL for copy/download into the postcard designer

Shortener

Service: url_shortening_service (API.md).

  • Mint POST /api/links/ on the API host, never on the short domain.
  • Public short URLs: https://piha.li/<code> (prod), https://beta.piha.li/<code> (beta).
  • Auth: Authorization: Bearer monica:<secret>.
  • Put the full UTM query on target_url before mint. Use campaign UUID as external_ref (idempotent).
  • Portal JSON endpoint for live composer (server-to-server only; browser must not call the shortener).
  • Empty shortener env (local) → fall back to the long UTM URL. Do not fail compose.

Secrets (control node, not git)

Caller — ~/Documents/secrets/monica_site/:

# prod (monica_site_prod.env)
SHORTENER_BASE_URL=https://shortener.aimloperations.com
SHORTENER_API_TOKEN=monica:<secret>

# beta (monica_site_beta.env)
SHORTENER_BASE_URL=https://shortener-beta.aimloperations.com
SHORTENER_API_TOKEN=monica:<beta-secret>

Operator — ~/Documents/secrets/url_shortening_service/ (same secret, named token):

SHORTENER_API_TOKENS=monica:<secret>
SHORT_ALLOWED_HOSTS=mkdrealtor.com,aimloperations.com

Prod PUBLIC_SHORT_URL / SHORT_DOMAIN should be piha.li (not the API hostname). Beta: beta.piha.li.

Generate: python -c "import secrets; print(secrets.token_urlsafe(32))"

Acceptance

  • Email/SMS drafts get a tracked link without manual paste
  • SMS + postcard QR use piha.li / beta.piha.li when shortener env is set
  • Token only in secret env files
  • Unconfigured shortener still composes with long UTM URLs
  • Tests cover mint + fallback
Campaign composer should mint tracked homepage links and register them with the standalone URL shortener so SMS/postcard QR get a short `piha.li` URL instead of a long query string. ## Tracked UTM (composer) - Auto-insert a site link when composing a campaign. Do not make the realtor paste UTM params. - `utm_source=monica` - `utm_medium=email|sms|postcard` (channel) - `utm_campaign` = hyphenated campaign name - Email: HTML `<a>` with visible host label (`MKDRealtor.com`) - SMS: plain-text URL in the body (phones cannot render HTML links; preview can linkify) - Postcard: QR of the tracked URL for copy/download into the postcard designer ## Shortener Service: [url_shortening_service](https://git.aimloperations.com/ai_ml_operations/url_shortening_service) ([API.md](https://git.aimloperations.com/ai_ml_operations/url_shortening_service/src/branch/master/API.md)). - Mint `POST /api/links/` on the **API host**, never on the short domain. - Public short URLs: `https://piha.li/<code>` (prod), `https://beta.piha.li/<code>` (beta). - Auth: `Authorization: Bearer monica:<secret>`. - Put the full UTM query on `target_url` **before** mint. Use campaign UUID as `external_ref` (idempotent). - Portal JSON endpoint for live composer (server-to-server only; browser must not call the shortener). - Empty shortener env (local) → fall back to the long UTM URL. Do not fail compose. ## Secrets (control node, not git) **Caller** — `~/Documents/secrets/monica_site/`: ``` # prod (monica_site_prod.env) SHORTENER_BASE_URL=https://shortener.aimloperations.com SHORTENER_API_TOKEN=monica:<secret> # beta (monica_site_beta.env) SHORTENER_BASE_URL=https://shortener-beta.aimloperations.com SHORTENER_API_TOKEN=monica:<beta-secret> ``` **Operator** — `~/Documents/secrets/url_shortening_service/` (same secret, named token): ``` SHORTENER_API_TOKENS=monica:<secret> SHORT_ALLOWED_HOSTS=mkdrealtor.com,aimloperations.com ``` Prod `PUBLIC_SHORT_URL` / `SHORT_DOMAIN` should be `piha.li` (not the API hostname). Beta: `beta.piha.li`. Generate: `python -c "import secrets; print(secrets.token_urlsafe(32))"` ## Acceptance - [ ] Email/SMS drafts get a tracked link without manual paste - [ ] SMS + postcard QR use `piha.li` / `beta.piha.li` when shortener env is set - [ ] Token only in secret env files - [ ] Unconfigured shortener still composes with long UTM URLs - [ ] Tests cover mint + fallback
westfarn commented 2026-08-30 13:18:26 -07:00
Author
Owner
Copy Link
Copy Source

Template port ticket: westfarn/web_django_template#3

Template port ticket: https://git.aimloperations.com/westfarn/web_django_template/issues/3
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
twestfall westfarn (Ryan Westfall)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ai_ml_operations/monica_site#9