Parámetros, integraciones y ejemplos con JavaScript (SDK)

Última actualización:

Prisma Campaigns provee una librería que incluye un conjunto de controles para realizar la integración utilizando JavaScript. Se recomienda emplear esta estrategia en casos que involucren aplicaciones web (tanto de escritorio como móviles) y otras soluciones desarrolladas a partir de frameworks con soporte para JavaScript (Phonegap/Cordova y Titanium, por nombrar dos ejemplos). De esta forma, no es necesario recurrir a ningún otro recurso externo para garantizar el acople correcto de los canales web.

Instalar el SDK

El primer paso para emplear la librería en un entorno web consiste en insertar el siguiente código dentro del elemento <body>:

<script type='text/javascript' src='http://SERVER:PORT/sdk/javascript/prisma.js'></script>
<script type = "text/javascript" >
      prisma.load(SERVER, PORT, APP_TOKEN, CUSTOMER_ID, INTEGRATIONS, PROTOCOL, OPTIONS);
</script>

Las variables SERVER, PORT y APP_TOKEN corresponden a los datos particulares de cada aplicación que se pueden obtener desde Settings/Applications, mientras que CUSTOMER_ID y el vector INTEGRATIONS corren por cuenta de la persona encargada de la integración. Si en esta sección se selecciona el canal destino, se podrá acceder al código de integración con los valores precargados.

Acceder a los datos de integración

La siguiente tabla incluye más detalles sobre cada uno de los parámetros de integración:

Parámetro Tipo de dato Requerido Descripción
SERVER string Sí Nombre del servidor donde está instalado el servicio de Prisma
PORT string Sí Puerto de escucha
APP_TOKEN string Sí Token de acceso para la aplicación actual
CUSTOMER_ID string Sí Identificador de cliente (si está disponible) o una cadena vacía ("") en caso contrario
INTEGRATIONS vector Sí Vector conteniendo el conjunto de placeholders a integrar en la página actual.
PROTOCOL string No Protocolo de conexión (http o https) dependiendo si se cuenta o no con acceso vía SSL
OPTIONS string No Parámetros opcionales de configuración de la integración, callbacks y otros elementos

Es importante destacar que este código cargará la librería de forma asincrónica, por lo que el sitio cargará rápidamente a pesar de la dependencia.

Placeholders a integrar

En esta sección se describen las claves permitidas en cada elemento del vector INTEGRATIONS:

Clave Tipo de dato Requerido Descripción
placeholderId string Sí El identificador del placeholder según esté configurado en Prisma Campaigns
elemendId string Sí Identificador del elemento presente en el código HTML donde se cargarán los banners para el placeholder
unrolled boolean No En caso de que el placeholder soporte varias campañas, este parámetro indica si se mostrarán todas de manera simultánea (desenrrollado) o no. El valor por defecto es false.
fallbackUrl string No URL completa que se desee utilizar en caso que la plataforma de campañas no esté disponible
context Object No Contexto particular de integración del placeholder que sirve para filtrar las campañas que califican
isolated boolean No Para los casos de banners HTML donde el estilo pueda verse afectado, este parámetro permite desplegar el banner en un iframe aislado. El valor por defecto es true.

Ejemplo 1 - Inicialización con tres placeholders distintos integrados:

<script type='text/javascript'>
   prisma.load('localhost', '443', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
      "137-W", [
                {placeholderId: "MainHomeBanner", elementId: "banner_flash"},
                {placeholderId: "RightHomeBanner", elementId: "banner_right"},
                {placeholderId: "LeftHomeBanner", elementId: "banner_left"}
                ],
                 "https:");
</script>

Ejemplo 2 - Integración de un solo placeholder en modo carrusel desenrollado y empleando contexto de filtrado:

<script type='text/javascript'>
   prisma.load('localhost', '443', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
      "137-W", [
                {placeholderId: "PromocionesHome",
                    context: {"productId" : "1234"},
                    unrolled : true,
                    elementId : "promo_list"}
                ],
                 "https:");
 </script>

Nota: En los ejemplos anteriores se utiliza el valor fijo 137-W como identificador de cliente. Para realizar la integración en un ambiente de producción, este valor debe ser cargado en forma dinámica para cada cliente en particular.

Parámetros opcionales

En esta sección se describen las claves permitidas en cada elemento del vector OPTIONS:

Clave Tipo de dato Descripción
onLoaded function Callback que se ejecuta una vez finalizada la inicialización
onLoadFailed function Callback que se invoca si ocurre algún error en la inicialización
onRedirect function Callback que se dispara en caso de que haya una redirección en el funnel de conversión
onPopup function Callback que permite controlar el despliegue de popups
storageType string Determina el tipo de storage que se utilizará para almacenar información de la navegación (local o cookies, siendo este último el valor por defecto)
reloadPopupsOnReset boolean Determina si los popups se deben mostrar nuevamente después de que se recargue la integración (luego de una conversión, por ejemplo), siendo false su valor por defecto
language string Determina el lenguaje a utilizar para la internacionalización de los textos en la integración, siendo es el valor por defecto
useTranslator boolean Determina si se realizará la internacionalización de los textos en la integración (true por defecto)
channel string Determina el canal que se está integrando (web por defecto)
platform string Determina la plataforma en la que se está ejecutando la integración, siendo el nombre del navegador su valor por defecto (chrome, firefox, etc)

A continuación se ilustra el uso de las funciones onLoaded, onLoadFailed, y onRedirect.

onLoaded

Esta función recibe como parámetro los banners disponibles para el cliente en cuestión:

<div id="container"></div>

<script type='text/javascript'>
var onLoaded = function(banners) {
    console.log("La carga de Prisma Campaigns finalizó correctamente");
};

prisma.load('campaigns.bank.com', '80', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
            "137-W", [{"placeholderId": "MainBanner", "elementId": "container"}],
            "http:", {onLoaded: onLoaded});
</script>

onLoadFailed

En este caso, el parámetro opcional error indica el error de la carga de la integración y posee los siguientes atributos:

Clave Tipo de dato Descripción
data string Información sobre el error
status string Código de respuesta HTTP 
<div id="container"></div>

<script type='text/javascript'>
var onLoadFailed = function(error) {
    console.log("Hubo un error en la inicialización de la integración de Prisma Campaigns");
};

prisma.load('campaigns.bank.com', '80', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
            "137-W", [{"placeholderId": "MainBanner", "elementId": "container"}],
            "http:", {onLoadFailed: onLoadFailed});
</script>

onRedirect

Esta función recibe como parámetro la URL a la que se desea redirigir:

<div id="container"></div>

<script type='text/javascript'>
var onRedirect = function(url) {
    console.log("Será redirigido al sitio" + url);
};

prisma.load('campaigns.bank.com', '80', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
            "137-W", [{"placeholderId": "MainBanner", "elementId": "container"}],
            "http:", {onRedirect: onRedirect});
</script>

Ejemplos

En esta sección se incluyen casos comunes de uso con un breve detalle para su implementación. Aunque no existen restricciones con respecto al elemento HTML en donde se desplegarán los banners, por lo general se tratará de <div>.

Acceso público anónimo

En este escenario se dispone de un sitio público donde existe un único placeholder disponible (Portal - Main Banner) a mostrar en mainbanner y un cliente sin identificar, por lo que el parámetro CUSTOMER_ID se envía vacío.

<script type = "text/javascript">
prisma.load("campaigns.bank.com", "80", "175b18e2-08f2-43c2-953a-91f370a0fe23",
            "", [{placeholderId : "Portal - Main Banner", elementId : "mainbanner"}]);
</script>

Acceso identificado

Cuando la persona que se encuentra navegando el sitio es un cliente conocido se debe incluir el ID correspondiente como parámetro al método load. En el código que aparece a continuación se asume que este dato se encuentra disponible en session.customer_id y que las imágenes se mostrarán en los elementos identificados por left_banner y right_banner:

<script type = "text/javascript">
prisma.load("campaigns.bank.com", "80", "175b18e2-08f2-43c2-953a-91f370a0fe23", session.customer_id,
            [{placeholderId : "Position - Left", elementId: "left_banner"},
            {placeholderId : "Position - Right", elementId: "right_banner"}]);
</script>

Lista de Campañas

Luego de llamar a load según se explica en los apartados anteriores, se pueden obtener todas las campañas activas para un cliente determinado mediante activeCampaigns. La sintaxis de esta función y la lista de los parámetros disponibles se muestra en el siguiente detalle:

activeCampaigns(customerId, category, group, fnResults)
Parámetro Tipo de dato Requerido Descripción
customerId string Sí Identificador de cliente (si está disponible) o una cadena vacía ("") en caso contrario
category string No Parámetro opcional que sirve para filtrar campañas por categoría
group string No Parámetro opcional que sirve para filtrar campañas por grupo
fnResults function No Función a ser invocada de manera asincrónica al obtener los resultados

La función fnResults recibe la lista de campañas con los siguientes datos: name, category, group, customOffer y funnelUrl. Utilizando este recurso es posible obtener, por ejemplo, el nombre de las campañas en cuestión:

prisma.client.activeCampaigns("137-W", "Ventas","Hipotecarios",
function (campaigns) {
    for (var i = 0 ; i < campaigns.length; i++) {
        console.log(campaigns[i].name);
    }
});

De la misma forma, se puede iniciar el funnel de conversión para una campaña determinada en una nueva ventana:

prisma.client.activeCampaigns("137-W", "Ventas","Hipotecarios",
function (campaigns) {
    for (var i = 0 ; i < campaigns.length; i++) {
        if (campaigns[i].customOffer.tasaHipotecaria != undefined) {
            campaigns[i].startFunnel();
            break;
        }
    }
});

En el caso puntual que aparece arriba, se buscan las campañas de ventas hipotecarias y se dispara el funnel de la más prioritaria que tenga definido el campo tasaHipotecaria.

Carrusel personalizado

Mediante la función onLoaded, se pueden crear banners empleando controles o componentes a medida distintos de los provistos por el SDK. Para lograr esto, se deben tener en cuenta los siguientes puntos:

  1. El parámetro elementId que indica el lugar donde crear el banner debe tener el valor null.

  2. La función onLoaded recibe la lista de banners descargados en forma de diccionario, donde cada clave es el identificador de placeholder.

Es importante aclarar que cada valor retornado contiene una lista de imágenes en el atributo images, en caso que más de una campaña coincida. El siguiente paso consiste en mostrar el banner o imagen en cualquier elemento de la página que se desee utilizando el método show

<div id="my-parent"></div>

<script type='text/javascript'>
var onLoaded = function(banners) {
    var carouselParent = document.getElementById("my-parent");
    var prisma = this;
          var banner = banners["MainBanner"];
          for (var i = 0; i < banner.images.length; i++) {
              var image = banner.images[i];
              image.show(carouselParent);
          }
};

prisma.load('campaigns.bank.com', '80', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
            "137-W", [{"placeholderId" : "MainBanner", "elementId" : null}],
            "http:", {onLoaded : onLoaded});
</script>

En este ejemplo, las imágenes o banners HTML asociados al placeholder MainBanner se mostrarán en el elemento identificado por my-parent en la página.

Popups personalizados

La función onPopup permite controlar el despliegue de popups desde la aplicación a integrar como se indica a continuación. Para eso, se requiere que la función reciba como parámetro el control a desplegar en la forma de onPopup(popup):

<div id="my-parent"></div>

<script type='text/javascript'>
var onPopup = function(popup) {
    if (popup.banner.category == "Ventas") {
        // 1. Desplegar el popup de forma personalizada
        // 2. Retornar true indica al sistema que no debe desplegar el popup ya que fue resuelto de forma personalizada
        return true;
    }
};

prisma.load('campaigns.bank.com', '80', '8e2626da-4ee1-45c7-b269-50df530dbc6e',
            "137-W", [{"placeholderId" : "MainBanner", "elementId" : null},],
            "http:", {onPopup : onPopup});
</script>

Como se ilustra en el ejemplo de arriba, en este caso se debe incluir un callback llamado onPopup en el parámetro OPTIONS del método load. Esta función será invocada por la plataforma cada vez que, entre la lista de campañas para el usuario actual, haya un popup que desplegar.

Los parámetros del popup se deben especificar como se indica a continuación:

Parámetro Tipo de dato Requerido Descripción
width long Sí Ancho del placeholder
height string Sí Alto del placeholder
banner Banner Sí Configuración del banner a desplegar en el popup
hideClose boolean Sí Indica si se debe ocultar el botón para cerrar el popup, según se haya configurado en la plataforma
dismissFn function No Función a ejecutar cuando el cliente indique que no le interesa una campaña, en caso de que esta admita dicha acción

El parámetro banner tiene distintos atributos dependiendo si consiste de una imagen o de código HTML. Esto permite desplegar el popup de forma personalizada según los requerimientos de una de las siguientes formas:

BannerHTML()
Parámetro Tipo de dato Descripción
width long Ancho del placeholder
height string Alto del placeholder
category string Categoría de la campaña asociada al banner o una cadena vacía en caso que no exista
group string Grupo de la campaña asociada al banner o una cadena vacía en caso que no exista
Funnel funnel Configuración del funnel asociado a la campaña
isolated boolean Indica si el popup se solicitó en modo aislado
content string Contenido HTML del banner 
BannerImage()
Parámetro Tipo de dato Descripción
width long Ancho del placeholder configurado
height string Alto del placeholder configurado
category string Categoría de la campaña asociada al banner o una cadena vacía en caso que no exista
group string Grupo de la campaña asociada al banner o una cadena vacía en caso que no exista
Funnel funnel Configuración del funnel asociado a la campaña
link string Link de la imagen a desplegar en el banner

Conversión

A través del método convert se marca la conversión de un cliente en una campaña específica de la siguiente manera:

<script type='text/javascript' src='http://SERVER:PORT/sdk/javascript/prisma.js'></script>
<script type = "text/javascript" >
    prisma.convert(SERVER, PORT, APP_TOKEN, PROTOCOL, CAMPAIGN_ID, CALLBACK)
</script>

Los parámetros SERVER, PORT, APP_TOKEN y PROTOCOL representan lo mismo que en casos anteriores. Los dos restantes se detallan en la tabla que aparece a continuación:

Parámetro Tipo de dato Requerido Descripción
CAMPAIGN_ID string Sí Identificador de la campaña que se obtiene a partir de la URL utilizada en la redirección
CALLBACK function No Función a ejecutar luego de la conversión que usa como parámetro la respuesta de la API

Por lo general, se suele realizar una redirección desde un paso del funnel hacia una herramienta externa (aplicación web). En esta acción se envían tres parámetros dentro de la consulta (campaign-id, trail-id y funnel-node-id) que pueden obtenerse en el backend o utilizando JavaScript en el navegador:

<script type = "text/javascript" >
    function getParameterByName(name, url) {
        if (!url) url = window.location.href;
        name = name.replace(/[\[\]]/g, "\\$&");
        var regex = new RegExp("[?&]" + name + "(=([^&#]*)|&|#|$)"),
            results = regex.exec(url);
        if (!results) return null;
        if (!results[2]) return '';
        return decodeURIComponent(results[2].replace(/\+/g, " "));
    }
</script>

Cordova

Para desplegar banners HTML en una app desarrollada sobre Cordova se debe cumplir una de las siguientes condiciones:

  • Establecer isolated = false para el placeholder con el objetivo de que el banner no sea creado dentro de un iframe.
  • Agregar la regla <allow-navigation href="about:" /> o <allow-navigation href="*" /> al config.xml de Cordova, para cargar el iframe del banner.

Artículos relacionados