Connecting Users (Alias)

By default Streakfox tracks a visitor-id that lives in localStorage.
When that same person signs in to your product you probably want their hard-earned streak to follow them to every device.
This is done with a server-side call to the admin-only alias endpoint. The request links the current visitorId with your own user ID.

👉 You only need to call aliasUser() once per visitor ⇄ user pair. The operation is idempotent and duplicate calls are ignored.

1 Copy-paste integration (works in any site)

<!-- Embed the widget script anywhere in <body> -->
<script
  src="https://cdn.streakfox.com/widget.js"
  async
  data-project="<PROJECT_ID>"
  data-user="<!-- optional: USER_ID -->"
></script>

<!-- OPTIONAL: one-time alias helper (≈12 lines) -->
<script>
  (function () {
    function ready(cb) {
      if (window.streak) cb();
      else setTimeout(() => ready(cb), 50);
    }

    ready(() => {
      const userId = window.MY_APP?.currentUser?.id; // ← replace with your auth logic
      if (!userId) return;

      const flag = 'sd_alias_' + userId;
      if (localStorage.getItem(flag)) return; // already linked

      // Recommend handling aliasing server-side using your admin token.
      // Client-side aliasing is disabled for security.
      try {
        localStorage.setItem(flag, '1');
      } catch {}
    });
  })();
</script>

If the page already knows the USER_ID when it renders you can skip the helper and just set data-user directly.

2 React / Next.js (server-side)

Install the tiny SDK:

npm i @streakdev/web

Create a small server route (or API route) that calls the admin alias API using your server credentials:

// /app/api/streak/alias/route.ts
import { NextRequest, NextResponse } from 'next/server';
import { createClient } from '@streakdev/web';

export async function POST(req: NextRequest) {
  const { projectId, anonymousId, userHash } = await req.json();
  const client = createClient({
    baseUrl: process.env.STREAK_API,
    adminToken: process.env.STREAK_ADMIN_TOKEN,
  });
  await client.aliasUser({ projectId, anonymousId, userHash });
  return NextResponse.json({ ok: true });
}

Mount it once (e.g. in app/layout.tsx) after your auth provider:

<StreakAlias projectId={process.env.NEXT_PUBLIC_STREAK_PROJECT_ID!} />

And remember to pass the user id to the widget when you can:

<script
  src="https://cdn.streakfox.com/widget.js"
  async
  data-project={process.env.NEXT_PUBLIC_STREAK_PROJECT_ID}
  data-user={session?.user.id ?? ''}
/>

3 How it works under the hood

Before login – the browser gets a random visitorId (sd_visitor_id) and the server creates a record keyed by that id.
Alias call – you send the same visitorId + your userId to /alias.
After alias – every request automatically includes both ids. The backend merges them so streaks roam freely across devices.

Duplicate alias calls are safe – the server ignores them.

Troubleshooting

• CORS error? Make sure the domain of your site is added to Project → Settings → Allowed Origins in the Streakfox dashboard.
• visitorId missing? Some browsers block localStorage in third-party iframes. The SDK falls back to an in-memory id that lasts until the tab closes.

Need help? Join our Discord or email support@streakfox.com – we're happy to assist!

Connecting Users

Connecting Users (Alias)

1 Copy-paste integration (works in any site)

2 React / Next.js (server-side)

3 How it works under the hood

Troubleshooting

On this page