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 <head> 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 <head> de tus páginas HTML.

   Copiar

   <script>
   async function initializeGSSDK() {
       window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
           provider: 'Custom',
           context: { pageType: 'home' } // Este contexto varía según la página
       });
   }
   var gsSDKScript = document.createElement('script');
   gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
   gsSDKScript.onload = initializeGSSDK;
   document.head.appendChild(gsSDKScript);
   </script>

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

  <script>
  async function initializeGSSDK() {
      window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
          provider: 'Custom',
          context: { pageType: 'home' }
      });
  }
  var gsSDKScript = document.createElement('script');
  gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
  gsSDKScript.onload = initializeGSSDK;
  document.head.appendChild(gsSDKScript);
  </script>

• Página de detalle de producto (PDP):

  Incluí el product_id en el context para las páginas de detalle de producto.

  Copiar

  <script>
  async function initializeGSSDK() {
      window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
          provider: 'Custom',
          context: { pageType: 'product_detail', product_id: '123' } // Reemplazá '123' por el ID real del producto
      });
  }
  var gsSDKScript = document.createElement('script');
  gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
  gsSDKScript.onload = initializeGSSDK;
  document.head.appendChild(gsSDKScript);
  </script>

• Páginas de carrito y checkout:

  Para las páginas de carrito y checkout, incluí los ítems del carrito dentro del context.

  Copiar

  <script>
  async function initializeGSSDK() {
      var context = { pageType: 'cart', cart_items: [{ product_id: '1', quantity: '1' }] };
      window.gsSDK = await new window.GSSDK.default('REPLACE_ME_CLIENT_ID', {
          provider: 'Custom',
          context: context
      });
  }
  var gsSDKScript = document.createElement('script');
  gsSDKScript.src = 'https://sdk.gopersonal.ai/gs-sdk.js';
  gsSDKScript.onload = initializeGSSDK;
  document.head.appendChild(gsSDKScript);
  </script>

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: '[e-mail]', 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"});