Usar APIs de campañas

Prisma Campaigns proporciona varias APIs relacionadas con campañas. Los endpoints que se enumeran a continuación permiten a los desarrolladores recuperar las campañas activas de cada cliente, mostrar banners e imágenes en placeholders, ver los pasos del funnel e incluso disparar campañas en base a ciertos eventos de negocio.

Campañas activas

Esta API devuelve todas las campañas activas de un cliente determinado. Para utilizarla, es necesario hacer lo siguiente:

La información a enviar 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

Con esta API es posible devolver la lista de banners e imágenes disponibles en un determinado placeholder. Cada página o pantalla puede incluir varios banners (o al menos un único popup). En cualquier caso, la sincronización de la pantalla o de la aplicación se realiza invocando una misma API. La respuesta incluye todos los elementos correspondientes a esa pantalla para el cliente en cuestión.

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 con dos conjuntos de datos:

1. Banners para mostrar en cada placeholder
2. Información sobre el popup a mostrar (si aplica)

y tiene la siguiente estructura:

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

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

Popup

La estructura de información correspondiente a un popup contiene los siguientes datos:

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

Para mostrar el funnel asociado con un popup determinado, la API se debe invocar como se indica a continuación: /api/campaigns/:campaign/funnel?d=:tracking-token&a=:app-token&t=:trail-id&popup=true

Placeholders

El atributo placeholders en la respuesta de la API sync-page contiene la lista de los banners que se visualizarán en cada uno de los placeholders solicitados.

Si un placeholder no posee ningún banner asociado para un cliente en particular, la respuesta estará vacía.

La estructura de información correspondiente a un placeholder se muestra abajo:

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

Cada objeto dentro de banners-list contiene los detalles de un banner para el placeholder en cuestión. En caso de que haya más que uno, será posible desplegarlos en distintos modos (carrusel, grilla, etc).

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

Dentro del objeto funnel hay propiedades relacionadas con el proceso de conversión del cliente junto con los datos sobre el primer paso del funnel.

Pasos del funnel

Para obtener los pasos definidos en el funnel se puede emplear la API advance-funnel. Este recurso devolverá los pasos (uno por uno) a medida de que el cliente vaya completándolos.

Si hay bifurcaciones en el funnel, en base a los datos u otros parámetros de usuario el siguiente paso se determinará después de que concluya la acción actual. De esta forma, se debe utilizar la API para obtener el primer paso del funnel cuando el cliente se interese por la campaña, así como los siguientes pasos a medida que cada uno de ellos termine.

La información a enviar 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 concordar con la interacción del usuario. Por ejemplo, si el cliente hizo clic en un banner, se deben incluir el identificador de campaña y el tracking token.

Cuando el usuario comienza el funnel no se debe enviar el parámetro step-data. En todos los demás casos sí es requerido (aunque sea vacío) para avanzar al próximo paso.

La estructura de la respuesta se muestra a continuación:

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

El detalle de configuración para cada tipo de paso se indica a continuación.

Mensaje

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

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

Captura de datos

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

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

donde

En este caso, fields indica cuáles campos son requeridos en el paso actual, donde cada uno posee la siguiente estructura:

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

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

Al invocar la API advance-funnel, los datos deben incluir los valores de los campos capturados utilizando name como referencia.

Redirección

El detalle de configuración para un paso de redirección es el siguiente:

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

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

Clientes

Este endpoint permite crear o actualizar la información de un cliente existente:

La información a enviar 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 queda definido por uno de los siguientes códigos HTTP:

Eventos de negocio

Prisma Campaigns proporciona un método para activar campañas a partir de ciertos business events que son particulares para cada empresa. Debido a que dichos eventos solamente tienen sentido en el ámbito de una aplicación, el administrador debe configurar la que dará inicio a los mismos. Para lograr esto, es necesario dirigirse a Settings/Applications y crear un nuevo evento de negocio introduciendo un nombre (que debe ser único) y una descripción.

A continuación, puede asociar un evento con una campaña en la sección correspondiente de las configuraciones de la campaña. Por defecto, los eventos se aplican a todos los clientes del segmento, pero también se pueden filtrar si es necesario.

Para disparar un evento se debe enviar una solicitud POST como se indica a continuación:

El cuerpo de la misma debe contener los siguientes campos:

El servidor responderá con 202 Accepted si la operación se completa exitosamente o 404 Not Found en caso de que no se encuentre ninguna campaña que cumpla con dichas condiciones. Adicionalmente, la respuesta incluye los campos que se detallan a continuación:

Nota: El servidor puede devolver un objeto del tipo EDN o JSON dependiendo del contenido de los encabezados Accept y Content-Type. Vale la pena aclarar que este último es obligatorio.

Artículos relacionados

• Utilizar eventos de negocio