> For the complete documentation index, see [llms.txt](https://academy.gopersonal.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://academy.gopersonal.ai/developers/plataforma-ecommerce/sdk-integration-guide-for-e-commerce-websites.md).
# Guía de integración del SDK para sitios de e-commerce
Esta documentación es una guía detallada para integrar el SDK de gopersonal en un sitio de e-commerce. La integración es indispensable para habilitar contenido y recomendaciones personalizadas para tus clientes. Esta guía aplica especialmente si no estás utilizando una plataforma soportada como WooCommerce, Magento, Shopify, etc.
### Conceptos importantes
* **Requisito de integración custom**: la integración con el SDK de gopersonal es necesaria si tu plataforma de e-commerce no está soportada directamente.
* **Consideración para Single Page Applications (SPA)**: identificá si tu sitio es una Single Page Application, ya que aplican consideraciones específicas para SPA.
### Requisitos previos
Antes de comenzar el proceso de integración, asegurate de haber recibido un `clientId` único para cada ambiente (por ejemplo, desarrollo, testing y producción). Cada `clientId` está asociado a uno o más dominios. Podés configurar estas asociaciones en el dashboard de gopersonal, en la sección Integraciones.
### Pasos de instalación
Para habilitar las funcionalidades de personalización en tu sitio, seguí estos pasos de instalación en cada página donde quieras que ocurra la personalización. El proceso es similar a integrar Google Analytics: requiere insertar un script dentro de las etiquetas `` de tus páginas HTML.
1. **Instalación del script**: reemplazá `REPLACE_ME_CLIENT_ID` por tu `clientId` en el siguiente script y agregalo en la sección `` de tus páginas HTML.
Copiar
```
```
#### Ejemplos de configuración del contexto
Según el tipo de página, el parámetro `context` del script debe ajustarse. Estos son ejemplos para distintos tipos de página:
* **Home**:
Copiar
```
```
* **Página de detalle de producto (PDP)**:
Incluí el `product_id` en el `context` para las páginas de detalle de producto.
Copiar
```
```
* **Páginas de carrito y checkout**:
Para las páginas de carrito y checkout, incluí los ítems del carrito dentro del `context`.
Copiar
```
```
### Gestión de la autenticación del cliente
Si el cliente ya está autenticado, usá el siguiente JavaScript para loguearlo. El flag `param_updateCartFromCustomer` copia el carrito de la sesión anterior a la nueva.
* **Agregar el email del usuario**: si tenés disponible la dirección de email, podés incluirla en la información del login.
Copiar
```
window.gsSDK.login('customer_id', {email: 'email@company.com', param_updateCartFromCustomer: true});
```
* **Logout**:
Copiar
```
window.gsSDK.logout();
```
### Registro de interacciones
Trackear las interacciones de los usuarios con los productos es fundamental para la personalización. A continuación se detallan los métodos para registrar los distintos tipos de interacción.
#### Visualización de un producto
Cuando un usuario visualiza un producto, registrá la interacción de la siguiente manera, reemplazando `productId` por el ID real del producto.
Copiar
```
window.gsSDK.addInteraction({
"event": "view",
"item": 'productId'
});
```
#### Marcar un producto como favorito
Para registrar cuando un usuario marca un producto como favorito, usá el siguiente snippet:
Copiar
```
window.gsSDK.addInteraction({
"event": "like",
"item": 'productId'
});
```
#### Agregar un producto al carrito
Cuando se agrega un producto al carrito, registrá la interacción con datos como la cantidad y el precio:
Copiar
```
window.gsSDK.addInteraction({
"event": "cart",
"item": productId,
"quantity": 1,
"price": 100
});
```
#### Quitar un producto del carrito
Para registrar cuando se quita un producto del carrito, usá:
Copiar
```
window.gsSDK.addInteraction({
"event": "remove-cart",
"item": productId,
"quantity": 1,
"price": 100
});
```
#### Cambios de cantidad en el carrito
Es fundamental actualizar las interacciones cuando cambia la cantidad de un producto en el carrito. Usá la siguiente lógica para determinar si corresponde registrar una interacción de agregado o de eliminación según la cantidad nueva y la anterior:
Copiar
```
const oldQuantity;
const newQuantity;
if (newQuantity > oldQuantity){
window.gsSDK.addInteraction({
"event": "cart",
"item": productId,
"quantity": newQuantity - oldQuantity,
"price": 100
});
} else {
window.gsSDK.addInteraction({
"event": "remove-cart",
"item": productId,
"quantity": oldQuantity - newQuantity,
"price": 100
});
}
```
#### Vaciar el carrito
Para las plataformas de e-commerce que permiten vaciar el carrito, registrá la interacción de la siguiente manera:
Copiar
```
window.gsSDK.addInteraction({
"event": "clean-cart"
});
```
#### Compra finalizada
Una vez finalizada la compra, registrá el estado del carrito. Si conocés el ID de la transacción, incluilo como se muestra a continuación:
Copiar
```
window.gsSDK.addInteractionState('cart');
// Si se conoce el ID de la transacción
window.gsSDK.addInteractionState('cart', { "transactionId": "1"});
```