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. Vedrai due coppie 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 (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. Crea un link di tracciamento nella dashboard Selgeo sotto Programmi > Link di tracciamento.
  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://api.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
  }'

Passaggi successivi​