API REST #

El API Rest provee un mecanismo de integración para aquellos casos donde no existe un SDK Nativo que permita integrarse con la plataforma de Marketing Automation.

En todos los casos las APIs soportan el formato EDN, que cuenta con ventajas relativas a JSON ya que admite distintos tipos de datos evitando tener que transmitir la información siempre codificada como string.

En caso que se desee utilizar JSON como formato de serialización se debe especificar los encabezados HTTP Content-Type y Accept con el valor application/json.

Trazas #

El API de trazas provee un mecanismo genérico de trazabilidad sin importar el tipo de acción o plataforma donde esta ocurre. Como tal, no asume ningún tipo de capacidad del canal para persistir los identificadores de sesión -por ejemplo cookies-, debiendo cada usuario del API Rest resolver de forma independiente la persistencia y asociación de dicha información.

Para los casos donde si se cuenta con dicha disponibilidad (navegadores de Internet, por ejemplo), se recomienda utilizar el SDK nativo existente.

Traza #

Los clientes interactúan con la plataforma en distintas sesiones, o interacciones que denominamos visitas (trails), las trazas son agrupadores para estas visitas. En el caso más común, antes de convertir un cliente interactúa varias veces con distintas secciones del sitio web, la aplicación móvil u otro canal.

Antes de crear una nueva visita (trail) está debe pertenecer a una traza, por lo que si no existe la traza hay que crearla. La traza debe generarse o bien la primera vez que un usuario visita o entra a la aplicación, o bien cuando se quiere dar por cerrada una traza anterior quizás porque el usuario ya convirtió en otra promoción.

El formato de la información posteada es un objeto EDN o JSON con dos campos, ambos opcionales.

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
}

data = {
    "app-token": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932"
}

El parámetro customer-id puede estar vacío si la persona interactuando no está identificada, escenario en el cuál el sistema creará un identificador de cliente anónimo para esta interacción.

La respuesta es un objeto EDN o JSON con el identificador de traza generado, este identificador de traza debe ser utilizado luego en cada nueva visita para mantenerlas asociadas. En caso que la traza se genere con un identificador de cliente anónimo, este será retornado como parte del resultado.

response = {
    :trace-id "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
}

response = {
    "trace-id": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932"
}

El resultado de la operación está dado por uno de los siguientes códigos de estado HTTP.

Visita #

Una nueva visita debe generarse cada vez que un usuario visita el sitio web o abre la aplicación móvil (o utiliza de alguna otra forma un canal alternativo).

El formato de la información posteada es un objeto EDN o JSON con tres campos, donde dos de ellos (platform y language) son opcionales.

data = {
    :language "en-US"
    :platform "Chrome Browser"
    :channel: :atm
}

data = {
    "language": "en-US",
    "platform": "Chrome Browser",
    "channel": "atm"
}

La respuesta es un objeto EDN o JSON con el identificador de visita generado, el cual deberá ser usado en las subsecuentes acciones generadas dentro de esta visita.

response = {
    :trail-id "D17C100F-0668-400A-AF91-967FE1A09A9E"
}

response = {
    "trail-id": "D17C100F-0668-400A-AF91-967FE1A09A9E"
}

El resultado de la operación está dado por uno de los siguientes códigos de respuesta HTTP:

Actividad #

Como se mencionó en el documento de primeros pasos, una actividad realizada dentro de una visita puede ser de distinto tipo:

La ejecución se realiza mediante el api action y el formato de la información posteada es un objeto EDN o JSON:

data = {
    :name "conversion"
    :type :trail-action/conversion
    :data [
        {
            :name "field1"
            :value "value1"
        }
        {
            :name "field2"
            :value "value2"
        }
    ]
}

data = {
    "name": "conversion",
    "type": "conversion",
    "data": [
        {
            "name": "field1",
            "value": "value1"
        },
        {
            "name": "field2"
            "value": "value2"
        }
    ]
}

El resultado de la operación está dado por uno de los códigos de estado HTTP que aparecen a continuación:

Conversión y No interés #

Mediante el uso del API action es posible indicar cuando un cliente convierte o marca su falta de interés en una campaña. Para esto cada acción tiene su tipo correspondiente, y el único parámetro requerido a enviar es el tracking-token obtenido previamente en el canal.

EDN:

Se debe enviar la información que se indica debajo. En el caso de JSON, el tipo de acción se debe enviar sin prefijo.

data = {
    :name "conversion"
    :type :trail-action/conversion
    :data [{:name "tracking-token" :value "value"}]
}

data = {
    :name "dismiss"
    :type :trail-action/dismiss
    :data [{:name "tracking-token" :value "valor"}]
}

data = {
    "name": "conversion",
    "type": "conversion",
    "data": [{"name": "tracking-token", "value": "value"}]
}

data = {
    "name": "dismiss",
    "type": "dismiss",
    "data": [{"name": "tracking-token", "value": "value"}]
}

IMPORTANTE: Una vez que se invoca conversion o dismiss en una traza, esta no puede ser utilizada nuevamente y debe crearse una nueva para marcar siguientes acciones, visitas y sincronizaciones. En caso de que se intente seguir utilizando la misma traza se obtendrá un error 400 de solicitud inválida.

Campañas #

Funcionalidades de campañas.

Campañas Activas #

Este API permite obtener todas las campañas que tiene activas un cliente dado.

La ejecución es mediante el API:

El formato de la información posteada es un objeto EDN:

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
    :category "Sales"
    :group "Cars"
    :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
}

Banners y Popups #

Los banners y popups se obtienen como resultado de la sincronización de “páginas” o pantallas de aplicaciones. Cada vez que el usuario navega a una nueva página o pantalla se pueden recuperar varios banners juntos, o un popup para esa pantalla. Estas acciones se realizan invocando a una única API (sync-page) que obtiene todos los elementos correspondientes a esa pantalla para el cliente.

El formato de la información posteada es un objeto EDN o JSON:

data = {
    :app-token "D17C100F-0668-400A-AF91-967FE1A09A9E"
    :customer-id "5114932"
    :trail-id "882252f3-fe70-4402-9195-639d8037f339"
    :sync-popups true
    :page-location "http://my.domain/page"
    :placeholders [{:placeholder "id-placeholder1"} {:placeholder "id-placeholder2"}]
}

data = {
    "app-token": "D17C100F-0668-400A-AF91-967FE1A09A9E",
    "customer-id": "5114932",
    "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
    "sync-popups": "true",
    "page-location": "http://my.domain/page",
    "placeholders": [{"placeholder": "id-placeholder1"}, {"placeholder": "id-placeholder2"}]
}

La respuesta es un objeto EDN o JSON conteniendo dos tipos de información:

1. Los banners a desplegar en cada placeholder
2. Información del Popup a desplegar en caso que corresponda.

response = {
    :popup = {}
    :placeholders = [{} {}]
}

response = {
    "popup": {},
    "placeholders": [{}, {}]
}

Popup #

La estructura de información del popup contiene los siguientes datos

popup = {
    :tracking-token
    :campaign
    :show-close
    :funnel
}

Para desplegar el funnel correspondiente a este popup se debe utilizar la url conformada de la siguiente forma: /api/campaigns/:campaign/funnel?d=:tracking-token&a=:app-token&t=:trail-id&popup=true

Placeholders #

El atributo placeholders en la respuesta del api sync-page, contiene el resultado de banners a desplegar en cada uno de los placeholders solicitados que contengan información. En caso que algún placeholder no tenga banners asociados a desplegar para el cliente identificado, no se devolverán resultados.

La estructura de respuesta para cada placeholder es la siguiente:

placeholder = {
    :customer-id "5114932"
    :banners-list [{b1} {b2}]
    :is-popup false
    :popup-timeout 1000
    :transition-time 5000
    :width 800
    :height 600
}

Descripción del resultado:

Detalle de banner:

Cada objeto de la lista banners-list contiene el detalle de uno de los banners a desplegar para ese placeholder. En caso que exista más de uno, se podrán desplegar en distintos formatos: carrusel, grilla, etc.

El detalle de cada objeto banner retornado es el siguiente:

banner-detail = {
    :banner {banner object}
    :funnel {funnel object}
}

Descripción del objeto banner:

Descripción del objeto funnel:

Dentro del objeto funnel se encuentran propiedades relativas al proceso de conversión del usuario identificado, junto con los datos correspondientes al primer paso del funnel.

Pasos del Funnel #

Para obtener los pasos definidos del funnel se utiliza advance-funnel. Esta API obtiene los pasos de a uno, a medida que se van completando los pasos anteriores.

En la medida que el funnel puede tener bifurcaciones condicionadas en base a datos u otras parametrizaciones del usuario, recién al momento de completar un paso se puede determinar cuál paso siguiente corresponde. Esta es la razón por la que se debe utilizar este API tanto para obtener el primer paso del funnel cuando el usuario se interesa en una campaña, así como los pasos siguientes a medida que se va completando cada uno.

El formato de la información posteada es un objeto EDN o JSON.

data = {
    :trail-id  "882252f3-fe70-4402-9195-639d8037f339"
    :campaign-id 123123101
    :tracking-token "12312-21919-j1b3-121m-1212"
    :step-data {}
}

data = {
    "trail-id": "882252f3-fe70-4402-9195-639d8037f339",
    "campaign-id": "123123101",
    "tracking-token": "12312-21919-j1b3-121m-1212",
    "step-data": {}
}

Los parámetros campaign-id y tracking-token deben corresponder a la interacción que el usuario haya realizado, si por ejemplo clickeó en un banner, se debe enviar el dato campaign y tracking-token correspondiente a ese banner. Cuando el usuario inicia el funnel no se debe enviar el parámetro step-data, mientras que en otros casos debe enviarse siempre así sea vacío para lograr avanzar en el funnel.

La estructura de respuesta es la siguiente:

response = {
    :type data-capture | message | redirect
    :config {}
}

A continuación, se describe el detalle de configuración para cada tipo de paso a desplegar.

Paso Mensaje #

step = {
    :title
    :message
    :actions
    :remaining-steps
    :max-steps
}

step = {
    "title":
    "message":
    "actions":
    "remaining-steps":
    "max-steps":
}

Paso Captura de Datos #

step = {
    :fields
    :actions
    :remaining-steps
    :max-steps
}

step = {
    "fields":
    "actions":
    "remaining-steps":
    "max-steps":
}

La lista de campos indica que campos se le deben solicitar al cliente en este paso, y tiene la siguiente estructura para cada campo:

field = {
    :label
    :name
    :control-type
    :value
}

field = {
    "label":
    "name":
    "control-type":
    "value":
}

Cuando se solicita el siguiente paso con advance-funnel, el step-data debe contener los valores de los campos capturados utilizando name como referencia.

Paso Redirect #

step = {
    :url
    :method
    :parameters
    :include-system-params
    :new-window
}

step = {
    "url":
    "method":
    "parameters":
    "include-system-params":
    "new-window":
}

Clientes #

Este API permite crear o actualizar la información de un cliente nuevo o existente a través de la URL que se indica a continuación:

El formato de la información posteada es un objeto EDN o JSON.

data = {
    :customer {:id 12345 :field "xxyyzz"}
    :app-token "882252f3-fe70-4402-9195-639d8037f339"
}

data = {
    "customer": {"id": "12345", "field": "xxyyzz"},
    "app-token": "882252f3-fe70-4402-9195-639d8037f339"
}

El resultado de la operación está dado por uno de los siguientes códigos de estado HTTP:

Eventos de negocio #

Prisma permite disparar campañas a partir de los llamados “Eventos de Negocio” (Business Events). La naturaleza de cada evento de negocio es, por supuesto, particular para cada compañía.

Como los eventos de negocio se definen dentro del scope una aplicación (Settings/Applications), es de esperarse que se cree una aplicación (llamada, por ejemplo, Backend) sobre la cual dar de alta los eventos que se tiene previsto disparar. Cada evento de negocio tiene un nombre (único) y una descripción, y una vez creado, puede ser asignado a una campaña.

La interfaz de configuración se encuentra en Campaign Settings/Business Events. Se debe primero habilitar el canal Business Events para luego poder asignarle los mismos a la campaña. De ser necesario, para cada evento se puede aplicar un filtro que se suma al ya definido por el segmento de la campaña.

Cuando se dispara un evento mediante una solicitud del tipo POST, se obtienen las campañas activas que lo tienen configurado y se aplica el filtro correspondiente. Luego, se aplica el algoritmo de orquestación de la compañía para seleccionar la mejor campaña para dicho evento y cliente.

Donde el cuerpo del request debe contener lo siguiente:

Un token de aplicación inválido o un evento inexistente generará un error 404. Un identificador de cliente vacío resultará en un error 400. Si no se encuentra un cliente con el identificador especificado, entonces se crea uno nuevo.

El campo customer-id puede ser o bien un text representando el identificador de un cliente o una especificación de búsqueda, es decir: un objeto con parejas de clave-valor que representan los campos de búsqueda. Por ejemplo:

{
    :app-token "882252f3-fe70-4402-9195-639d8037f339"
    :event-name "newsletter-registration"
    :customer-id {:email "jane.doe@example.com"}
}

{
    "app-token": "882252f3-fe70-4402-9195-639d8037f339"
    "event-name": "newsletter-registration",
    "customer-id": {"email": "jane.doe@example.com"},
}

Si se especifica un campo que no existe en el esquema de clientes, se generará un error 400. Si no se encuentra un cliente con los campos especificados, entonces se crea un cliente nuevo y dichos valores se asignan a los campos correspondientes.

El cuerpo del request también puede contener los siguientes datos opcionales:

En caso de no encontrarse una campaña para el cliente y evento indicado el servidor responde 404 Not Found. De lo contrario, devolverá 202 Accepted y los siguientes valores:

Nota: El servidor responde EDN o JSON dependiendo del contenido de los headers Accept o Content-Type, donde este último es obligatorio. El campo customer-id contiene el mismo valor que el campo customer-id del request. Si el campo customer-id del request es una especificación de búsqueda, entonces el campo customer-id del response será el identificador del cliente correspondiente.