Drop in the script tag, trigger your first tracked event, and link signed-in users.

Getting Started with Streakfox

Create a program-backed streak in one pass: add the widget script, send a real event, and verify that streak state changed. Add signed-in identity once the basic event path works.

1) Create or open a program

In the dashboard create a project, then open Programs.
Pick the event key you want to count first, such as visit, lesson_complete, or deploy.
Copy the Project ID (also called siteKey; the widget uses it as data-project).
Add your site’s origin to Allowed Origins so CORS passes in production.

<script
  src="https://cdn.streakfox.com/widget.js"
  data-project="YOUR_PROJECT_ID"
  data-position="bottom-right"   
  data-theme="beige"
  data-event="visit"              
  async
></script>

Auto-mounts to <body>; no extra markup needed.
Common data attributes: data-event="visit|like|lesson_complete", data-theme="light|dark|beige", data-view="streak|milestone", data-hide-branding="true".

3) Trigger your first streak event

The widget fetches state when it mounts. A streak only advances when you send a streak interaction. After the script loads, trigger the event from your app code:

<script>
  (function ready(cb) {
    if (window.streak) return cb();
    setTimeout(() => ready(cb), 25);
  })(() => {
    window.streak('like'); // uses the widget config’s event when omitted
  });
</script>

If you omit the argument, window.streak() uses the widget’s configured event (defaults to visit).

For backend-owned actions, send the same event through the signed server endpoint instead:

curl -X POST https://api.streakfox.com/v1/server/e \
  -H "Content-Type: application/json" \
  -H "X-Streak-Server-Token: $STREAKFOX_SERVER_TOKEN" \
  -d '{
    "siteKey": "YOUR_PROJECT_ID",
    "userHash": "user_abc123",
    "event": "lesson_complete",
    "eventType": "streak_interaction",
    "source": "api"
  }'

4) (Optional) Link signed-in users with a short-lived token

Create a userHash on your server (e.g. sha256(userId + salt)).
Sign a short-lived token with your ALIAS_SIGNING_SECRET and send it to /v1/alias.

// server-side (Node example)
import crypto from 'node:crypto';

const secret = process.env.ALIAS_SIGNING_SECRET!;
function sign(payload: object) {
  const body = Buffer.from(JSON.stringify(payload)).toString('base64url');
  const sig = crypto.createHmac('sha256', secret).update(body).digest('base64url');
  return `${body}.${sig}`;
}

export function createAliasToken({ siteKey, anonymousId, userHash }: {
  siteKey: string;
  anonymousId: string;
  userHash: string;
}) {
  const now = Math.floor(Date.now() / 1000);
  return sign({ siteKey, anonymousId, userHash, iat: now, exp: now + 600 });
}

curl -X POST https://api.streakfox.com/v1/alias \
  -H "Content-Type: application/json" \
  -d '{"token":"<token-from-server>"}'

5) Verify it worked

Call the state endpoint with your project ID and user hash. You should see todayDone: true after an event.

curl "https://api.streakfox.com/v1/state?siteKey=YOUR_PROJECT_ID&userHash=USER_HASH&event=visit"

Next steps

Track custom actions: /docs/guides/action-based-streaks
Send backend or webhook events: /docs/api/events
Link users across devices: /docs/guides/connecting-users
Learn Programs: /docs/guides/programs

Quickstart

Getting Started with Streakfox

1) Create or open a program

2) Embed the widget (one line)

3) Trigger your first streak event

4) (Optional) Link signed-in users with a short-lived token

5) Verify it worked

On this page