Pomoc/Przewodniki proxy
Przewodniki proxy

Proxy dla Flowsery Analytics w Next.js

Kieruj Flowsery Analytics przez własną domenę w aplikacji Next.js, aby adblockery nie zakłócały śledzenia, a dane o odwiedzających były dokładne.

Pełne proxy składa się z dwóch kroków: rewrite (dzięki któremu tracker działa jako first-party i omija adblockery) oraz middleware (przekazuje prawdziwy adres IP odwiedzającego do backendu Flowsery). Same rewrites dostarczą zdarzenia, ale każdy odwiedzający będzie wyglądał, jakby pochodził z regionu twojego serwera, dlatego potrzebujesz obu elementów.

1. Skonfiguruj rewrites

Dodaj lub zaktualizuj plik next.config.js w katalogu głównym projektu:

JavaScript
module.exports = {
  async rewrites() {
    return [
      {
        source: '/js/main.js',
        destination: 'https://cdn.flowsery.com/main.js',
      },
      {
        source: '/api/track',
        destination: 'https://analytics.flowsery.com/analytics/events',
      },
      {
        source: '/:locale/api/track',
        destination: 'https://analytics.flowsery.com/analytics/events',
      },
    ];
  },
};

Jeśli twój projekt używa już ścieżki /api/track, wybierz inną i przekaż ją w atrybucie data-api skryptu trackera (np. data-api="/flowsery-events").

2. Przekaż prawdziwy adres IP odwiedzającego (middleware)

Rewrites w Next.js wykonują zapytanie serwer-serwer, więc znajdujący się dalej edge Cloudflare zastępuje cf-connecting-ip adresem IP Twojego serwera Next.js. Flowsery widzi wtedy każdego odwiedzającego jako „Twój serwer” i określa lokalizację na podstawie regionu hostingu.

Aby to naprawić, dodaj middleware, które odczyta prawdziwy adres IP odwiedzającego przy wejściu i zapisze go w niestandardowym nagłówku x-flowsery-real-ip. Ten nagłówek przechodzi przez proxy bez zmian, a backend Flowsery przedkłada go nad cf-connecting-ip, jeśli jest obecny.

Utwórz lub zaktualizuj plik middleware.ts w katalogu głównym projektu:

TypeScript
import { NextRequest, NextResponse } from 'next/server';
 
const TRACKING_PROXY_PATHS = /\/api\/track$/;
 
export default function middleware(request: NextRequest) {
  if (!TRACKING_PROXY_PATHS.test(request.nextUrl.pathname)) {
    return NextResponse.next();
  }
 
  const realIp = request.headers.get('cf-connecting-ip') || request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
 
  if (!realIp) return NextResponse.next();
 
  const forwardedHeaders = new Headers(request.headers);
  forwardedHeaders.set('x-flowsery-real-ip', realIp);
 
  return NextResponse.next({
    request: { headers: forwardedHeaders },
  });
}
 
export const config = {
  matcher: ['/api/track', '/:locale/api/track'],
};

Jeśli masz już middleware

Dwa elementy trzeba starannie połączyć:

1. Handler. Dla ścieżek /api/track najpierw wywołaj logikę proxy śledzenia, a dopiero potem przejdź do swojej dotychczasowej logiki:

TypeScript
export default function middleware(request: NextRequest) {
  // Runs for /api/track + /:locale/api/track. Returns a response only when
  // the path matches, otherwise returns NextResponse.next() so your existing
  // logic runs below.
  if (/\/api\/track$/.test(request.nextUrl.pathname)) {
    const realIp = request.headers.get('cf-connecting-ip') || request.headers.get('x-forwarded-for')?.split(',')[0]?.trim();
    if (realIp) {
      const headers = new Headers(request.headers);
      headers.set('x-flowsery-real-ip', realIp);
      return NextResponse.next({ request: { headers } });
    }
    return NextResponse.next();
  }
 
  // ...your existing middleware logic here (locale detection, auth, etc.)
}

2. Matcher. Większość middleware działającego na poziomie stron używa negatywnego lookaheadu, np. /((?!api/|_next/...).*), aby wykluczyć trasy API. Taki wzorzec wyklucza też /api/track, więc middleware nigdy nie uruchomi się dla ścieżki śledzenia. Rozszerz tablicę matcher, aby ponownie ją uwzględnić:

TypeScript
export const config = {
  matcher: [
    // Your existing page-level pattern, leave it alone.
    '/((?!api/|js/|_next/static|_next/image|favicon.ico|locales|ingest).*)',
 
    // Added so middleware also runs for the tracking proxy paths.
    '/api/track',
    '/:locale/api/track',
  ],
};

Kolejność nie ma znaczenia. Wpisy matchera działają jak alternatywa (OR): ścieżka uruchamia middleware, jeśli pasuje do dowolnego z nich. Trasy stron nadal pasują do twojego dotychczasowego wzorca, a /api/track trafia na nowy, jawny wpis i dociera do powyższego handlera proxy śledzenia.

3. Zmień tag skryptu

Skieruj skrypt na lokalną ścieżkę obsługiwaną przez proxy:

HTML
<script defer data-fl-website-id="flid_******" src="/js/main.js"></script>

4. Wdróż zmiany

Rewrite i middleware zaczną działać po wdrożeniu.

Sprawdzenie, czy wszystko działa

  1. Otwórz swoją stronę w zwykłej karcie przeglądarki.
  2. Otwórz DevTools → Network i przefiltruj po /api/track.
  3. Sprawdź, czy każde żądanie trafia do twojej domeny (a nie do analytics.flowsery.com).
  4. W panelu Flowsery sprawdź, czy kraje i miasta odwiedzających odpowiadają twoim odbiorcom (a nie regionowi hostingu).

Rozwiązywanie problemów

Wszyscy odwiedzający pochodzą z tej samej lokalizacji

Jeśli wszyscy odwiedzający mają jedną lokalizację, na przykład region twojego serwera, krok z middleware nie ustawia nagłówka x-flowsery-real-ip.

Najczęstsze przyczyny:

  • Matcher middleware nie obejmuje ścieżki śledzenia. Większość istniejących matcherów używa negatywnego lookaheadu, np. /((?!api/|...).*), który wyklucza /api/*. Dodaj /api/track (oraz /:locale/api/track, jeśli adresy URL mają prefiks języka) jako jawne wpisy w tablicy matcher.
  • Nagłówek trafił do odpowiedzi zamiast do żądania. Backend odczytuje nagłówki żądania, więc użyj NextResponse.next({ request: { headers } }), a nie response.headers.set(...).
  • Twoim dostawcą edge nie jest Cloudflare. Jeśli korzystasz z Vercel, Fly.io lub innego edge'a, odczytaj adres IP odwiedzającego z nagłówka tego dostawcy (x-real-ip, x-vercel-forwarded-for, fly-client-ip itp.).