Capacidades

Las capacidades son ganchos de integración que su sitio web implementa para exponer funcionalidades adicionales, por ejemplo, definir una función que maneje la adición de un producto al carrito de compras para habilitar un botón de Añadir al Carrito dentro de un widget de Recomendaciones de Productos de Fanplayr.

Capacidades Disponibles

Capacidad	Descripción
addProductToCart	Botón "Añadir al Carrito" en los widgets de Recomendaciones de Productos
applyToCart	Botón "Aplicar Oferta" en los widgets de descuento/oferta
sessionOffer	Notificar a su tienda cuando Fanplayr presenta una oferta a un visitante

Las capacidades se registran en el objeto fanplayr.platform.capabilities dentro del callback fanplayr_ready, que se dispara una vez que los scripts de Fanplayr se han cargado.

window.fanplayr_ready = function () {
  // Registre las capacidades aquí
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.sessionOffer = function (event) {
    /* ... */
  };
};

---

Añadir Producto al Carrito

La capacidad addProductToCart permite que el widget de Recomendaciones de Productos de Fanplayr añada un producto directamente al carrito del visitante sin que este abandone la página.

Firma del controlador

interface AddProductEvent {
  /** ID del producto definido en el catálogo de Fanplayr */
  id: string
  /** Cualquier dato personalizado definido para el producto */
  customData?: Record<string, any>
}

fanplayr.platform.capabilities.addProductToCart = (event: AddProductEvent) => void | Promise<void>

El controlador recibe un objeto AddProductEvent que contiene el id del producto de su catálogo de Fanplayr. Se admite devolver una Promise: Fanplayr esperará a que se resuelva antes de volver a habilitar el botón del widget, lo que evita envíos duplicados. Su controlador es responsable de cualquier parámetro adicional del carrito, como la cantidad.

Ejemplo básico

Antes de salir en vivo

Este es solo un ejemplo. Debe reemplazar toda la llamada fetch con la lógica de la API de carrito de su propia tienda.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    // Reemplace esto con la API de carrito real de su tienda:
    return fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId: product.id })
    });
  };
};

Uso de customData

Si define atributos personalizados en los productos de su catálogo de Fanplayr (por ejemplo, IDs de variantes, SKUs o referencias internas), estos están disponibles en product.customData y pueden pasarse a su API de carrito.

---

Aplicar Oferta al Carrito

La capacidad applyToCart permite que los widgets de ofertas y descuentos de Fanplayr apliquen un código de cupón o promoción directamente al carrito del visitante.

No es lo mismo que Añadir Producto al Carrito

Esta capacidad maneja códigos de descuento/oferta (por ejemplo, FREESHIP), no productos. Consulte Añadir Producto al Carrito si desea integrar recomendaciones de productos.

Hay dos formas de implementar esta capacidad: un enfoque simple de redirección de URL, o un controlador personalizado para integraciones más complejas.

Opción 1 — Redirección de URL

Proporcione una applyToCartUrl como parte de su configuración de seguimiento de usuario. Incluya el marcador de posición %c donde se debe insertar el código de oferta.

{
  type: 'st',
  accountKey: '7e43c8cddccade2b95ee5286ba89758a',
  applyToCartUrl: 'https://example.com/applyOffer.php?code=%c',
  data: {
    // User tracking data
  }
}

Cuando un visitante activa la oferta, Fanplayr redirige el navegador a esta URL con %c reemplazado por el código de oferta (por ejemplo, FREESHIP), lo que resulta en:

https://example.com/applyOffer.php?code=FREESHIP

Su endpoint debe entonces:

1. Aplicar el código de oferta especificado al carrito.
2. Redirigir al usuario a la página del carrito.
3. Buena práctica: Si el código no puede aplicarse, muestre un mensaje informativo explicando el motivo.

Opción 2 — Controlador personalizado

Si la aplicación de un código requiere lógica del lado del cliente (por ejemplo, llamar a una API de carrito de JavaScript), registre una función de controlador en su lugar.

Firma del controlador

interface AddOfferEvent {
  /** El código de oferta/cupón a aplicar */
  code: string
}

fanplayr.platform.capabilities.applyToCart = (event: AddOfferEvent) => void | Promise<void>

Ejemplo básico

Antes de salir en vivo

Este es solo un ejemplo. Debe reemplazar todo el cuerpo del controlador con la lógica de su propia tienda para aplicar un código de oferta.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    // Reemplace esto con la lógica de su tienda para aplicar el código de oferta al carrito
    console.warn('Fanplayr: applyToCart capability is not implemented');
  };
};

Ejemplo asíncrono

Devolver una Promise le indica a Fanplayr que espere a que se resuelva antes de volver a habilitar la interfaz de usuario del widget, evitando que el controlador se active varias veces mientras su solicitud está en curso.

Antes de salir en vivo

Este es solo un ejemplo. Debe reemplazar toda la llamada fetch con la lógica de la API de carrito de su propia tienda.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = async function (event) {
    // Reemplace esto con la API de carrito real de su tienda:
    await fetch('/api/apply-code-to-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};

Legado: callback de completado

Las versiones anteriores de esta capacidad admitían un callback doneFn opcional como segundo argumento en lugar de una Promise. Esto todavía se admite para la compatibilidad con versiones anteriores, pero el enfoque de Promise anterior es preferido para nuevas implementaciones.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event, doneFn) {
    $.ajax({
      type: 'GET',
      url: '/api/apply-code-to-cart',
      data: { code: event.code },
      complete: function () {
        doneFn();
      }
    });
  };
};

---

Oferta de Sesión

La capacidad sessionOffer forma parte de la característica Ofertas de Sesión de Fanplayr, que ayuda a evitar que usuarios no autorizados reclamen códigos de descuento fuera de una sesión de Fanplayr.

Cuando Fanplayr presenta una oferta a un visitante, invoca su controlador sessionOffer con el código de oferta. Su controlador es responsable de marcar el código como válido durante la duración de la sesión del visitante, para que su tienda pueda verificarlo antes de aplicarlo al carrito.

Alternativa basada en URL

Si prefiere un enfoque del lado del servidor en lugar de un controlador JavaScript, puede proporcionar una sessionOfferUrl en su configuración de seguimiento de usuario. Consulte Ofertas de Sesión para obtener todos los detalles.

Firma del controlador

interface SessionOfferEvent {
  /** El código de oferta que se presenta al visitante */
  code: string
}

fanplayr.platform.capabilities.sessionOffer = (event: SessionOfferEvent) => void | Promise<void>

Se admite devolver una Promise; si la Promise se rechaza, Fanplayr tratará la oferta de sesión como fallida y podría reintentarla en una llamada posterior. Si la Promise se resuelve, o si no se devuelve ninguna Promise, la oferta se considera registrada con éxito.

Ejemplo

Antes de salir en vivo

Este es solo un ejemplo. Debe reemplazar el cuerpo del controlador con la lógica de su propia tienda para marcar un código de oferta como válido para la sesión actual.

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.sessionOffer = async function (event) {
    // Reemplace esto con la lógica de su tienda para marcar el código como válido
    // para la sesión actual del visitante:
    await fetch('/api/session-offers/allow', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};