Funzionalità

Le funzionalità (Capabilities) sono punti di integrazione che il tuo sito web implementa per esporre funzionalità aggiuntive — per esempio, definendo una funzione che gestisce l'aggiunta di un prodotto al carrello per abilitare un pulsante Aggiungi al Carrello all'interno di un widget Fanplayr di Raccomandazioni di Prodotto.

Funzionalità Disponibili

Funzionalità	Descrizione
addProductToCart	Pulsante "Aggiungi al Carrello" nei widget di Raccomandazioni di Prodotto
applyToCart	Pulsante "Applica Offerta" nei widget di sconti/offerte
sessionOffer	Notifica il tuo negozio quando Fanplayr presenta un'offerta a un visitatore

Le funzionalità sono registrate sull'oggetto fanplayr.platform.capabilities all'interno della callback fanplayr_ready, che viene attivata una volta che gli script di Fanplayr sono stati caricati.

window.fanplayr_ready = function () {
  // Registra qui le funzionalità
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.sessionOffer = function (event) {
    /* ... */
  };
};

---

Aggiungi Prodotto al Carrello

La funzionalità addProductToCart consente al widget di Raccomandazioni di Prodotto di Fanplayr di aggiungere un prodotto direttamente al carrello del visitatore senza che questi lasci la pagina.

Firma del gestore

interface AddProductEvent {
  /** ID del prodotto definito nel catalogo Fanplayr */
  id: string
  /** Qualsiasi dato personalizzato definito per il prodotto */
  customData?: Record<string, any>
}

fanplayr.platform.capabilities.addProductToCart = (event: AddProductEvent) => void | Promise<void>

Il gestore riceve un oggetto AddProductEvent contenente l'id del prodotto dal tuo catalogo Fanplayr. È supportato il ritorno di una Promise — Fanplayr attenderà che si risolva prima di riabilitare il pulsante del widget, il che previene invii duplicati. Il tuo gestore è responsabile di eventuali parametri aggiuntivi del carrello, come la quantità.

Esempio base

Prima di andare online

Questo è solo un esempio. Devi sostituire l'intera chiamata fetch con la logica API del carrello del tuo negozio.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    // Sostituisci questo con l'API reale del carrello del tuo negozio:
    return fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId: product.id })
    });
  };
};

Utilizzo di customData

Se definisci attributi personalizzati sui prodotti nel tuo catalogo Fanplayr (ad es. ID varianti, SKU o riferimenti interni), questi sono disponibili su product.customData e possono essere passati alla tua API del carrello.

---

Applica Offerta al Carrello

La funzionalità applyToCart consente ai widget di offerte e sconti di Fanplayr di applicare un codice coupon o promozionale direttamente al carrello del visitatore.

Non è la stessa cosa di Aggiungi Prodotto al Carrello

Questa funzionalità gestisce codici di sconto/offerta (ad es. FREESHIP), non prodotti. Vedi Aggiungi Prodotto al Carrello se desideri integrare raccomandazioni di prodotto.

Esistono due modi per implementare questa funzionalità: un semplice approccio di reindirizzamento URL o un gestore personalizzato per integrazioni più complesse.

Opzione 1 — Reindirizzamento URL

Fornisci un applyToCartUrl come parte della configurazione del tracciamento utente. Includi il placeholder %c dove il codice offerta dovrebbe essere inserito.

{
  type: 'st',
  accountKey: '7e43c8cddccade2b95ee5286ba89758a',
  applyToCartUrl: 'https://example.com/applyOffer.php?code=%c',
  data: {
    // Dati di tracciamento utente
  }
}

Quando un visitatore attiva l'offerta, Fanplayr reindirizza il browser a questo URL con %c sostituito dal codice offerta (ad es. FREESHIP), risultando in:

https://example.com/applyOffer.php?code=FREESHIP

Il tuo endpoint deve quindi:

1. Applicare il codice offerta specificato al carrello.
2. Reindirizzare l'utente alla pagina del carrello.
3. Migliore pratica: Se il codice non può essere applicato, mostra un messaggio informativo che spieghi il motivo.

Opzione 2 — Gestore personalizzato

Se l'applicazione di un codice richiede logica lato client (ad es. la chiamata a un'API del carrello JavaScript), registra invece una funzione gestore.

Firma del gestore

interface AddOfferEvent {
  /** Il codice offerta/coupon da applicare */
  code: string
}

fanplayr.platform.capabilities.applyToCart = (event: AddOfferEvent) => void | Promise<void>

Esempio base

Prima di andare online

Questo è solo un esempio. Devi sostituire l'intero corpo del gestore con la logica del tuo negozio per applicare un codice offerta.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    // Sostituisci questo con la logica del tuo negozio per applicare il codice offerta al carrello
    console.warn('Fanplayr: la funzionalità applyToCart non è implementata');
  };
};

Esempio asincrono

Restituire una Promise indica a Fanplayr di attendere che si risolva prima di riabilitare l'interfaccia utente del widget, impedendo che il gestore venga attivato più volte mentre la tua richiesta è in corso.

Prima di andare online

Questo è solo un esempio. Devi sostituire l'intera chiamata fetch con la logica API del carrello del tuo negozio.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = async function (event) {
    // Sostituisci questo con l'API reale del carrello del tuo negozio:
    await fetch('/api/apply-code-to-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};

Legacy: callback di completamento

Le versioni precedenti di questa funzionalità supportavano una callback doneFn opzionale come secondo argomento invece di una Promise. Questa è ancora supportata per la retrocompatibilità, ma l'approccio con Promise descritto sopra è preferito per le nuove implementazioni.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event, doneFn) {
    $.ajax({
      type: 'GET',
      url: '/api/apply-code-to-cart',
      data: { code: event.code },
      complete: function () {
        doneFn();
      }
    });
  };
};

---

Offerta di Sessione

La funzionalità sessionOffer fa parte della funzione Offerte di Sessione di Fanplayr, che aiuta a impedire agli utenti non autorizzati di reclamare codici sconto al di fuori di una sessione Fanplayr.

Quando Fanplayr presenta un'offerta a un visitatore, invoca il tuo gestore sessionOffer con il codice offerta. Il tuo gestore è responsabile di contrassegnare il codice come valido per la durata della sessione del visitatore, in modo che il tuo negozio possa verificarlo prima di applicarlo al carrello.

Alternativa basata su URL

Se preferisci un approccio lato server piuttosto che un gestore JavaScript, puoi fornire un sessionOfferUrl nella configurazione del tracciamento utente. Vedi Offerte di Sessione per tutti i dettagli.

Firma del gestore

interface SessionOfferEvent {
  /** Il codice offerta presentato al visitatore */
  code: string
}

fanplayr.platform.capabilities.sessionOffer = (event: SessionOfferEvent) => void | Promise<void>

È supportato il ritorno di una Promise — se la Promise viene rifiutata, Fanplayr tratterà l'offerta di sessione come fallita e potrebbe riprovare in una chiamata successiva. Se la Promise si risolve, o se non viene restituita alcuna Promise, l'offerta è considerata registrata con successo.

Esempio

Prima di andare online

Questo è solo un esempio. Devi sostituire il corpo del gestore con la logica del tuo negozio per contrassegnare un codice offerta come valido per la sessione corrente.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.sessionOffer = async function (event) {
    // Sostituisci questo con la logica del tuo negozio per contrassegnare il codice come valido
    // per la sessione corrente del visitatore:
    await fetch('/api/session-offers/allow', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};