Guides
Quickstart
Drop in the script tag, trigger your first streak event, and link signed-in users in minutes.
Getting Started with Streakfox
Ship a Duolingo-style streak in three steps: add the widget script, send your first event, and (optionally) attach logged-in users so their streak follows every device.
1) Grab your project ID
- In the dashboard create a project and copy the Project ID (we use it as
data-project). - Add your site’s origin to Allowed Origins so CORS passes in production.
2) Embed the widget (one line)
<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
After the script loads you can fire an action-based streak 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).
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_SECRETand 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 - Link users across devices:
/docs/guides/connecting-users - Explore the API:
/docs/api/overview