feat: fix travel placement bug, add theme-based alternate icons, fix animated background crash

- Fix repeat-city travel placement: use stop indices instead of global city name matching so Follow Team trips with repeat cities show travel correctly - Add TravelPlacement helper and regression tests (7 tests) - Add alternate app icons for each theme, auto-switch on theme change - Fix index-out-of-range crash in AnimatedSportsBackground (19 configs, was iterating 20) - Add marketing video configs, engine, and new video components - Add docs and data exports Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-06 09:36:34 -06:00
parent fdcecafaa3
commit 8e937a5646
77 changed files with 143400 additions and 83 deletions
--- a/docs/codexMarketing.md
+++ b/docs/codexMarketing.md
@@ -0,0 +1,363 @@
+# SportsTime iOS Launch & Growth Plan (90 Days)
+
+Assumptions used for this plan:
+- You are pre-launch on TestFlight with no meaningful existing audience.
+- Budget is $500/month total.
+- You can ship product changes quickly.
+- US-only, iPhone-only, sports leagues are US-focused.
+- Pricing is currently `$0.99/month` and `$9.99/year` (strongly recommend testing higher price points in Month 2).
+
+Proposed 90-day targets (edit as needed):
+- Baseline: `12,000 installs`, `300 paid subscribers`, `D1 32%`, `D7 14%`, `D30 7%`.
+- Stretch: `30,000 installs`, `800 paid subscribers`, `D1 35%`, `D7 16%`, `D30 8%`.
+- 100k installs in 90 days is only realistic if a viral loop from sharing/polls lands hard; paid media alone cannot do this on $500/mo.
+
+## 1. Positioning & Messaging
+
+- Core hook: “Plan multi-game sports road trips in minutes, not spreadsheets.”
+- Positioning statement: SportsTime is the only iPhone app that combines real game schedules, route logic, and stadium tracking into one trip-planning flow.
+- Target audience psychology: sports fans with FOMO, completionist behavior (visit all stadiums), social bragging (share routes/progress), and “planning as entertainment” during downtime.
+- Why they install: they want an answer to “What games can I realistically hit in one trip?”.
+- Why they pay: unlimited saved trips, group planning/polls, and stadium progress tracking are “identity” features for serious fans.
+
+Main competitor set:
+- `Roadtrippers` and `Wanderlog` for generic road-trip planning.
+- `MLB Ballpark` for in-stadium check-in utility.
+- `StadiumTrack` / `Stadium Rover` / `Balltrip` for stadium/fan tracking or lightweight sports-trip planning.
+- `SeatGeek` as adjacent discovery/ticket competitor.
+
+Why SportsTime wins:
+- Sports-native planning modes (`by dates`, `by games`, `by route`, `follow team`, `by teams`) rather than generic POI routing.
+- Cross-league coverage in one planner.
+- Built-in “fan progression” layer (stadium tracking + achievements), not just itinerary.
+- Group poll collaboration tied to trip options.
+
+Tagline ideas:
+- “From Couch to Kickoff.”
+- “Build Your Ultimate Stadium Run.”
+- “Plan the Trip. Chase the Games.”
+- “See More Games. Drive Less.”
+- “The Road-Trip Brain for Sports Fans.”
+
+App Store subtitle ideas:
+- “Plan Multi-Game Road Trips”
+- “Sports Route + Stadium Tracker”
+- “Trip Planner for Sports Fans”
+- “Find Games, Build the Route”
+- “Road Trips for Game Days”
+
+## 2. Pre-Launch Plan (30-60 Days Before)
+
+Landing page strategy:
+- One CTA only: “Get your first 3-game route.”
+- Inputs on page: favorite team, home city, month, max driving hours/day, email.
+- Output: send a personalized sample itinerary by email within 24 hours.
+- Add 3 social proof blocks from TestFlight users and one short demo video.
+
+Waitlist strategy:
+- Segment by league interest and distance willingness.
+- Send weekly “Route Drop” emails: one weekend plan, one 5-day plan, one “follow-team” plan.
+- Use scarcity: “Founding 500 get lifetime Founder Badge in app + 1 free pro year.”
+
+Beta/TestFlight plan:
+- Recruit 150-250 testers with high intent from fan communities.
+- Use a structured mission each week: “Plan and save 1 trip” then “Share 1 trip card” then “Log 1 stadium visit.”
+- Track activation target: 60% of testers reach `trip_saved`.
+- Run 2 in-app surveys: after first trip save and after first week.
+
+Community building channels:
+- Reddit: `r/baseball`, `r/NBA`, `r/nfl`, `r/hockey`, `r/mls`, `r/wnba`, `r/NWSL`, `r/roadtrip`.
+- TikTok/Reels: 4-5 short videos/week, each showing real route scenarios.
+- X/Twitter: daily “Can this trip work?” route posts with screenshots.
+
+How to collect emails:
+- Website route generator.
+- “Free printable stadium checklist” gated download.
+- “Opening Week Route Pack” gated PDF.
+- QR code from social video overlays to waitlist page.
+
+How to seed early users:
+- DM 100 fan creators/podcasters with a custom route built for their team.
+- Offer “free pro for creators + audience code”.
+- Run “First 1,000 Founders” campaign with public counter.
+
+## 3. App Store Optimization (ASO)
+
+Keyword strategy:
+- Intent cluster A: `sports trip planner`, `stadium trip planner`, `game day trip`.
+- Intent cluster B: `road trip planner`, `multi stop route planner`, `travel itinerary`.
+- Intent cluster C: `MLB trip`, `NBA trip`, `NFL trip`, `NHL trip`, `MLS trip`.
+- Intent cluster D: `stadium tracker`, `ballpark tracker`, `sports bucket list`.
+
+Title/subtitle structure:
+- Title format: `Brand + core intent`.
+- Candidate title: `SportsTime: Stadium Trips`.
+- Candidate subtitle: `Plan Multi-Game Road Trips`.
+
+Screenshot strategy (8 screens):
+- 1: “Plan by dates, games, routes, or teams.”
+- 2: “See all games in your trip window.”
+- 3: “Get optimized route options with drive time.”
+- 4: “Compare itinerary options fast.”
+- 5: “Save trips and revisit anytime.”
+- 6: “Track stadiums visited across leagues.”
+- 7: “Plan with friends using trip polls.”
+- 8: “Share polished trip cards and PDFs.”
+
+Preview video plan:
+- Video A (15s): instant value, “from dates to route in seconds.”
+- Video B (30s): real scenario, “hit 3 games in 4 days.”
+- Video C (20s): stadium tracker + achievements + social sharing.
+
+Review/rating strategy for first 100 reviews:
+- Trigger `SKStoreReviewController` only after `trip_saved` + second successful session.
+- Do not prompt after errors or paywall rejection.
+- Send direct asks to top 100 TestFlight users with one-tap review deep link.
+- In-app “Founding User” card asking for review after user shares a route.
+
+Localization strategy:
+- English (US) first.
+- Spanish metadata next for US Hispanic market.
+- Localize title/subtitle/keywords/screenshots before localizing full app UI.
+
+## 4. Launch Week Strategy
+
+| Day | Objective | Tactics | KPI |
+|---|---|---|---|
+| Day 1 (Mon) | Final prep | Freeze build, finalize ASO assets, schedule manual release, set analytics dashboards, queue 7 short videos | Zero blocker bugs |
+| Day 2 (Tue) | Public launch burst | App Store live + Product Hunt launch + waitlist email blast + creator DMs (30) + ASA exact-match campaign start | Day-1 installs, CVR |
+| Day 3 (Wed) | Reddit credibility | Post 3 value-first route breakdowns (not promo spam), reply to comments for 4 hours, publish one “how I planned this trip” thread | Saves/comments/clicks |
+| Day 4 (Thu) | Short-form reach | Publish 3 TikToks/Reels showing team-specific route examples, CTA to free route planner | CTR to App Store |
+| Day 5 (Fri) | Press + podcasts | Send 50 personalized pitches to sports newsletters/podcasts/blogs with team-angle hooks and demo links | Replies/bookings |
+| Day 6 (Sat) | Community activation | Run “Weekend Stadium Challenge” with hashtag + share card template, repost user submissions | UGC count, shares |
+| Day 7 (Sun) | Conversion optimization | Analyze funnel drop-offs, ship onboarding/paywall copy fixes, rotate ad creatives, publish launch recap thread | Activation uplift |
+
+Product Hunt strategy:
+- Launch Tuesday 12:01am PT.
+- First comment must include one specific use case and roadmap.
+- Ask 25 close contacts to engage in first 4 hours.
+
+Reddit strategy:
+- 70% value content, 20% discussion, 10% product mention.
+- Post local/team-specific trip examples, not generic promo.
+
+TikTok strategy:
+- Repeatable content format: “Can you hit X games in Y days from [city]?”
+- One visual hook in first 1.5 seconds, route reveal by second 5.
+
+Influencer outreach:
+- Target micro-creators in sports travel/fan vlog niche (`5k-100k followers`).
+- Offer custom route build + 1-year pro for coverage.
+
+Press outreach:
+- Pitch angle by season moment (opening day, playoffs, rivalry weeks).
+- Focus on niche sports outlets first, then broader travel tech.
+
+Hacker News:
+- Use only if you pitch technical angle: route algorithm + schedule constraints.
+
+Paid ads in launch week:
+- Spend `$120` max in week 1 for signal collection.
+- Keep campaigns narrow and high-intent.
+
+## 5. Growth Engine (Post-Launch)
+
+Organic loops:
+- Poll invite loop: each poll invite sends a deep link; recipient installs to vote.
+- Share loop: route cards/PDFs include app watermark + CTA.
+- Progress loop: stadium milestones create social posts (“12/30 MLB parks completed”).
+
+Referral system:
+- Give 1 month Pro for every referred user who completes first `trip_saved`.
+- Cap at 12 months to avoid abuse.
+
+Viral features to prioritize:
+- Public “Team Trip Templates” share pages.
+- “Weekend Route Generator” for each league.
+- “Stadium Chase leaderboard” by city/team fandom.
+
+Content strategy:
+- Daily short route content tied to upcoming schedule windows.
+- Weekly newsletter: “Best trips this week from [major US cities].”
+
+SEO strategy:
+- Create indexed pages: `/routes/[team]/[month]/[origin-city]`.
+- Publish “best sports road trips by month” content with real route screenshots.
+
+Community building:
+- Launch a Discord with 3 channels only: `route-help`, `trip-recaps`, `feature-vote`.
+- Host weekly “route office hours”.
+
+Retention strategy:
+- Push notifications on intent:
+- Trigger if user planned but did not save in 24h.
+- Trigger when favorite team has dense game window.
+- Trigger when user is near unvisited stadium.
+- Email cadence:
+- Day 1: “Your first route + edit tips.”
+- Day 3: “3 trips you can do from your city.”
+- Day 10: “Track your first stadium visit.”
+
+## 6. Paid Acquisition Plan (If Budget > $0)
+
+Budget recommendation at `$500/month`:
+- Apple Search Ads: `$325`
+- TikTok Ads: `$125`
+- Meta Ads: `$50`
+- Creator seed spend: barter/free-pro only unless one creator clearly performs.
+
+Apple Search Ads strategy:
+- Campaign groups: brand, competitor, category, discovery.
+- Start exact-match with high intent keywords only.
+- Use CPT caps tightly; pause anything above target CPI by day 4.
+
+TikTok ads strategy:
+- Use native-style UGC clips, not polished promo ads.
+- Creative angles: “I planned this Yankees trip in 30 seconds”, “3 games, 4 days challenge”.
+
+Meta ads strategy:
+- Interest stack: league fans + road trips + travel planning.
+- Run one retargeting ad set once pixel audience exists.
+
+Creator partnerships:
+- Prioritize sports trip vloggers and fan podcasters.
+- Give creator-specific deep links and offer their audience 30-day pro.
+
+Expected CPI ranges (US, non-gaming guidance + practical inference):
+- Apple Search Ads: roughly `$3.5-$6.0` per install.
+- TikTok: roughly `$1.5-$4.0`.
+- Meta: roughly `$2.0-$6.0`.
+
+Testing plan:
+- 2-week sprints.
+- 3 creatives per channel minimum.
+- Kill rule: pause ad after `3x target CPI` with no activation.
+- Scale rule: increase 20% budget/day only on ad sets hitting activation and paywall conversion thresholds.
+
+## 7. Analytics & Tracking Setup
+
+Must-have tools:
+- Product analytics: `PostHog` or `Amplitude`.
+- Crash/perf: `Firebase Crashlytics`.
+- Subscription tracking: StoreKit transaction events + server-side receipt status.
+- Attribution at this budget: Apple Ads native attribution + SKAN/AdAttributionKit signals.
+
+North-star metric:
+- `Weekly Trip Saves (WTS)` and `Weekly Activated Users (WAU-Activated)`.
+
+Core funnel:
+- `install -> first_open -> onboarding_complete -> trip_options_generated -> trip_saved -> paywall_view -> purchase_success -> week1_return`.
+
+Event schema to implement now:
+- `app_first_open`
+- `onboarding_started`
+- `onboarding_completed`
+- `planning_mode_selected`
+- `sports_selected`
+- `date_range_set`
+- `regions_selected`
+- `games_loaded`
+- `trip_options_generated`
+- `trip_option_viewed`
+- `trip_saved`
+- `trip_shared`
+- `pdf_export_generated`
+- `paywall_viewed`
+- `paywall_cta_tapped`
+- `purchase_started`
+- `purchase_success`
+- `purchase_failed`
+- `subscription_renewed`
+- `subscription_canceled`
+- `poll_create_started`
+- `poll_created`
+- `poll_invite_sent`
+- `poll_vote_submitted`
+- `stadium_visit_logged`
+- `achievement_unlocked`
+- `push_opt_in_status_changed`
+- `push_opened`
+- `deeplink_opened`
+- `referral_accepted`
+
+Required event properties:
+- `league`, `planning_mode`, `trip_option_count`, `trip_distance`, `trip_days`, `origin_city`, `paywall_trigger`, `product_id`, `price`, `utm_source`, `creative_id`.
+
+Metrics to track weekly:
+- Install-to-activation rate.
+- Activation-to-paywall rate.
+- Paywall view-to-purchase rate.
+- D1/D7/D30 retention.
+- ARPPU, trial-to-paid (if trials added), refund rate.
+- LTV/CAC payback window by channel.
+
+## 8. 90-Day Execution Roadmap
+
+Week 1-2:
+- Ship analytics and event taxonomy.
+- Finalize ASO metadata and first 8 screenshots.
+- Build waitlist landing page and route-lead magnet.
+- Recruit first 150 TestFlight users.
+- Publish 10 short videos before launch day.
+
+Week 3-4:
+- Launch publicly.
+- Run launch week playbook.
+- Collect first 50 public reviews.
+- Ship onboarding and paywall copy improvements from funnel data.
+- Start weekly route newsletter.
+
+Month 2:
+- Release referral loop and creator deep links.
+- Add public route templates for SEO pages.
+- Run 2 pricing/paywall experiments.
+- Publish 20 additional short videos tied to schedule moments.
+- Scale only top-performing acquisition channel.
+
+Month 3:
+- Double down on best league-specific growth channel.
+- Launch “Stadium Challenge” campaign with leaderboard.
+- Expand metadata localization to Spanish (US-focused).
+- Add one retention feature tied to favorite teams and upcoming game clusters.
+- Prepare playoff-season campaign calendar.
+
+## 9. Aggressive Growth Ideas
+
+1. Build “Weekend Trip Generator” web tool that creates shareable route images instantly.
+2. Make first poll free (even on free tier) to maximize invite-based installs.
+3. Run “30 Stadiums in 90 Days” public challenge with weekly leaderboard.
+4. Auto-generate team-specific social content daily from schedule windows.
+5. Offer fan podcasters a custom route segment they can run each week.
+6. Launch “Founder handle” badges that appear on shared cards for status.
+7. Create local city route packs (“Best Chicago-based sports trips this month”).
+8. Ship one-tap “Share to Instagram Stories” templates for every saved trip.
+9. Partner with sports betting/travel newsletters for co-branded route drops.
+10. Build seasonal event pages around rivalry weeks and playoffs for search capture.
+
+## 10. Biggest Mistakes to Avoid
+
+- Keeping pricing too low for too long; it hurts perceived value and makes paid growth non-viable.
+- Gating every social loop behind paywall; you need free-tier virality before monetization pressure.
+- Launching without instrumentation; no event-level data means blind iteration.
+- Broad targeting (“all sports fans”) instead of high-intent segments by league/team/city.
+- Posting self-promo spam in Reddit communities; you will get blocked and lose your best channel.
+- Ignoring retention and over-focusing on top-of-funnel installs.
+- Shipping with schedule/timezone inaccuracies; trust is the product in planning apps.
+- Running too many channels at once as a solo founder; pick 2 organic channels + 1 paid channel.
+- Not building reusable creative systems; growth will stall if content production is ad hoc.
+- Delaying referral/deep-link loops; with $500/month budget, this is your real growth lever.
+
+## Sources
+
+- Wanderlog App Store listing: <https://apps.apple.com/us/app/wanderlog-travel-planner/id1476732439>
+- Roadtrippers App Store listing: <https://apps.apple.com/us/app/roadtrippers-trip-planner/id944060491>
+- Balltrip App listing: <https://apps.apple.com/us/app/balltrip-app/id1625957435>
+- StadiumTrack listing: <https://apps.apple.com/us/app/stadiumtrack/id6752205919>
+- Stadium Rover listing: <https://apps.apple.com/us/app/stadium-rover/id6744362780>
+- MLB Ballpark listing: <https://apps.apple.com/us/app/mlb-ballpark/id513135722>
+- SeatGeek listing: <https://apps.apple.com/us/app/seatgeek-buy-event-tickets/id582790430>
+- TripIt listing: <https://apps.apple.com/us/app/tripit-travel-planner/id311035142>
+- AppTweak Apple Ads benchmarks (US CPI reference): <https://www.apptweak.com/en/aso-blog/apple-ads-benchmarks>
+- AppsFlyer market trend references:
+  - <https://www.appsflyer.com/resources/reports/performance-index/>
+  - <https://www.appsflyer.com/resources/reports/top-5-data-trends-report/>