Skip to content

Onboarding and backfill UX

When a user signs up for an app built on SweatStack, three things have to happen before the app is useful: account creation, wearable connection, and the backfill of historical data. The first two are fast: tens of seconds in total. The backfill takes longer: typically 1 minute per 50 to 100 hours of activity history. If your app relies on historical data, how you handle the wait during the backfill shapes the first impression of the app.

This guide is opinionated about what works in production. The short version: let users in immediately and show progress. Don't gate the first session on a complete backfill.

What you'll build

A first-session flow that:

  • Authenticates and connects a wearable in one step, through Sign in with SweatStack
  • Lets the user into the app immediately while the backfill runs in the background
  • Shows clear progress, so the user understands that more data is on the way
  • Reconciles correctly when the backfill finishes

The flow has three temporal phases:

   Sign up        Authorize         Backfill running        Backfill complete
   |              |                 |                       |
   v              v                 v                       v
+------+  +-------------+  +-------------------+  +-----------------------+
|      |  |  Sign in    |  |  First session:   |  |  Steady state:        |
| Your |  |  with       |  |  partial data,    |  |  full history,        |
| app  |  |  SweatStack |  |  progress shown   |  |  push-driven updates  |
|      |  |  (auth +    |  |                   |  |                       |
|      |  |  link)      |  |                   |  |                       |
+------+  +-------------+  +-------------------+  +-----------------------+
            ~30 seconds       ~1-2 minutes                ongoing

Phase 1: sign up + connect wearable

Use Sign in with SweatStack, so the user authenticates once, with their wearable account. SweatStack creates the SweatStack account in the background, and the OAuth2 flow returns to your app with an access token. For the user it's a single tap.

Recommended button copy: "Sign in with SweatStack". See the button guidance for the brand kit.

Phase 2: backfill, while the user explores

The moment sign-in completes, SweatStack starts ingesting from the wearable. Expect 50 to 100 hours of activity data in the first minute. The backfill starts with the most recent activities and works backward.

Within minutes after the user first arrives in your app, most of the data they will ever care about is already there. Do not block the first session on completion.

What to show in the first session

Fetch what is available and render it. The activities and longitudinal-data endpoints work during the backfill. They return what has been ingested so far.

Show a small, persistent indicator that more data is on the way. Something like:

Importing your training history...

Use the backfill status endpoint to follow the user's backfill.

Reconciling when more data arrives

Two reasonable patterns:

  • Pull on focus. Every time the app comes to the foreground, query the activity list again.
  • Push on event. Subscribe to the activity_created webhook and refresh the relevant view when it arrives. See the native mobile app guide for the webhook-to-push gateway pattern, or refresh server-side state directly if you have a backend.

Both work. Pull on focus is simpler and enough for most apps. Webhooks are smoother for an app that stays in the foreground.

Phase 3: steady state

Once the backfill is complete, a new activity arrives within seconds after the wearable syncs it. The same activity_created webhook fires for every new activity from then on, and the patterns above keep working unchanged. There's no separate "live" mode to switch to.

Common mistakes

  • Gating the first session on the full backfill. It adds a minute or two of "loading" before the user sees anything useful. Short, but unnecessary: most of the data they care about is in within seconds. Render what you have and reconcile.
  • Waiting for "all activities" before rendering. "All" is a moving target during the backfill. Render what you have, and reconcile as it grows.

Next steps