Verada Docs

ESP personalizzato ​

INFO

Nota: Questa documentazione è ancora in fase di elaborazione e soggetta a modifiche.

Introduzione ​

Questo documento descrive una proposta per una nuova integrazione di ESP personalizzato che fornirebbe una struttura di dati generica per rappresentare gli eventi supportati dall'interfaccia di streaming ESP di Fanplayr.

Configurazione dell'endpoint ​

Questo ESP può essere configurato dalla sezione Streams > Endpoints del portale Fanplayr. Di seguito è riportato un esempio delle potenziali opzioni di configurazione che saranno disponibili:

URL di pubblicazione ​

L'URL a cui Fanplayr trasmetterà i payload tramite il metodo HTTP POST. Il corpo della richiesta conterrà la struttura di dati JSON descritta più avanti in questo documento.

  • Tipo: string

Chiave API ​

Una chiave API opzionale che sarà inclusa nella richiesta POST al vostro URL e che potrà essere utilizzata per scopi di autenticazione.

Configurazione dello stream ​

Per inviare dati all'endpoint definito, sarà necessario creare uno stream che sia attivato dall'evento desiderato da catturare e che abbia un'azione che invii dati all'endpoint.

L'esempio seguente si attiva sull'evento "Session Expiry".

Struttura del payload ​

Di seguito è riportato un esempio della struttura del payload che viene inviato utilizzando l'integrazione Custom ESP. Questa struttura è utilizzata per;

json5
{
  "version": "2022-01-01",
  "eventType": "addContact" | "abandonedSession" | "abandonedCart" | "order",
  "sessionKey": "",
  "domain": "",
  "siteCustomerId": "",
  "subscriberEmail": "",
  "subscriberKey": "",
  "date": "2022-01-01T00:00:00Z",
  "customData": {
    "key1": "value1",
    "key2": "value2"
  },
  "abandonedCart": {
    "gross": 0,
    "discount": 0,
    "discountCode": "",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "",
        "sku": "",
        "name": "",
        "url": "",
        "image": "",
        "quantity": 0,
        "category": ""
      }
    ]
  },
  "orderDetails": {
    "id": "",
    "gross": 0,
    "discount": 0,
    "discountCode": "",
    "shipping": 0,
    "tax": 0,
    "products": [
      {
        "id": "",
        "sku": "",
        "name": "",
        "url": "",
        "image": "",
        "quantity": 0,
        "category": ""
      }
    ]
  },
  "productsViewed": [
    {
      "id": "",
      "sku": "",
      "name": "",
      "url": "",
      "image": "",
      "category": ""
    }
  ],
  "relatedProducts": [
    {
      "id": "",
      "sku": "",
      "name": "",
      "url": "",
      "image": "",
      "category": ""
    }
  ]
}

version ​

Rappresenta il formato della struttura del payload.

  • Tipo: string

eventType ​

Specifica il tipo di evento che questo payload rappresenta.

  • Tipo: string

  • Dettagli:

    Il tipo di evento sarà uguale a uno dei seguenti valori:\

    • addContact - Attivato quando viene acquisito un nuovo indirizzo email per un utente.
    • abandonedSession - Attivato alla fine della sessione di navigazione se l'utente non aveva prodotti nel carrello e non ha effettuato un ordine.
    • abandonedCart - Attivato alla fine della sessione di navigazione se l'utente aveva almeno un prodotto nel carrello che ha abbandonato e non ha effettuato un ordine.
    • order - Attivato quando viene acquisito un ordine.

domain ​

Il nome di dominio del sito web che l'utente ha navigato durante la sua sessione Fanplayr.

  • Tipo: string

siteCustomerId ​

Rappresenta l'identificatore dell'utente loggato per il sito web, se disponibile. Questo valore è assegnato tramite la proprietà customerId del tracciamento delle pagine di Fanplayr o dall'identità $siteCustomerId utilizzando la funzionalità di Gestione delle Identità.

  • Tipo: string | undefined

subscriberEmail ​

Questo valore sarà popolato se Fanplayr ha associato un indirizzo email all'utente tramite un widget Fanplayr durante la sessione corrente o in una sessione precedente.

  • Tipo: string | undefined

subscriberKey ​

Rappresenta l'identità dell'utente quando si utilizza la funzionalità di Gestione delle Identità di Fanplayr.

  • Tipo: string | undefined

date ​

La data di creazione dell'evento, in GMT, in formato ISO 8601.

  • Tipo: string

sessionKey ​

Un identificatore univoco che rappresenta l'ID della sessione di navigazione di Fanplayr.

  • Tipo: string

customData ​

Un oggetto contenente coppie chiave-valore di qualsiasi dato personalizzato che è stato allegato all'evento tramite lo Stream Fanplayr utilizzato per attivare e controllare l'evento.

typescript
interface CustomData {
  // [chiave: string]: string;
}

Esempio

json5
{
  key1: 'value1',
  key2: 'value2'
}

abandonedCart ​

Un oggetto che rappresenta lo stato finale del carrello quando uno o più prodotti rimangono nel carrello alla fine della sessione.

typescript
interface CartDetails {
  // Un valore monetario che rappresenta l'importo lordo totale
  // di tutti gli articoli nel carrello.
  gross: number;
  // Un valore monetario che rappresenta lo sconto totale applicato al carrello.
  discount: number;
  // Qualsiasi codice sconto applicato. Se ci sono più codici, saranno separati
  // da una virgola.
  discountCode?: string;
  // Un valore monetario che rappresenta il costo di spedizione.
  shipping: number;
  // Un valore monetario che rappresenta eventuali tasse.
  tax: number;
  // Rappresenta il codice valuta ISO 4217 per tutti i valori monetari.
  currencyCode: string;
  // Un array di prodotti aggiunti al carrello.
  products: CartProduct[];
}

interface CartProduct {
  // L'identificatore della variante del prodotto.
  id: string;
  // L'identificatore del gruppo di prodotti.
  sku: string;
  // Il nome visualizzato del prodotto.
  name: string;
  // L'URL completo del prodotto sul sito web.
  url: string;
  // L'URL completo dell'immagine principale del prodotto, se disponibile.
  image?: string;
  // La quantità del prodotto aggiunta al carrello.
  quantity: number;
  // Il nome della categoria del prodotto, se disponibile.
  category?: string;
}

Esempio:

json5
{
  gross: 120.0,
  discount: 10,
  discountCode: '10OFF',
  shipping: 0,
  tax: 0,
  currencyCode: 'USD',
  products: [
    {
      id: 'RDB1-A2',
      sku: 'RDB1',
      name: 'Rifiano Duffel Bag',
      url: 'https://store.com/products/rdb1',
      image: 'https://cdn.store.com/products/rdb1-01.jpg',
      quantity: 2,
      category: 'Accessories'
    }
  ]
}

productsViewed ​

Un array di oggetti che rappresentano i dettagli dei prodotti visualizzati durante la sessione.

  • Tipo: ViewedProduct[]
typescript
interface ViewedProduct {
  // L'identificatore della variante del prodotto.
  id: string;
  // L'identificatore del gruppo di prodotti.
  sku: string;
  // Il nome visualizzato del prodotto.
  name: string;
  // L'URL completo del prodotto sul sito web.
  url: string;
  // L'URL completo dell'immagine principale del prodotto, se disponibile.
  image?: string;
  // Il nome della categoria del prodotto, se disponibile.
  category?: string;
}

Esempio:

json5
[
  {
    id: 'RDB1-A2',
    sku: 'RDB1',
    name: 'Rifiano Duffel Bag',
    url: 'https://store.com/products/rdb1',
    image: 'https://cdn.store.com/products/rdb1-01.jpg',
    category: 'Accessories'
  },
  {
    id: 'VDD-1',
    sku: 'VDD',
    name: 'Vintage Denim Dress',
    url: 'https://store.com/products/vdd1',
    image: 'https://cdn.store.com/products/vdd1-01.jpg',
    category: 'Womens > Clothing'
  }
]

relatedProducts ​

Un array di oggetti che rappresentano i dettagli dei prodotti correlati all'evento.

  • Tipo: RelatedProduct[]
  • Dettagli:

    Questa proprietà esisterà nel payload solo se al l'evento sono state aggiunte raccomandazioni di prodotti (configurate tramite lo Stream).
typescript
interface RelatedProduct {
  // L'identificatore della variante del prodotto.
  id: string;
  // L'identificatore del gruppo di prodotti.
  sku: string;
  // Il nome visualizzato del prodotto.
  name: string;
  // L'URL completo del prodotto sul sito web.
  url: string;
  // L'URL completo dell'immagine principale del prodotto, se disponibile.
  image?: string;
  // Il nome della categoria del prodotto, se disponibile.
  category?: string;
}

Esempio:

json5
[
  {
    id: 'BFF-3',
    sku: 'BFF',
    name: 'Bali Flip Flop',
    url: 'https://store.com/products/bff',
    image: 'https://cdn.store.com/products/bff-01.jpg',
    category: 'Womens > Shoes'
  }
]

orderDetails ​

Un oggetto che rappresenta i dettagli della transazione degli ordini acquisiti. Questi dettagli sono disponibili solo per il tipo di evento "order".

typescript
interface OrderDetails {
  // L'identificatore unico dell'ordine fornito dalla vostra integrazione.
  id: string;
  // Un valore monetario che rappresenta l'importo lordo totale
  // di tutti gli articoli nel carrello.
  gross: number;
  // Un valore monetario che rappresenta lo sconto totale applicato al carrello.
  discount: number;
  // Qualsiasi codice sconto applicato. Se ci sono più codici, saranno separati
  // da una virgola.
  discountCode?: string;
  // Un valore monetario che rappresenta il costo di spedizione.
  shipping: number;
  // Un valore monetario che rappresenta eventuali tasse.
  tax: number;
  // Rappresenta il codice valuta ISO 4217 per tutti i valori monetari.
  currencyCode: string;
  // Un array di prodotti inclusi nell'ordine.
  products: OrderProduct[];
}

interface OrderProduct {
  // L'identificatore della variante del prodotto.
  id: string;
  // L'identificatore del gruppo di prodotti.
  sku: string;
  // Il nome visualizzato del prodotto.
  name: string;
  // L'URL completo del prodotto sul sito web.
  url: string;
  // L'URL completo dell'immagine principale del prodotto, se disponibile.
  image?: string;
  // La quantità del prodotto inclusa nell'ordine.
  quantity: number;
  // Il nome della categoria del prodotto, se disponibile.
  category?: string;
}

Esempio:

json5
{
  id: '34783495',
  gross: 120.0,
  discount: 10,
  discountCode: '10OFF',
  shipping: 0,
  tax: 0,
  currencyCode: 'USD',
  products: [
    {
      id: 'RDB1-A2',
      sku: 'RDB1',
      name: 'Rifiano Duffel Bag',
      url: 'https://store.com/products/rdb1',
      image: 'https://cdn.store.com/products/rdb1-01.jpg',
      quantity: 2,
      category: 'Accessories'
    }
  ]
}

Esempi di payload ​

Evento "Aggiungi contatto" ​

Di seguito è riportato un esempio della struttura del payload che rappresenta l'acquisizione dell'indirizzo email di un utente:

  • La proprietà action è impostata su addContact per rappresentare l'acquisizione di una nuova email.
  • La subscriberKey è uguale all'indirizzo email acquisito.
  • Potrebbero essere presenti anche dati aggiuntivi, come i prodotti visualizzati durante la sessione di navigazione dell'utente.
javascript
{
  "version": "2022-01-01",
  "eventType": "addContact",
  "sessionKey": "02941605ef4048c832f272b13b1a2d4e",
  "domain": "store.com",
  "subscriberKey": "email@domain.com",
  "date": "2022-01-01T00:00:00Z",
  "productsViewed": [
    {
      "id": "RDB1-A2",
      "sku": "RDB1",
      "name": "Rifiano Duffel Bag",
      "url": "https://store.com/products/rdb1",
      "image": "https://cdn.store.com/products/rdb1-01.jpg",
      "category": "Accessories"
    }
  ]
}

Evento "Sessione abbandonata" ​

Un esempio dell'evento di abbandono della sessione in cui l'utente non ha prodotti aggiunti al carrello alla fine della sessione.

json5
{
  version: '2022-01-01',
  eventType: 'abandonedSession',
  sessionKey: '02941605ef4048c832f272b13b1a2d4e',
  domain: 'store.com',
  date: '2022-01-01T00:00:00Z',
  productsViewed: [
    {
      id: 'RDB1-A2',
      sku: 'RDB1',
      name: 'Rifiano Duffel Bag',
      url: 'https://store.com/products/rdb1',
      image: 'https://cdn.store.com/products/rdb1-01.jpg',
      category: 'Accessories'
    }
  ]
}

Evento "Carrello abbandonato" ​

json5
{
  version: '2022-01-01',
  eventType: 'abandonedCart',
  sessionKey: '02941605ef4048c832f272b13b1a2d4e',
  domain: 'store.com',
  date: '2022-01-01T00:00:00Z',
  productsViewed: [
    {
      id: 'RDB1-A2',
      sku: 'RDB1',
      name: 'Rifiano Duffel Bag',
      url: 'https://store.com/products/rdb1',
      image: 'https://cdn.store.com/products/rdb1-01.jpg',
      category: 'Accessories'
    }
  ],
  abandonedCart: {
    gross: 120.0,
    discount: 10,
    discountCode: '10OFF',
    shipping: 0,
    tax: 0,
    products: [
      {
        id: 'RDB1-A2',
        sku: 'RDB1',
        name: 'Rifiano Duffel Bag',
        url: 'https://store.com/products/rdb1',
        image: 'https://cdn.store.com/products/rdb1-01.jpg',
        quantity: 2,
        category: 'Accessories'
      }
    ]
  }
}

Evento "Ordine" ​

Un esempio di evento d'ordine che viene attivato tramite il trigger dello stream "Order Received".

json5
{
  version: '2022-01-01',
  eventType: 'order',
  sessionKey: '02941605ef4048c832f272b13b1a2d4e',
  domain: 'store.com',
  date: '2022-01-01T00:00:00Z',
  productsViewed: [
    {
      id: 'RDB1-A2',
      sku: 'RDB1',
      name: 'Rifiano Duffel Bag',
      url: 'https://store.com/products/rdb1',
      image: 'https://cdn.store.com/products/rdb1-01.jpg',
      category: 'Accessories'
    }
  ],
  order: {
    id: '234897349',
    gross: 120.0,
    discount: 10,
    discountCode: '10OFF',
    currencyCode: 'USD',
    shipping: 0,
    tax: 0,
    products: [
      {
        id: 'RDB1-A2',
        sku: 'RDB1',
        name: 'Rifiano Duffel Bag',
        url: 'https://store.com/products/rdb1',
        image: 'https://cdn.store.com/products/rdb1-01.jpg',
        quantity: 2,
        category: 'Accessories'
      }
    ]
  }
}

Copyright © 2011-present Verada