Guia tècnica per personalitzar one-to-one l'experiència al teu eCommerce amb el SDK de Pleasepoint.

El SDK JS de Pleasepoint és l'eina essencial per als desenvolupadors que personalitzaran one-to-one l'experiència d'usuari en temps real a l'eCommerce. Amb el SDK obtindràs accés en temps real als models de machine learning i deep learning desplegats a la plataforma de Pleasepoint. Aquests models, meticulosament entrenats, estan dissenyats per adaptar l'experiència de l'usuari segons les seves preferències i patrons de consum mentre naveguen pel lloc web.

Una de les funcionalitats més importants del SDK JS de Pleasepoint és també la seva capacitat de registrar els esdeveniments d'interacció de l'usuari durant la navegació. Amb els esdeveniments d'interacció proporcionaràs un context valuós a la xarxa neuronal per analitzar i entendre el comportament de l'usuari abans de fer una compra.

En capturar i processar aquests esdeveniments de manera efectiva, es millora significativament la capacitat de personalització, cosa que es tradueix en una experiència més rellevant i satisfactòria per a l'usuari, i s'obté així una millor conversió.

Així doncs, és crucial comprendre en detall com implementar i aprofitar al màxim les capacitats del SDK de Pleasepoint. Per aquest motiu, hem preparat una guia completa que cobreix tots els aspectes tècnics i funcionals del SDK. Si t'interessa explorar més a fons el SDK de Pleasepoint, aquesta és la documentació.

Aquests són els continguts de l'article:

Instal·lació del SDK.
Introducció al registre d'esdeveniments.
Definició dels tipus d'esdeveniments.
Registre d'esdeveniments per pàgina del site.
Mostrar recomanacions one-to-one en temps real.
Implementació de test A/B.

Si vols continuar aprofundint en l'ús del SDK de Pleasepoint et recomanem aquests articles:

1. Instal·lació del SDK.

Aquest és el script que has d'afegir abans del tancament del body al teu eCommerce. Necessites que aquest script s'incrusti a totes les pàgines.

<script type="module" src="https://platform.pleasepoint.com/pleasepoint-widgets/index.js"></script>

Així pots comprovar que el SDK de Pleasepoint està disponible via JavaScript:

function pleasepointWidgetReady() {
    // window.pleasepointWidget is available
}
if (window.pleasepointWidget) {
    pleasepointWidgetReady();
} else {
    window.addEventListener('pleasepointWidgetReady', pleasepointWidgetReady);
}

2. Introducció al registre d'esdeveniments.

És fonamental registrar correctament els esdeveniments generats a la pàgina per mesurar de manera precisa el rendiment dels nostres motors de recomanació. És important tenir en compte que:

El registre d'esdeveniments sempre té com a mínim una referència de producte, que són elements angulars del motor i dels esdeveniments.
Per mesurar correctament el rendiment, cal registrar esdeveniments de la mateixa pàgina (Externs al SDK, com podria ser impressió de productes, llistats de productes o esdeveniments d'afegir a la cistella), ja que el SDK ja registra els esdeveniments de manera nativa.

Una crida al registre d'esdeveniments té el format següent:

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'impression' | 'click' | 'add_to_cart' | 'pdp' | 'checkout' | 'execute_checkout' ,
	source: {
		page: '',
		block: ''
	}
});

Els paràmetres que rep la funció són:

AccountId i apiId: identificadors de l'entorn de Pleasepoint Platform i de l'API d'esdeveniments.
Products: array d'identificadors de productes.
UserReferenceId o email: identificador de l'usuari o email (Quan l'usuari hagi iniciat sessió, en cas contrari es passa un valor null).
SessionId: identificador de la sessió associada a la visita de l'usuari, generat per l'aplicació la primera vegada que un usuari accedeix al lloc web. També es pot fer servir el PHPSESSID (Llocs web PHP) o també la cookie _ga en llocs amb Google Analytics activat.
EventType: tipus d'esdeveniment. Els valors permesos són: impression, click, plp, pdp, add_to_cart, checkout, execute_checkout.
Source: origen de l'esdeveniment, objecte amb 2 claus:
- Page: pàgina d'origen de l'esdeveniment generat. Per exemple: home, pdp (Pàgina de producte), plp (Pàgina de llistat de productes), cart.
- Block: bloc origen dels esdeveniments generats, text lliure. És opcional, però es pot fer servir per distingir millor l'origen dels esdeveniments dins de la mateixa pàgina Per exemple: Dins de la page Home, podríem tenir diversos blocs: ofertas, mascomprados, noteolvides, libros_destacados…

3. Definició dels tipus d'esdeveniments.

En l'àmbit de la personalització de l'experiència en temps real a l'eCommerce, comprendre el comportament i les interaccions dels usuaris és fonamental perquè els models de deep learning ofereixin continguts cada vegada més rellevants. Per aconseguir-ho, és crucial registrar els esdeveniments que proporcionen el context complet de la interacció de l'usuari abans de fer la compra en línia.

Els esdeveniments més rellevants que registrarem són les impressions de productes, els clics a un producte, les visites a les pàgines de producte, l'afegir un producte a la cistella, l'inici del procés de pagament i la compra finalitzada. Cadascun d'aquests esdeveniments ens ofereix informació valuosa sobre com els usuaris interactuen amb el nostre eCommerce, des del primer contacte fins a la conversió final.

Esdeveniment "Impressió".

eventType: impression

Definició: Són visualitzacions d'ítems tipus producte dins de qualsevol pàgina i llistat de productes a l'e-commerce.
Quan cal registrar-lo?: Cada ítem que es mostri als llistats de productes hauria d'anar acompanyat d'un esdeveniment de tipus impression. No cal registrar un per un els esdeveniments, es pot fer per blocs en una sola petició.
Paràmetres importants: És recomanable emplenar el paràmetre page del source per distingir d'on vénen les impressions de producte.

Esdeveniment "Clic a producte".

eventType: click

Definició: Registra el clic d'un usuari a un enllaç d'un ítem de producte que el dirigeixi a la pàgina de producte en particular.
Quan cal registrar-lo?: A cada enllaç del producte (Imatge, nom, etc.) que redirigeixi l'usuari a la pàgina d'aquest producte.
Paràmetres importants: És recomanable emplenar el paràmetre page del source per distingir d'on vénen les impressions de producte.

Esdeveniment "Visita de pàgina de producte".

eventType: pdp

Definició: Indica quan s'ha visualitzat una pàgina específica de producte.
Quan cal registrar-lo?: S'ha de registrar un esdeveniment per cada pàgina de producte oberta per l'usuari.
Paràmetres importants: Contindrà una sola referència de producte, que és la pròpia de la pàgina vista.

Esdeveniment "Afegir a la cistella".

eventType: add_to_cart

Definició: Registra l'acció d'afegir un producte a la cistella de la compra.
Quan cal registrar-lo?: A qualsevol enllaç de l'e-commerce que afegeixi un producte a la cistella de la compra. Es pot centralitzar a la funció d'afegir a la cistella si és comuna a totes les pàgines.
Paràmetres importants: En aquest cas, els paràmetres page i block es poden combinar per ubicar exactament l'esdeveniment.

Esdeveniment "Inici de la compra".

eventType: checkout

Definició: Informa el sistema que s'inicia la tramitació de la compra.
Quan cal registrar-lo?: S'ha de registrar un esdeveniment de checkout per inici de tramitació de la compra, que contingui els diferents productes afegits prèviament a la cistella. Es pot implementar a la funció que condueix al procés de pagament des de la cistella.

Esdeveniment "Compra realitzada".

eventType: execute_checkout

Definició: Informa el sistema que s'ha tramitat la compra correctament i que, per tant, s'ha creat un ticket.
Quan cal registrar-lo?: Un cop s'ha efectuat el pagament, s'ha de fer el registre de l'esdeveniment amb el llistat de productes comprats. Es pot implementar a la pàgina de confirmació de la comanda.

4. Registre d'esdeveniments per pàgina del site.

Resulta fonamental identificar i registrar els esdeveniments típics que es produeixen a cadascuna de les pàgines clau d'un lloc d'eCommerce. Aquestes pàgines inclouen la pàgina d'inici, les pàgines de llistes de productes, les pàgines de detall de productes, la cistella de la compra i la pàgina de confirmació de la comanda.

En aquesta guia t'expliquem els esdeveniments més rellevants que s'han de registrar a cadascuna d'aquestes pàgines, en destaquem la importància i com poden proporcionar informació valuosa per millorar l'experiència de l'usuari i optimitzar el rendiment de la personalització one-to-one al teu eCommerce.

Pots accedir a la documentació completa sobre la funció de registre d'esdeveniments en aquest enllaç.

Aquesta és la taula resum d'esdeveniments per pàgina:

	Impressió	Clic a producte	Visita PDP	Afegir a la cistella	Inici tramitació	Confirmació comanda
Home	Sí	Sí	No	Sí	No	No
Pàgines de llistes de productes (PLPs)	Sí	Sí	No	Sí	No	No
Pàgines de detall de producte (PDPs)	Sí	Sí	Sí	Sí	No	No
Pàgines de cistella	Sí	Sí	No	Sí	Sí	No
Confirmació de comanda	No	No	No	No	No	Sí

Recordem que només s'han de registrar els esdeveniments externs al SDK de recomanació, ja que el SDK gestiona els seus esdeveniments internament.

Registre d'esdeveniments a la pàgina home.

A la Home de l'e-commerce haurem de registrar:

Impressió: Impressions de cada producte que es mostra.
Clic: Qualsevol clic en un producte.
Afegir a la cistella: Si el disseny inclou un botó d'afegir a la cistella per al producte des del llistat sense haver de passar per la seva pàgina de producte.

Aquesta seria l'estructura de la crida a la funció JavaScript del SDK de Pleasepoint per registrar els esdeveniments a la home.

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'impression' | 'click' | 'add_to_cart',
	source: {
		page: 'home',
		block: 'XXXX'
	}
});

El paràmetre block de l'apartat source és opcional, però es pot fer servir per distingir millor l'origen dels esdeveniments dins de la mateixa pàgina.

Registre d'esdeveniments a les pàgines de llistes de productes (PLPs).

A les pàgines de llistat de producte s'han de registrar bàsicament els mateixos esdeveniments que a la home, ja que generalment són molt semblants.

Impressió: Impressions de cada producte que es mostra.
Clic: Qualsevol clic en un producte.
Afegir a la cistella: Si el disseny inclou un botó d'afegir a la cistella per al producte des del llistat sense haver de passar per la seva pàgina de producte.

Aquesta seria l'estructura de la crida a la funció JavaScript del SDK de Pleasepoint per registrar els esdeveniments a les PLPs.

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'impression' | 'click' | 'add_to_cart',
	source: {
		page: 'plp',
		block: 'XXXX'
	}
});

Registre d'esdeveniments a les pàgines de detall de producte (PDPs).

L'accés a la pàgina de producte és un esdeveniment important en l'experiència de compra en un eCommerce. A cada pàgina de producte s'han de registrar els esdeveniments següents:

PDP: Aquest serà l'esdeveniment per al producte de la pàgina que s'està visualitzant.
Impressió: Impressions d'altres productes que es mostrin si hi ha algun bloc de productes relacionats o similar.
Clic: Si es mostren altres productes a la pàgina, qualsevol clic en un d'ells s'ha de registrar amb l'esdeveniment click.
Afegir a la cistella: Quan es faci clic al botó d'afegir a la cistella de la pàgina de producte. Si es mostren altres productes i el disseny inclou un botó d'afegir a la cistella per a aquests des del llistat sense haver de passar per la seva pàgina de producte.

Aquesta seria l'estructura de la crida a la funció JavaScript del SDK de Pleasepoint per registrar els esdeveniments a les PDPs.

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'pdp' | 'impression' | 'click' | 'add_to_cart',
	source: {
		page: 'pdp',
		block: 'XXXX'
	}
});

Registre d'esdeveniments a la cistella.

A la pàgina que mostra el contingut de la cistella, s'hauran d'implementar els esdeveniments següents:

Impressió: Si es mostren altres productes que no siguin els propis de la cistella, impressions de cada producte que es mostra.
Clic: Qualsevol clic en un producte que no sigui dels propis de la cistella.
Afegir a la cistella: Si es mostren altres productes per afegir a la cistella dins de la mateixa cistella, s'ha de registrar aquest esdeveniment quan s'incloguin.
Inici de tramitació de la comanda: S'ha de registrar un esdeveniment de checkout quan es premi el botó de tramitar la comanda, típicament just abans d'accedir a la passarel·la de pagament. En aquest esdeveniment s'han d'incloure tots els productes que hi hagi a la cistella. per a aquest esdeveniment no cal emplenar res del paràmetre source.

Aquesta seria l'estructura de la crida a la funció JavaScript del SDK de Pleasepoint per registrar els esdeveniments a les PDPs.

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'impression' | 'click' | 'add_to_cart' | 'checkout',
	source: {
		page: 'cart',
		block: 'XXXX'
	}
});

Registre d'esdeveniments a la confirmació de la comanda.

Un cop fet el pagament i, per consegüent, havent confirmat la comanda, s'ha de registrar aquest esdeveniment a la pàgina de confirmació.

Confirmació de la comanda: Es registra aquest tipus d'esdeveniment amb cadascun dels productes comprats.

Aquesta seria l'estructura de la crida a la funció JavaScript del SDK de Pleasepoint per registrar l'esdeveniment de confirmació de la comanda.

pleasepointWidget.registerEvent({
	accountId: 'XXXXXXXXXXXXX',
	apiId: 'XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX',
	products: [id_product1, id_product2],
	userReferenceId: 'user_id', /* OR */ email: 'user@email',
	sessionId: id_session,
	eventType: 'execute_checkout',
	source: {
		page: '',
		block: ''
	}
});

Ara és el moment de veure com inserir les recomanacions personalitzades one-to-one en qualsevol espai de l'eCommerce fent servir el SDK de Pleasepoint. El registre d'esdeveniments d'interacció amb el widget de recomanació és totalment transparent per a l'usuari i es fa de manera automàtica.

Pots accedir a la documentació completa en aquest enllaç.

El widget Pleasepoint és un component web que es pot incorporar al teu lloc web o eCommerce per mostrar recomanacions personalitzades. Es pot inserir mitjançant HTML o JavaScript. Els atributs en HTML són kebab-case, mentre que en JavaScript són camelCase.

Aquesta és l'estructura bàsica del widget:

Ús en HTML:

<pleasepoint-recommendation
    account-id="my_account_id"
    num-recommendations="4"
    cols="2"
    show-slider <!-- optional, default false -->
    <!-- engine-specific attributes -->
    business-rule=""
    business-rule-params='{"param1": ["value1", "value2"]}' <!-- optional -->
    user-reference-id="" <!-- OR --> email=""
    session-id=""
    event-source-page="" <!-- optional -->
    event-source-block="" <!-- optional -->
></pleasepoint-recommendation>

Ús en JS:

const widget = pleasepointWidget.create('recommendation', {
    accountId: 'my_account_id',
    numRecommendations: 4,
    cols: 2,
    showSlider: true, // optional, default false
    // engine-specific attributes
    businessRule: '',
    businessRuleParams: {"param1": ["value1", "value2"]}, // optional
    userReferenceId: '', /* OR */ email: '',
    sessionId: '',
    eventSourcePage: '', // optional
    eventSourceBlock: '', // optional
});

// widget is a regular HTML element, insert it into the page as usual
// for example:
document.body.appendChild(widget);

Aquests són els paràmetres principals del widget:

Account id: Identificador del teu compte de Pleasepoint.
Num. recommendations: Nombre de recomanacions que proporcionarà la xarxa neuronal de recomanació.
Cols: Nombre de columnes en què mostrar la recomanació.
Show slider: Camp opcional; en cas que s'activi es mostraran tots els productes en una mateixa fila amb un slider per poder lliscar i veure tots els productes. En cas contrari es mostraran les recomanacions a les files necessàries segons el nombre de recomanacions i el de columnes.
Engine: Motor de recomanació one-to-one. Aquest paràmetre varia segons el model de recomanació que es vulgui fer servir.
Bestsellers engine: Motor de recomanació per als bestsellers. Aquest motor es fa servir com a recomanació alternativa si no està disponible la recomanació one-to-one desitjada.
Business rule: Regla de negoci que volem aplicar a la recomanació. Amb la regla de negoci portem l'estratègia comercial a la personalització.
Business rule params: Paràmetres dinàmics per a la regla de negoci. Per hiperpersonalitzar l'experiència aconsellem connectar els models de CLV i buyer-persona amb els paràmetres de les regles de negoci. Actuen com a variables de la regla de negoci establerta.
Secondary business rule: Regla de negoci alternativa. Quan es defineix una regla secundària és la que es fa servir en el cas de recomanar amb el model de bestsellers. Si no està definida, fa servir la mateixa regla de negoci que la regla principal.
Secondary business rule params: Paràmetres dinàmics per a la regla de negoci secundària.
User reference id: Identificador de l'usuari quan ha iniciat sessió. Aquest camp no és necessari si tenim l'email de l'usuari.
User email: Email de l'usuari quan ha iniciat sessió. Aquest camp no és necessari si tenim l'id d'usuari.
Session id: Identificador de la sessió d'usuari. Aquest identificador només es fa servir per al registre d'esdeveniments; en cap cas Pleasepoint no afegeix cap cookie per identificar l'usuari en el temps.
Event source page: Valor que identifica el tipus de pàgina en què es mostra la recomanació.
Event source block: Valor que identifica el bloc de la pàgina en què es mostra la recomanació.

A la documentació tens la informació completa dels paràmetres per a la recomanació one-to-one o bestsellers, item-item i ranking one-to-one.

6. Implementació de test A/B.

Per habilitar el test A/B al widget de Pleasepoint hem d'incloure el paràmetre en què indiquem el percentatge de sessions que volem marcar com a B durant el test. D'aquesta manera, tota sessió d'usuari es classifica com a A o com a B a l'inici de la seva sessió i rep tota l'experiència segons el cas definit.

Així hauries de carregar el script per activar el test A/B:

<script type="module" src="https://platform.pleasepoint.com/pleasepoint-widgets/index.js" pleasepoint-ab-test-percent="5"></script>

En aquest exemple el 95% de les sessions d'usuari es classificaran per veure la recomanació de productes personalitzades, mentre que el 5% restant veurà els productes seleccionats per al cas b.

Fent servir productes per defecte.

Una de les opcions per al test A/B és que el cas B mostri els productes per defecte seleccionats a mà o amb el sistema que sigui per part de l'eCommerce.

Per activar aquesta funcionalitat has d'afegir el paràmetre de productes per defecte al test amb aquest paràmetre:

<!-- HTML -->
ab-test-default-products="['prod1','prod2']"

// JS
abTestDefaultProducts: ['prod1','prod2']

Fent servir la recomanació de bestsellers.

Una bona pràctica és fer el test A/B utilitzant el model de bestsellers per a la recomanació. D'aquesta manera estàs mesurant quin impacte té la personalització de l'experiència respecte a mostrar els productes que més tracció tenen en cada moment.

Per fer servir aquest model de recomanació al test A/B has de seguir aquests passos:

Assegurar-te de no incloure el paràmetre de productes per defecte.
Assegurar-te d'haver inclòs el paràmetre de best-sellers-engine a les opcions de configuració.

Gràcies a l'ús de la funcionalitat d'A/B testing del SDK de Pleasepoint podràs activar els experiments que necessitis de manera ràpida sense necessitat d'incloure més eines.

En cas que ja tinguis una eina de test A/B pots fer servir el SDK de Pleasepoint des de la mateixa eina de test que tens desplegada sense necessitat de fer servir aquesta funcionalitat.

No dubtis a contactar amb el nostre equip de suport si tens algun dubte en la implementació de la personalització one-to-one.