SFMC Tips #356: Personalization: Configurare i Resolver in Sitemap Builder

Nell’articolo precedente abbiamo utilizzato i Page Types in Sitemap Builder, l’estensione Google Chrome per Salesforce Personalization, per configurare TrailNest in modo che ogni pagina potesse essere riconosciuta come:

• Home
• Category
• Product Detail
• Cart
• Checkout
• Order Confirmation

SFMC Tips #355: Personalization: Configurare i Page Types in Sitemap Builder

Con i Page Types, siamo ora in grado di determinare “che tipo di pagina viene attualmente visualizzata.”

Tuttavia, riconoscere semplicemente il Product Detail non ci permette ancora di recuperare dati specifici come:

• “Quale prodotto viene visualizzato?“
• “Qual è il nome del prodotto?“
• “Quanto costa?“

Questa volta configureremo questi valori.

Cos’è un Resolver?

Un Resolver in Sitemap Builder è un processo riutilizzabile per recuperare i valori richiesti da una pagina Web.

La documentazione Help descrive un Resolver come una piccola funzione riutilizzabile che recupera valori dal DOM, dall’URL, dallo Storage, dal JavaScript Context e così via, e che può essere riutilizzata da più Event e Page Types.

Ad esempio, supponiamo che una pagina Product Detail contenga il seguente HTML.

<main
    id="trailnest-app"
    data-product-id="TN-BP-003"
    data-product-name="Trail Pro 35L"
    data-product-price="139000">

Utilizzando i Resolver, è possibile recuperare solo i valori richiesti da questo HTML.

• Product ID
  → TN-BP-003
• Product Name
  → Trail Pro 35L
• Product Price
  → 139000

I valori recuperati verranno successivamente utilizzati da Event come Product View e Add to Cart.

In altre parole, per semplificare il flusso della Sitemap in questo caso:

• Page Type
  → Determina che “viene mostrato il Product Detail”
• Resolver
  → Recupera che “il prodotto visualizzato è TN-BP-003”
• Event
  → Invia che “TN-BP-003 è stato visualizzato”

Ecco come i componenti si relazionano tra loro.

I Resolver in Sitemap Builder permettono di configurare tramite UI i Resolver per il recupero dati forniti dal Salesforce Interactions SDK.

Ad esempio, selezionando CSS Selector (text) si recupera il testo di un elemento HTML, mentre selezionando CSS Selector Attribute si recupera il valore di un attributo specificato da un elemento HTML.

Il Salesforce Interactions SDK fornisce i Resolver corrispondenti come fromSelector() e fromSelectorAttribute(). Utilizzando Sitemap Builder, è possibile configurare questo processo senza dover scrivere JavaScript da zero.

Aprire la Tab Resolvers

Apri la tab Resolvers in Sitemap Builder e clicca su + Add New Resolver.

La schermata di creazione del Resolver contiene principalmente le seguenti impostazioni.

※ Questa sezione si limita a spiegarle. Le configureremo effettivamente nelle sezioni successive.

① Name

Questo è il nome del Resolver che stai creando.

Ad esempio:

• Product ID
• Product Name
• Product Price

Imposta un nome che chiarisca quale valore verrà recuperato.

Poiché in seguito selezionerai i Resolver dagli Event, è utile dare loro nomi che indichino chiaramente il loro scopo.

② Kind

Specifica in che modo viene creato il Resolver.

Nella schermata utilizzata in questo caso, puoi selezionare:

• Built-in
• Custom JavaScript

Con Built-in, i valori vengono recuperati utilizzando i metodi forniti da Sitemap Builder, come CSS Selector o URL.

Custom JavaScript viene utilizzato quando si desidera recuperare valori tramite JavaScript personalizzato, nei casi in cui il valore sia difficile da ottenere usando solo Built-in.

Poiché i dati necessari sono già stati preparati nell’HTML di TrailNest, utilizzeremo principalmente Built-in.

③ Method

Specifica da dove e in che modo viene recuperato il valore.

Sono disponibili principalmente i seguenti metodi.

• CSS Selector (text)
  Recupera il testo dal primo elemento HTML corrispondente al CSS Selector
• CSS Selector Attribute
  Recupera l’attributo specificato dal primo elemento HTML corrispondente al CSS Selector
• CSS Selector (multiple)
  Recupera il testo da più elementi HTML corrispondenti
• CSS Selector Attribute (multiple)
  Recupera l’attributo specificato da più elementi HTML corrispondenti
• Current URL (href)
  Recupera l’URL della pagina attualmente visualizzata
• Meta Tag (name or property)
  Recupera un valore da un Meta Tag HTML
• Window Path
  Recupera un valore presente nell’oggetto window

e altri ancora.

Ad esempio, CSS Selector (text) recupera il testo visualizzato di un elemento HTML.

Se l’HTML è:

<h1 class="product-title">Trail Pro 35L</h1>

puoi recuperare Trail Pro 35L da product-title.

Al contrario, CSS Selector Attribute recupera il valore di un attributo impostato su un elemento HTML.

Ad esempio, da:

<main
    id="trailnest-app"
    data-product-id="TN-BP-003">

puoi recuperare data-product-id.

TrailNest include data-product-id, data-product-name e data-product-price, quindi utilizzeremo frequentemente CSS Selector Attribute.

④ Output Type

Con un Resolver Built-in, specifichi come trattare il tipo di dato del valore recuperato.

Nella schermata utilizzata in questo caso, puoi selezionare:

• Text
• Number
• Boolean
• Date

※ L’Output Type non viene specificato per un Resolver Custom JavaScript.

Ad esempio:

• Product ID e Product Name → Text
• Product Price → Number

Suggerimento: Anche se il valore recuperato dall’HTML è una stringa, impostando Output Type su Number è possibile trattarlo come un valore numerico.

⑤ Selector

Specifica da quale elemento HTML recuperare il valore tramite un CSS Selector.

Puoi inserire il selettore manualmente, ma utilizzando Pick puoi selezionare direttamente l’elemento target dalla pagina Web attualmente visualizzata.

⑥ Output

Questa è la sezione dove puoi verificare quale valore il Resolver configurato recupera effettivamente dalla pagina Web corrente.

Quando si configura un Resolver, è utile mantenere aperta nel browser la pagina target, in modo da poter verificare il risultato recuperato durante la configurazione.

Creare il Resolver Product ID

Ora creiamo Product ID come primo Resolver.

Prima di tutto, apri un prodotto qualsiasi in TrailNest e visualizza la pagina Product Detail.

Ad esempio, la pagina prodotto utilizzata in questo caso contiene il seguente HTML.

<main
    id="trailnest-app"
    data-page-type="product_detail"
    data-product-id="TN-BP-003"
    data-product-name="Trail Pro 35L"
    data-product-price="139000">

Il valore che vogliamo recuperare in questo caso è:

• data-product-id=”TN-BP-003″

precisamente: TN-BP-003

Clicca su Add New Resolver e configura come segue.

• Name: Product ID
• Kind: Built-in
• Method: CSS Selector Attribute
• Output Type: Text
• Selector: #trailnest-app
• Attribute: data-product-id

In questo caso:

• Selector: #trailnest-app

significa trovare l’elemento HTML con:

id=”trailnest-app”

Poi:

• Attribute: data-product-id

recupera il valore di data-product-id da quell’elemento.

Sitemap Builder genera il seguente Resolver.

resolvers.fromSelectorAttribute('#trailnest-app', 'data-product-id')

fromSelectorAttribute() è un Resolver che recupera il valore di un attributo specifico dall’elemento corrispondente al CSS Selector indicato.

Se viene valutato correttamente, Output mostra qualcosa come:

• TN-BP-001

Con questo, abbiamo completato il Resolver per recuperare il Product ID del prodotto attualmente visualizzato su Product Detail.

Clicca su Save.

Creare il Resolver Product Name

Successivamente, recuperiamo Product Name.

Il Product Detail contiene anche il seguente attributo.

• data-product-name=”Trail Pro 35L”

La configurazione è quasi identica a Product ID. Cambia solo l’Attribute da recuperare.

• Name: Product Name
• Kind: Built-in
• Method: CSS Selector Attribute
• Output Type: Text
• Selector: #trailnest-app
• Attribute: data-product-name

Il Resolver generato è:

resolvers.fromSelectorAttribute(
    '#trailnest-app',
    'data-product-name'
)

Verifica che Output mostri qualcosa come:

• Alpine Daypack 18L

Se non ci sono problemi, clicca su Save.

Creare il Resolver Product Price

Successivamente, recuperiamo Product Price.

L’HTML contiene:

• data-product-price=”139000″

Configura come segue.

• Name: Product Price
• Kind: Built-in
• Method: CSS Selector Attribute
• Output Type: Number
• Selector: #trailnest-app
• Attribute: data-product-price

Ciò che differisce da Product ID e Product Name in questo caso è che Output Type è impostato su Number.

Il valore 139000 recuperato dall’Attribute HTML esiste originariamente come stringa, ma poiché Product Price verrà successivamente incluso in un Event come prezzo, lo trattiamo come Number.

Il Resolver generato è:

resolvers.fromSelectorAttribute(
    '#trailnest-app',
    'data-product-price'
)

e viene trattato come valore numerico in base all’Output Type specificato in Sitemap Builder.

Verifica che Output mostri qualcosa come: 79000

e salvalo.

Perché Recuperare i Valori dagli Attributi data-*?

In questo caso, Product ID non viene visualizzato sulla pagina, ma Product Name e Product Price sono effettivamente mostrati sulla pagina reale.

Ad esempio, per Product Name, potresti recuperare il testo da un elemento come:

<h1>Trail Pro 35L</h1>

utilizzando CSS Selector (text).

Eppure, in questo caso recuperiamo i valori da Attribute come:

• data-product-name=”Trail Pro 35L”
• data-product-price=”139000″

Il motivo è separare quanto più possibile la presentazione visuale della pagina Web dal recupero dei dati.

Ad esempio, se una modifica al design trasforma:

• h1.product-title

in:

• div.product-header > h2

un Resolver che fa riferimento direttamente all’elemento visualizzato potrebbe necessitare di modifiche.

D’altro canto, fintanto che i seguenti elementi preparati intenzionalmente per la Sitemap vengono mantenuti:

• #trailnest-app
• data-product-id
• data-product-name
• data-product-price

l’impatto sul Resolver può essere ridotto anche in caso di cambiamenti nel layout della pagina.

Si raccomanda di mantenere i Selector quanto più semplici possibile, utilizzando informazioni stabili come ID o Class univoche piuttosto che basarsi su lunghe catene di elementi figli o su nth-child.

Utilizzare Custom JavaScript

Finora abbiamo utilizzato Resolver Built-in poiché le informazioni sul prodotto potevano essere recuperate dagli attributi data-* dell’HTML.

Tuttavia, in TrailNest, abbiamo anche casi in cui desideriamo:

• Restituire un valore fisso
• Recuperare un valore inserito in un Form
• Recuperare informazioni sull’Order memorizzate in Local Storage

In questi casi, utilizza un Resolver Custom JavaScript.

Con un Resolver Custom JavaScript, configuri una funzione che alla fine restituisce il valore.

Ad esempio:

() => 1

※ Ciò significa che ogni volta che questo Resolver viene valutato, restituisce sempre 1.

Lo stesso Resolver del Salesforce Interactions SDK funziona restituendo una Function che può essere valutata successivamente, piuttosto che un valore diretto come 1.

Creare il Resolver Product Quantity

Per Add to Cart, oltre a Product ID e prezzo è necessaria anche la Quantity.

In TrailNest, la quantità aggiunta ogni volta che viene cliccato il pulsante Add to Cart è sempre 1, quindi creeremo un Resolver che restituisce un valore fisso.

Configura come segue.

• Name: Product Quantity
• Kind: Custom JavaScript

Inserisci il seguente codice in Custom JavaScript.

() => 1

Verifica che Output mostri: 1

e salvalo.

Anche se è molto semplice, definire un valore fisso come Resolver permette di riutilizzarlo successivamente dall’Event Add to Cart.

Creare il Resolver Checkout Email

Successivamente, spostiamoci sulla pagina Checkout.

In TrailNest, l’utente inserisce un Indirizzo Email al Checkout.

L’HTML contiene:

<input
    id="email"
    name="email"
    type="email"
    required>

Crea un Resolver per recuperare l’Indirizzo Email inserito.

• Name: Checkout Email
• Kind: Custom JavaScript

Imposta il seguente codice in Custom JavaScript.

() => (document.querySelector('#email')?.value || '').trim()

Quando il Resolver viene valutato, l’Indirizzo Email inserito viene mostrato in Output.

Questo Resolver verrà successivamente utilizzato per creare Contact Point Email.

Creare il Resolver Checkout Customer ID

In TrailNest, viene inserito anche il Customer ID, per rendere il sito più vicino a un reale sito e-commerce.

※ Normalmente si utilizzerebbe un processo di login, ma in questo caso facciamo semplicemente inserire il valore all’utente.

L’HTML contiene:

<input
    id="customerId"
    name="customerId"
    type="text"
    required>

Poiché il Customer ID non segue un formato specifico, è possibile inserire qualsiasi ID purché il campo non sia vuoto.

Ad esempio:

• CUST-000001
• TEST-001
• 123456

Crea il Resolver come segue.

• Name: Checkout Customer ID
• Kind: Custom JavaScript

() => (document.querySelector('#customerId')?.value || '').trim()

Verifica che il Customer ID inserito venga mostrato in Output.

Questo valore verrà successivamente utilizzato per Party Identification e per associare il deviceId dell’utente anonimo al Customer ID del cliente conosciuto.

Creare il Resolver Order ID

Successivamente, prepareremo anche le informazioni sull’Order utilizzate dal Purchase Event come Resolver.

In TrailNest, quando viene eseguito Place Order, le informazioni sull’Order vengono memorizzate in Local Storage sotto:

trailnest_last_order

Contiene informazioni come:

{
    orderId: "TN-...",
    customer: {...},
    items: [...],
    total: ...
}

Crea un Resolver per recuperare l’Order ID.

• Name: Order ID
• Kind: Custom JavaScript

() => {
  try {
    const order =
      JSON.parse(
        localStorage.getItem('trailnest_last_order')
      );

    return order?.orderId || '';
  } catch (e) {
    return '';
  }
}

Quando viene valutato sulla pagina Order Confirmation, è possibile recuperare un Order ID come: TN-xxxxxxxxxxxxx

Il Local Storage viene utilizzato in questo caso poiché TrailNest è un semplice sito demo che deve trasferire le informazioni sull’Order create al Checkout alla pagina Order Confirmation.

Questo non significa che l’utilizzo del Local Storage sia obbligatorio per le implementazioni di Salesforce Personalization.

Creare il Resolver Order Total

Recupera il totale dell’ordine dalle stesse informazioni sull’Order.

• Name: Order Total
• Kind: Custom JavaScript

() => {
  try {
    const order =
      JSON.parse(
        localStorage.getItem('trailnest_last_order')
      );

    return Number(order?.total || 0);
  } catch (e) {
    return 0;
  }
}

Ad esempio, è possibile recuperare un totale ordine come: 188000

Questo valore verrà utilizzato come Total Value nel Purchase Event.

Creare i Resolver per gli Order Items

Infine, creeremo anche i Resolver per recuperare i dettagli dei prodotti acquistati nel Purchase Event.

In TrailNest, ogni prodotto mostrato su Order Confirmation viene restituito come elemento HTML in questo modo:

<div
    class="checkout-summary-item"
    data-product-id="TN-BP-003"
    data-quantity="1"
    data-price="79000">

L’aspetto sullo schermo è lo stesso di prima, ma per permettere a Sitemap Builder di recuperare i dettagli dell’item, l’elemento contiene:

• data-product-id
• data-quantity
• data-price

In seguito, specifica:

• .checkout-summary-item

come Line Items Selector del Purchase Event.

Sitemap Builder passa quindi ciascun elemento prodotto corrispondente al Resolver come $item.

Ad esempio, se ci sono tre prodotti:

1° .checkout-summary-item
→ $item

2° .checkout-summary-item
→ $item

3° .checkout-summary-item
→ $item

Il Resolver viene valutato una volta per ciascun prodotto.

Pertanto, creeremo tre Resolver per recuperare Product ID, Quantity e Price da $item.

① Order Item Product ID

Prima di tutto, recuperiamo il Product ID dell’item acquistato.

• Name: Order Item Product ID
• Kind: Custom JavaScript

Imposta il seguente codice in Custom JavaScript.

($item) => $item.attr('data-product-id') || ''

$item.dataset.productId recupera il valore di:

• data-product-id=”TN-BP-003″

② Order Item Quantity

Successivamente, recuperiamo la quantità acquistata.

• Name: Order Item Quantity
• Kind: Custom JavaScript

($item) => Number($item.attr('data-quantity') || 0)

Questo recupera il valore di data-quantity come Number.

③ Order Item Price

Infine, recuperiamo il prezzo unitario del prodotto.

• Name: Order Item Price
• Kind: Custom JavaScript

($item) => Number($item.attr('data-price') || 0)

Questo recupera il valore di data-price come Number.

※ $item viene passato dal Line Items Mapping del Purchase Event, quindi non è possibile visualizzare in anteprima il valore effettivo dal solo Resolver.

Con questo, il Purchase Event può recuperare ogni prodotto acquistato come singolo Line Item nel modo seguente.

• Line Items Selector
  → .checkout-summary-item
• Catalog Object ID
  → Order Item Product ID
• Quantity
  → Order Item Quantity
• Price
  → Order Item Price

TrailNest è un sito di test, quindi gli attributi data-* sono stati aggiunti all’HTML di Order Confirmation per facilitare il recupero dei valori da parte di Sitemap Builder.

Tuttavia, su un sito Web reale, potrebbe non essere possibile modificare l’HTML esclusivamente per Salesforce Personalization.

In quel caso, valuta di costruire i Line Items a partire da dati già disponibili sul sito, come:

• il DOM esistente
• dataLayer
• stato JavaScript
• Local Storage
• informazioni sull’Order lato Commerce

Resolver Creati in Questo Articolo

A questo punto, abbiamo preparato i Resolver di base necessari per TrailNest.

Informazioni sul Prodotto

• Product ID
• Product Name
• Product Price
• Product Quantity

Informazioni sul Profilo

• Checkout Email
• Checkout Customer ID

Informazioni sull’Order

• Order ID
• Order Total

Informazioni sugli Order Item

• Order Item Product ID
• Order Item Quantity
• Order Item Price

Abbiamo utilizzato i Resolver Built-in per i valori recuperabili dagli attributi data-* della pagina prodotto, e i Resolver Custom JavaScript per i valori recuperati da Form o Local Storage.

In altre parole:

• Attributo DOM
  → Resolver Built-in
• Valore inserito in un Form
  → Resolver Custom JavaScript
• Order in Local Storage
  → Resolver Custom JavaScript

Questo è il modo in cui li abbiamo utilizzati in maniera differenziata.

Che ve ne pare?

Nel prossimo articolo utilizzeremo gli Profile Attributes.

Utilizzando i seguenti valori recuperati in questo articolo:

• Checkout Email
• Checkout Customer ID

verificheremo come includerli in un Profile Event come:

• Indirizzo Email
  → Contact Point Email
• Customer ID
  → Party Identification

Questo ci permetterà di continuare a prepararci per associare successivamente il comportamento Web raccolto mentre l’utente era anonimo a un cliente conosciuto.

Questo è tutto per questo articolo.

Restate sintonizzati per altri tips su Salesforce Marketing Cloud! 😎

Nobuyuki Watanabe

---

Tradotto e adattato da SFMC Tips #356 : Personalization: Configuring Resolvers in Sitemap Builder di Nobuyuki Watanabe (@marketingcloudtips), pubblicato originariamente su Medium. Traduzione autorizzata dall’autore.