Streaks

Streaks track consecutive user engagement over time. Define a qualifying event (like app_open or workout_completed), and Amba automatically tracks current count, longest count, and streak status.

How it works

1. Admin defines a streak definition with a qualifying event and period
2. When a user tracks the qualifying event, their streak is automatically updated
3. If the user misses a period, the streak resets (unless a grace period or freeze is configured)
4. Streak evaluation also runs daily in the background to catch broken streaks

SDK usage

Get user's streaks

const streaks = await client.streaks.getAll();
// Returns all streak states with definitions

Each streak includes:

{
  current_count: 7,
  longest_count: 14,
  last_qualified_at: "2025-01-14T10:30:00Z",
  status: "active",
  streak_definitions: {
    name: "Daily Workout",
    qualifying_event: "workout_completed",
    period: "daily"
  }
}

Qualify a streak manually

// Usually automatic via event tracking, but you can also qualify directly:
await client.streaks.qualify('streak_def_xxx');

Automatic qualification

When you track an event that matches a streak's qualifying_event, the streak is automatically qualified:

// This both tracks the event AND qualifies the "Daily Workout" streak
await client.track('workout_completed', { duration: 30 });

Streak mechanics

Period

• daily — user must qualify once per calendar day
• weekly — user must qualify once per calendar week

Grace period

Set grace_period_hours to give users extra time before their streak breaks. For example, a 6-hour grace period means the user has until 6 AM the next day.

Streak freezes

When freeze_enabled is true, users can freeze their streak to prevent it from breaking. max_freezes controls how many freezes a user can hold at once.

Shields (freezes)

In partner-facing copy we call freezes "shields" — same field on the wire (freezes_remaining), different word for the user. A streak with 1 shield that misses its qualifying period is automatically converted from active to frozen instead of broken, and freezes_remaining is decremented by 1. The streak's current_count is preserved — never punish a missed day with a red number; show "your streak is safe" copy instead.

Field semantics

Auto-grant rule

Set freezes_per_n_events = 5, max_freezes = 2 to get the partner spec verbatim: every 5 completed missions grants the user 1 shield, capped at 2 concurrent shields.

await admin.streaks.create({
  name: 'Daily Workout',
  qualifying_event: 'workout_completed',
  period: 'daily',
  freeze_enabled: true,
  max_freezes: 2,
  freezes_per_n_events: 5,
});

The grant fires on the increment that crosses the threshold (i.e. when current_count % freezes_per_n_events === 0). Resets and restarts do NOT grant a shield.

Shield consumption emits streak_shielded

When the daily streak-evaluation workflow finds a streak that missed its window AND freezes_remaining > 0, the row flips to frozen, freezes_remaining is decremented, and an engagement event is emitted:

{
  "event_name": "streak_shielded",
  "properties": {
    "streak_id": "us_…",
    "streak_definition_id": "sd_…",
    "freezes_remaining_after": 0
  }
}

Use this event to render in-app "your streak is safe" copy or to drive a re-engagement push. The same row also gets a streak_events audit entry with event_type='freeze' so the admin user-detail dump renders the full timeline.

Admin grant endpoint

POST /admin/projects/:projectId/users/:userId/streaks/:streakDefinitionId/grant-shield
Body: { count?: number }   // default 1

Bumps user_streaks.freezes_remaining by count, clamped at max_freezes. Returns the updated row. 404 if no user_streaks row exists for the (user, definition) pair — the streak workflow lazily-creates that row on the first qualifying event, so the user must have at least one event before you can grant.

Admin API reference

Client API reference

POST /client/streaks/:id/qualify

Records a qualifying event for a streak. Handles:

• Already qualified today (returns current state, no-op)
• Consecutive day (increments count)
• Broken streak (resets to 1)

Response:

{
  "data": {
    "id": "uuid",
    "current_count": 8,
    "longest_count": 14,
    "last_qualified_at": "2025-01-15T10:30:00Z",
    "status": "active",
    "current_period_start": "2025-01-08"
  }
}

MCP tools

Example

Agent: "Create a daily login streak with a 6-hour grace period"

amba_create_streak({
  project_id: "proj_xxx",
  name: "Daily Login",
  qualifying_event: "app_open",
  period: "daily",
  grace_period_hours: 6,
  freeze_enabled: true,
  max_freezes: 2
})

Reading streaks in Expo

import { useEffect, useState } from 'react';
import { Amba } from '@layers/amba-expo';
 
function StreakCard() {
  const [streaks, setStreaks] = useState<Awaited<ReturnType<typeof Amba.streaks.getAll>>>([]);
 
  useEffect(() => {
    Amba.streaks.getAll().then(setStreaks);
  }, []);
 
  const daily = streaks.find((s) => s.streak_id === 'daily_login');
 
  return (
    <View>
      <Text>Current streak: {daily?.current_count ?? 0} days</Text>
      <Text>Longest streak: {daily?.longest_count ?? 0} days</Text>
    </View>
  );
}

Database tables