Program poleceń (rejestracja z kodem)

Framework: React / Next.js

Pobieranie danych jest przenośne — w blokach z przykładami zakładka Raw pokazuje czysty fetch działający w dowolnym frameworku.
UI (komponenty z hookami i JSX) jest specyficzne dla React / Next.js. W innym frameworku weź zapytanie z zakładki Raw i napisz własny widok.

Co zbudujesz

Kompletny flow programu poleceń: odwiedzający klika link polecający (https://twoj-sklep.pl/register?ref=REF-AB12CD34), kod zostaje zapamiętany, a przy rejestracji trafia do customerSignup — nowy klient dostaje bonus powitalny z polecenia, a polecający punkty po pierwszym opłaconym zamówieniu. Do tego sekcja konta, w której klient widzi własny kod, link do udostępnienia i statystyki poleceń.

Sedno — kod z linku musi przeżyć nawigację do momentu rejestracji:

useReferralCapture();                          // 1. wejście z linku → cookie `referral-code` (30 dni)
const referralCode = getReferralCodeCookie();  // 2. przy rejestracji odczytaj kod
await signup({ ...dane, referralCode });       // 3. przekaż w input mutacji customerSignup
clearReferralCodeCookie();                     // 4. po sukcesie wyczyść

Wymagania

Skonfigurowany SDK i provider — Konfiguracja Next.js.
Włączony program poleceń w panelu sklepu (sekcja „Program poleceń" w ustawieniach programu lojalnościowego). Stan programu odczytasz z zapytania LoyaltySettings (pola referralEnabled, referralPoints, referralBonusPoints).

Krok 1 — Przechwyć kod z linku polecającego

Zamontuj raz, wysoko w aplikacji (np. w layoucie), komponent wywołujący useReferralCapture(). Hook odczytuje parametr ?ref=KOD z adresu wejścia i zapisuje go w cookie referral-code — domyślnie na 30 dni, więc odwiedzający może spokojnie pooglądać sklep i wrócić do rejestracji później.

To okno „wejście z linku → rejestracja" jest niezależne od ustawionej w panelu ważności polecenia — tamta liczy dni od rejestracji na pierwsze zamówienie poleconego i jest egzekwowana przez API.

Krok 2 — Rejestracja z kodem

Mutacja customerSignup przyjmuje w input opcjonalne pole referralCode. Nieprawidłowy, wygasły lub własny kod jest ignorowany — rejestracja zawsze przechodzi, więc nie musisz go walidować po swojej stronie. Wybierz kontekst renderowania:

Raw (dowolny framework)

Brak gotowego helpera SDK dla tej operacji — użyj raw operation (działa w każdym frameworku).

// Działa w dowolnym frameworku (Vue, Svelte, vanilla JS, Node, Edge)
const QUERY = `mutation CustomerSignup($input: CustomerCreateInput!) {
  customerSignup(input: $input) {
    customer {
      ...Customer
    }
    customerAccessToken {
      ...CustomerAccessToken
    }
    accountStatus
    pendingApprovalMessage
    userErrors {
      ...UserError
    }
  }
}

fragment Customer on Customer {
  id
  email
  firstName
  lastName
  displayName
  phone
  isEmailVerified
  emailMarketing
  tags
  customerType
  companyName
  taxId
  vatNumber
  regon
  defaultAddress {
    ...MailingAddress
  }
  orderCount
  totalSpent {
    ...Money
  }
  createdAt
  updatedAt
}

fragment MailingAddress on MailingAddress {
  id
  streetLine1
  streetLine2
  buildingNumber
  flatNumber
  city
  company
  country
  countryCode
  firstName
  lastName
  name
  phone
  state
  stateCode
  postalCode
  isDefault
  taxId
  vatNumber
  regon
  pickupPoint {
    ...PickupPoint
  }
}

fragment PickupPoint on PickupPoint {
  provider
  pointId
  name
  address
  paymentAvailable
}

fragment Money on Money {
  amount
  currencyCode
}

fragment CustomerAccessToken on CustomerAccessToken {
  accessToken
  expiresAt
}

fragment UserError on UserError {
  message
  code
  field
}`;

const res = await fetch(`${apiUrl}/storefront/graphql`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: QUERY, variables: { input: /* … */ }, }),
});
const { data } = await res.json();

Krok 3 — Komponenty (React)

Oba komponenty są weryfikowane typami przeciw @doswiftly/storefront-sdk — zmiana publicznego API nie przejdzie weryfikacji, dlatego ten przykład nie może zdryfować. ReferralAwareSignupButton pokazuje sam rdzeń flow (odczyt kodu → przekazanie do mutacji → wyczyszczenie); w realnym formularzu połącz go z resztą pól rejestracji:

referral.tsx
'use client';

import { useState } from 'react';
import {
  useReferralCapture,
  getReferralCodeCookie,
  clearReferralCodeCookie,
} from '@doswiftly/storefront-sdk/react';

// ReferralCapture: zamontuj raz, wysoko w aplikacji (np. w layoucie).
// Odczytuje parametr `?ref=KOD` z adresu wejścia i zapisuje kod w cookie
// `referral-code` (30 dni) — kod przeżyje nawigację po sklepie i poczeka,
// aż odwiedzający faktycznie założy konto.
export function ReferralCapture() {
  useReferralCapture();
  return null;
}

// ReferralAwareSignupButton: sedno rejestracji z polecenia. Przy wysyłce
// formularza dołącz zapisany kod jako `referralCode` w input mutacji
// `customerSignup`, a po sukcesie wyczyść cookie — kolejne rejestracje
// z tej przeglądarki nie użyją go ponownie. Nieprawidłowy, wygasły lub
// własny kod jest po stronie API ignorowany: rejestracja zawsze przechodzi.
export function ReferralAwareSignupButton({
  onSignup,
}: {
  // Transport mutacji dostarcza Twój storefront (wygenerowany hook lub klient
  // GraphQL) — komponent przekazuje mu komplet pól wraz z kodem polecenia.
  onSignup: (input: { referralCode?: string }) => Promise<void>;
}) {
  const [isSubmitting, setIsSubmitting] = useState(false);

  const handleSignup = async () => {
    setIsSubmitting(true);
    try {
      const referralCode = getReferralCodeCookie();
      await onSignup({ referralCode: referralCode ?? undefined });
      clearReferralCodeCookie();
    } finally {
      setIsSubmitting(false);
    }
  };

  return (
    <button type="button" onClick={handleSignup} disabled={isSubmitting} aria-busy={isSubmitting}>
      {isSubmitting ? 'Zakładanie konta…' : 'Załóż konto'}
    </button>
  );
}

Wyczyść kod po sukcesie

Po udanej rejestracji wywołaj clearReferralCodeCookie(). Bez tego kolejna rejestracja z tej samej przeglądarki (np. drugi domownik) ponownie użyłaby starego kodu.

Krok 4 — Pokaż klientowi jego kod i statystyki

Zalogowany klient generuje (lub odczytuje) własny kod mutacją loyaltyGenerateReferralCode — odpowiedź niesie też gotowy shareUrl (link w formacie …/register?ref=KOD, dokładnie ten, który obsługuje Krok 1):

Raw (dowolny framework)

Brak gotowego helpera SDK dla tej operacji — użyj raw operation (działa w każdym frameworku).

// Działa w dowolnym frameworku (Vue, Svelte, vanilla JS, Node, Edge)
const QUERY = `mutation GenerateReferralCode {
  loyaltyGenerateReferralCode {
    ...GenerateReferralCodePayload
  }
}

fragment GenerateReferralCodePayload on GenerateReferralCodePayload {
  success
  referralCode
  shareUrl
  userErrors {
    ...UserError
  }
}

fragment UserError on UserError {
  message
  code
  field
}`;

const res = await fetch(`${apiUrl}/storefront/graphql`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: QUERY, }),
});
const { data } = await res.json();

Statystyki poleceń (ilu poleconych, ile zakończonych pierwszym zakupem, ile punktów zdobytych) zwraca zapytanie ReferralStats:

Client Component
Raw (dowolny framework)

'use client';
import { useReferralStats } from '@/lib/graphql/hooks';

const { data, isLoading, error } = useReferralStats();

// Działa w dowolnym frameworku (Vue, Svelte, vanilla JS, Node, Edge)
const QUERY = `query ReferralStats {
  referralStats {
    ...ReferralStats
  }
}

fragment ReferralStats on ReferralStats {
  referralCode
  shareUrl
  totalReferred
  completedReferrals
  pendingReferrals
  totalPointsEarned
}`;

const res = await fetch(`${apiUrl}/storefront/graphql`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ query: QUERY, }),
});
const { data } = await res.json();

Typy

Renderowane ze schematu GraphQL — nigdy nie rozjeżdżają się z API:

ReferralStats

ReferralStatsobjectPełna referencja →

Referral program statistics

Pole	Typ	Opis
`completedReferrals`	`Int!`	Completed referrals (first order placed)
`pendingReferrals`	`Int!`	Pending referrals (signed up, no order yet)
`referralCode`	`String!`	Customer referral code
`shareUrl`	`String!`	Shareable referral URL
`totalPointsEarned`	`Int!`	Total points earned from referrals
`totalReferred`	`Int!`	Total customers referred

LoyaltySettings

LoyaltySettingsobjectPełna referencja →

Public loyalty program settings

Pole	Typ	Opis
`availableActions`	`[LoyaltyAction!]!`	Available point earning actions
`isEnabled`	`Boolean!`	Whether loyalty program is enabled
`pointsExpiryMonths`	`Int`	Months until points expire (null = no expiry)
`pointsName`	`String!`	Custom name for points (e.g., "Points", "Stars", "Coins")
`pointsPerCurrency`	`Float!`	Points earned per 1 unit of currency
`referralBonusPoints`	`Int`	Bonus points for referred customer
`referralEnabled`	`Boolean!`	Whether referral program is enabled
`referralPoints`	`Int`	Points awarded to referrer

Powiązane

Logowanie, rejestracja, reset hasła — Logowanie i rejestracja.
Punkty, poziomy, nagrody klienta — Konto klienta.
Rdzeń SDK (helpery cookie, stałe) — Referencja TypeScript SDK.
Kontrakt operacji CustomerSignup / ReferralStats — Referencja GraphQL API.

Co zbudujesz​

Wymagania​

Krok 1 — Przechwyć kod z linku polecającego​

Krok 2 — Rejestracja z kodem​

Krok 3 — Komponenty (React)​

Krok 4 — Pokaż klientowi jego kod i statystyki​

Typy​

ReferralStats​

LoyaltySettings​

Powiązane​