Откуда пришли пользователи: first-touch attribution для NestJS + React + Telegram Mini App в 100 строк кода

SELECT acquisition_source, COUNT(*)
  FROM 
  WHERE created_at > NOW() - INTERVAL '7 days'
  GROUP BY 1
  ORDER BY 2 DESC;

// apps/web/src/lib/acquisitionSource.ts
  const STORAGE_KEY = 'speakwithai.acquisition_source';
  const MAX_LEN = 128;
  function buildSourceString(params: URLSearchParams): string | null {
    // Telegram Mini App в браузере (fallback) — пишем как tg:
    const tgStart = params.get('tgWebAppStartParam');
    if (tgStart) return `tg:${tgStart}`.slice(0, MAX_LEN);
    // Обычный веб — UTM
    const utmSource = params.get('utm_source');
    if (!utmSource) return null;
    const parts = [
      utmSource,
      params.get('utm_campaign') ?? '',
      params.get('utm_content') ?? '',
    ];
    while (parts.length > 1 && parts[parts.length - 1] === '') parts.pop();
    return `web:${parts.join('/')}`.slice(0, MAX_LEN);
  }
  export function captureAndStoreSource(): void {
    try {
      if (localStorage.getItem(STORAGE_KEY)) return; // first-touch
      const source = buildSourceString(
        new URLSearchParams(window.location.search),
      );
      if (source) localStorage.setItem(STORAGE_KEY, source);
    } catch {
      // localStorage может быть отключён (Safari private) — пропускаем
    }
  }
  export function getStoredSource(): string | null {
    try {
      return localStorage.getItem(STORAGE_KEY);
    } catch {
      return null;
    }
  }

// apps/web/src/main.tsx
  import { captureAndStoreSource } from './lib/acquisitionSource';
  captureAndStoreSource();
  createRoot(document.getElementById('root')!).render();
  Дальше при регистрации добавляем поле source в DTO:
  const { accessToken } = await registerApi({
    name,
    email,
    password,
    agreementsVersion: AGREEMENTS_VERSION,
    source: getStoredSource() ?? undefined,
  });

public async up(qr: QueryRunner): Promise {
    await qr.query(`
      ALTER TABLE 
        ADD COLUMN IF NOT EXISTS acquisition_source VARCHAR(128) NULL;
    `);
  }
  public async down(qr: QueryRunner): Promise {
    await qr.query(`
      ALTER TABLE  DROP COLUMN IF EXISTS acquisition_source;
    `);
  }

function sanitizeSource(raw: string | undefined | null): string | null {
    if (!raw) return null;
    const trimmed = raw.trim();
    if (!trimmed) return null;
    return trimmed.slice(0, 128);
  }
  // В AuthService.register:
  await this.usersService.create({
    email: dto.email,
    passwordHash,
    name: dto.name,
    agreementsAcceptedAt: new Date(),
    agreementsVersion: dto.agreementsVersion,
    acquisitionSource: sanitizeSource(dto.source),
  });

verifyInitData(initData: string): { user: TelegramUser; startParam: string |
  null } {
    // ...та же валидация HMAC, что была раньше...
    const params = new URLSearchParams(initData);
    // ... существующая логика проверки подписи ...
    const userJson = params.get('user');
    const user: TelegramUser = JSON.parse(userJson);
    const rawStart = params.get('start_param');
    const startParam =
      rawStart && rawStart.length > 0 && rawStart.length <= 64
        ? rawStart
        : null;
    return { user, startParam };
  }

async loginWithTelegram(initData: string) {
    const { user: tgUser, startParam } =
  this.telegramAuth.verifyInitData(initData);
    const telegramId = String(tgUser.id);
    let user = await this.usersService.findByTelegramId(telegramId);
    if (!user) {
      const source = startParam ? `tg:${startParam}` : null;
      user = await this.usersService.create({
        email: `tg_${telegramId}@demo.speakwithai.pro`,
        name: tgUser.first_name,
        telegramId,
        isDemoUser: true,
        acquisitionSource: source, // ← здесь
      });
    }
    return this.generateTokens(user.id, user.email);
  }

• localStorage недоступен (Safari private mode, старые WebView) Падать нельзя. Все обращения к localStorage в try/catch, возвращаем null. Источник просто не запишется — это не критично.
  
• Возвращающийся пользователь с другим UTM
  First-touch — игнорируем. Если человек пришёл по utm_source=habr 2 недели
  назад, потом по utm_source=vc сейчас — для меня он остаётся habr. Это
  сознательный выбор: я хочу знать «кто познакомил пользователя с продуктом», а не «через что он зашёл сегодня». Last-touch уже есть в Yandex.Metrika.
  
• Capacitor (нативное Android)
  Здесь отдельная подножка: window.location.search пустой, потому что бандл
  загружается с localhost (assets из APK). UTM параметры ловить через URL не получится. Решение — другой канал атрибуции: Capacitor приходит из RuStore, и каждая установка через RuStore просто помечается как app:rustore на бэке (определяем через user-agent или X-Auth-Mode: bearer заголовок, который и так шлётся на нативе для bearer-аутентификации).
  
• GDPR / 152-ФЗ
  UTM — не персональные данные. start_param — тоже. Это маркер канала, а не идентификатор человека. В оферте/политике конфиденциальности про это даже писать не нужно (но я написал — лишним не будет).
  
• Что если злоумышленник запихает 1MB текста в source?
  Не запихает. @MaxLength(128) валидатор отбросит на DTO, plus varchar(128) обрежет на уровне БД даже если каким-то чудом пройдёт.

SELECT
    acquisition_source,
    COUNT(*) AS users,
    MIN(created_at) AS first_seen,
    MAX(created_at) AS last_seen
  FROM 
  WHERE created_at > NOW() - INTERVAL '7 days'
    AND acquisition_source IS NOT NULL
  GROUP BY 1
  ORDER BY 2 DESC;