Passa al contenuto principale

Avvio rapido

Configura il tuo programma di affiliazione in meno di 30 minuti. Questa guida ti spiega come aggiungere lo snippet di tracciamento Selgeo al tuo sito web, collegarlo a Stripe e verificare la tua prima conversione di test.

Versione API: v1

Prerequisiti​

  • Un account commerciante Selgeo
  • Accesso all'HTML del tuo sito web (o a un tag manager)
  • Un account Stripe collegato a Selgeo (per il tracciamento delle conversioni basato su Stripe)

Passaggio 1: Ottenere le chiavi API​

Accedi alla dashboard del commerciante Selgeo e naviga su Impostazioni > Chiavi API. Ogni modalità ha la propria coppia di chiavi:

Tipo di chiaveFormatoScopo
Chiave pubblica (test)pk_test_*Snippet JS sul tuo sito web (modalità test)
Chiave pubblica (live)pk_live_*Snippet JS sul tuo sito web (modalità live)
Chiave segreta (test)sk_test_*Chiamate API lato server (modalità test)
Chiave segreta (live)sk_live_*Chiamate API lato server (modalità live)

Le chiavi pubbliche sono presenti fin dall’inizio. Le chiavi segrete vengono generate su richiesta: fai clic su Genera chiave segreta nella modalità che ti serve. La chiave viene mostrata una sola volta, quindi copiala subito — una chiave segreta di test puoi rivederla da questa pagina con la tua password, una di live no, e perderla ti obbliga a ruotarla.

Le chiavi pubbliche (pk_*) possono essere incorporate in modo sicuro nel codice frontend. Possono solo registrare clic.

Le chiavi segrete (sk_*) non devono mai essere esposte al browser. Usale solo sul tuo server.

Inizia con le chiavi di test

Usa pk_test_* e sk_test_* durante l'integrazione. La modalità test traccia tutto nello stesso modo ma non crea commissioni reali. Passa alle chiavi live quando sei pronto per andare in produzione.

Passaggio 2: Aggiungere lo snippet di tracciamento​

Aggiungi il seguente tag <script> a ogni pagina del tuo sito web, appena prima del tag di chiusura </body>:

<script
  async
  src="https://cdn.selgeo.com/v1/selgeo.js"
  data-merchant="pk_test_YOUR_KEY"
></script>

Sostituisci pk_test_YOUR_KEY con la tua chiave pubblica effettiva dal Passaggio 1.

Per il tuo framework, consulta la guida dedicata​

Il tag <script> qui sopra funziona su qualsiasi pagina HTML. Se sviluppi su uno stack frontend moderno, l'integrazione equivalente si trova in una delle seguenti guide:

  • HTML / script semplice — siti statici, tag manager, pagine personalizzate renderizzate dal server.
  • Next.js — next/script per App Router e Pages Router.
  • React (Vite) — posizionamento in index.html, con fallback useEffect.
  • WordPress — Editor del sito, footer.php o un plugin per intestazione e piè di pagina.

Cosa fa lo snippet:

  1. Quando un visitatore arriva tramite un link di referral di un partner (es. https://tuo-sito.com/?ref=abc123), lo snippet registra il clic su Selgeo e memorizza un click_id nel sessionStorage del browser.
  2. Se usi Stripe Payment Links, lo snippet aggiunge automaticamente il click_id a quei link come client_reference_id — nessun lavoro backend necessario.
  3. Lo snippet è senza cookie. Usa solo sessionStorage, che viene cancellato quando la scheda del browser viene chiusa.

Passaggio 3: Verificare l'installazione​

  1. Ottieni un link di referral. I link di tracciamento vengono creati dai partner nel portale partner (nella sezione Link), non nella dashboard del merchant. Per un rapido test personale, accedi al portale partner come partner di test e creane uno, oppure chiedi a un partner esistente il suo link.
  2. Apri una nuova scheda del browser e visita il tuo sito usando il link di tracciamento.
  3. Apri gli Strumenti per sviluppatori del browser (F12) e controlla la scheda Console. Con data-debug aggiunsoo vedrai: 
    [selgeo] ref detected IL_TUO_REF
    [selgeo] click_id stored xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  4. Verifica il click_id eseguendo questo nella console del browser: 
    __selgeo.getClickId()
  5. Controlla la dashboard Selgeo — il clic dovrebbe apparire in Analytics entro pochi secondi.

Passaggio 4: Tracciare le conversioni tramite Stripe​

Selgeo supporta tre percorsi di integrazione Stripe. Scegli quello che corrisponde alla tua configurazione:

Lo snippet rileva automaticamente tutti i tag <a> che puntano a https://buy.stripe.com/... e aggiunge ?client_reference_id=CLICK_ID.

<!-- Il tuo Payment Link esistente — lo snippet lo riscrive automaticamente -->
<a href="https://buy.stripe.com/test_abc123">Abbonati ora</a>

Opzione B: Stripe Checkout (una riga di codice frontend)​

Frontend — leggi l'ID clic dallo snippet:

const clickId = __selgeo.getClickId();

fetch('/api/create-checkout', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ priceId: 'price_xxx', clickId: clickId }),
});

Backend — passalo come client_reference_id:

const stripe = require('stripe')('sk_test_YOUR_STRIPE_KEY');

app.post('/api/create-checkout', async (req, res) => {
  const session = await stripe.checkout.sessions.create({
    mode: 'subscription',
    line_items: [{ price: req.body.priceId, quantity: 1 }],
    success_url: 'https://tuo-sito.com/success',
    cancel_url: 'https://tuo-sito.com/cancel',
    client_reference_id: req.body.clickId || undefined,
  });
  res.json({ url: session.url });
});

Opzione C: Conversioni non-Stripe (API di conversione)​

curl -X POST https://app.selgeo.com/api/v1/conversions \
  -H "Authorization: Bearer sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "CLICK_ID_DAL_FRONTEND",
    "external_transaction_id": "signup_12345",
    "event_type": "signup",
    "amount_cents": 0
  }'

Passaggio 5: Testare una conversione end-to-end​

Esegui l'intero ciclo in modalità di test per verificare che tutto funzioni:

  1. Crea un programma di test nella dashboard Selgeo e approva almeno un partner. Poi fai creare a quel partner un link di referral nel portale partner (nella sezione Link).
  2. Fai clic sul link di referral in una nuova scheda del browser. Questo registra un clic e memorizza un click_id.
  3. Completa un acquisto usando uno dei metodi sopra:
    • Payment Links: Fai clic su uno Stripe Payment Link sul tuo sito. Usa la carta di test Stripe 4242 4242 4242 4242.
    • Checkout: Avvia il tuo flusso di checkout. Il click_id viene passato come client_reference_id.
    • API di conversione: Invia una richiesta POST /api/v1/conversions dal tuo server con il click_id.
  4. Controlla la dashboard: Vai su Analytics nella dashboard Selgeo. Dovresti vedere:
    • Il clic registrato sotto il partner
    • La conversione attribuita al partner
    • Una commissione calcolata (se sono configurate regole di commissione)
Carte di test Stripe

Usa i numeri di carta di test di Stripe per simulare pagamenti senza addebiti reali. Il più comune è 4242 4242 4242 4242 con qualsiasi data di scadenza futura e qualsiasi CVC.

Passaggi successivi​