Tabla de contenido
Para que una transacción de cliente se pueda aplicar a un desafío de fidelidad, debe tener el formato Evento de fidelidad de Adobe que el servicio de desafío entienda. Los eventos del cliente (desde un sistema POS, una aplicación móvil, una plataforma de comercio electrónico o cualquier otra fuente) suelen utilizar el esquema de datos propio del cliente. Transformadores de eventos eliminan esta brecha sin requerir ningún cambio en el sistema de flujo ascendente.
Información general
Una definición de evento indica a la plataforma dos cosas:
- Qué eventos reclamar: cómo reconocer que un evento entrante pertenece a esta definición (coincidencia)
- Cómo darles nueva forma: una expresión JSONata que asigna los campos del cliente al formato de Evento de fidelidad (transformación)
Se pueden configurar varias definiciones de evento por organización. La plataforma los evalúa en orden y aplica el primero que coincida. Los eventos que no coinciden con ninguna definición se transfieren a la ingesta nativa (consulte Reserva — Eventos de fidelidad nativos).
El formato de evento de fidelización de Adobe
Cada definición de evento debe producir un objeto JSON con el siguiente formato. Esta es la entrada que procesa el servicio de desafío.
{
"_id": "string — optional; used for duplicate detection if enabled",
"event_name": "string — used for internal metrics and reporting only (e.g. 'purchase', 'visit')",
"timestamp": "ISO 8601 date-time string — when the event occurred",
"utc_offset": "string — UTC offset of the store or device (e.g. '-07:00'); required for daypart matching",
"location_id": "string — optional; store or location identifier",
"transaction_id": "string — optional; dedup key for the transaction",
"loyalty_identity": {
"id": "string — the member's loyalty ID"
},
"item_list": [
{
"item_set": ["string", "..."], // one or more identifiers — SKU, category, event code, etc.
"item_name": "string — optional human-readable label",
"quantity": 1, // integer; how many units
"unit_price": 4.99, // float; price per unit
"sub_total": 4.99 // float; line total (quantity × unit_price)
}
]
}
Notas de campo
loyalty_identityid: el ID de fidelidad del miembro.item_listitem_settimestamputc_offset_idsub_totalCampos de definición de evento
guidname"Starbucks POS Purchase".xdmSchemaIdtransformerFuncionamiento de la coincidencia
Los eventos que llegan a través del servicio principal de recopilación de datos (DCCS) llevan una referencia de esquema XDM en su sobre. La plataforma lee el identificador de esquema de /body/xdmMeta/schemaRef/id y lo compara con el xdmSchemaId de cada definición.
La plataforma recorre las definiciones de evento de la organización en orden y aplica la primera coincidencia. Una vez encontrada una coincidencia, el cuerpo xdmEntity se pasa al transformador.
Escritura del transformador
El campo transformer es una expresión JSONata. Recibe el evento JSON entrante como entrada y debe devolver un objeto de evento de fidelidad de Adobe válido.
Asigne cada campo de nivel superior del formato de destino a la ruta correspondiente en el evento de origen:
| code language-jsonata |
|---|
|
Si todos los eventos que coinciden con esta definición representan la misma actividad lógica, codifique el event_name:
| code language-jsonata |
|---|
|
event_name se usa para informes y métricas internas. No se usa como filtro de tareas: la calificación de tareas está determinada por el contenido de item_set, no por el nombre del evento.
Para los eventos que llegan a través de la ruta DCCS, la identidad del miembro se suele llevar en el campo XDM estándar identityMap en lugar de una propiedad de inquilino personalizada. identityMap es un mapa escrito por el área de nombres (la clave en sí es el nombre del área de nombres y el valor es una matriz de objetos de identidad).
| code language-jsonata |
|---|
|
-
Sustitución del área de nombres: Reemplace
Emailcon el área de nombres que su organización utilice para los miembros con lealtad:Loyalty,ECID,CRMID, etc. Lea siempre desde el área de nombres que contiene la identidad principal del perfil de lealtad. -
Usar siempre
[0]:identityMap.Emailes una matriz. Sin el índice, JSONata devuelve una secuencia en lugar de un valor único si hay más de una identidad yloyalty_identity.idse convierte en una lista. Ancléelo al primer elemento con[0]. -
Evitar campos de inquilino personalizados para la identidad: Los grupos de campos personalizados a veces exponen un campo de aspecto electrónico (p. ej.
_yourtenant.identification.core.email). En los datos de ejemplo, esto devuelve un valor y tiene un aspecto correcto, pero en los eventos de producción suele estar vacío. La fuente confiable de identidad siempre esidentityMap.
item_setitem_set es una matriz de identificadores de cadena. Incluya todos los campos por los que puedan filtrar las tareas de desafío:
| code language-jsonata |
|---|
|
Para los eventos no transaccionales (un registro de entrada, una finalización de una encuesta, un déclencheur personalizado), un solo identificador es suficiente:
| code language-jsonata |
|---|
|
unit_priceunit_price debe ser un precio por unidad. Algunos esquemas de origen almacenan un total de línea (precio × cantidad) en su lugar. Si el campo de origen es un total de línea, divida por cantidad para obtener el precio unitario:
| code language-jsonata |
|---|
|
Dividir solo si el campo de origen es un total de línea. Si ya almacena un precio unitario, asígnelo directamente: si se divide un precio unitario por cantidad, se producirá un valor incorrecto de forma silenciosa.
transaction_idSi el evento de origen no incluye un identificador de transacción, puede derivar uno estable de la marca de tiempo:
| code language-jsonata |
|---|
|
Esto convierte la marca de tiempo ISO en milisegundos epoch y produce un valor determinístico para un evento determinado. Utilice la función de generación de ID de su propia plataforma si hay una disponible.
La biblioteca completa de funciones JSONata está disponible. Ejemplos útiles:
| code language-jsonata |
|---|
|
Ejemplos
Escenario: Una aplicación móvil envía un evento de protección. No hay elementos de línea: el evento en sí es la actividad correspondiente.
Evento entrante:
| code language-json |
|---|
|
Definición de evento:
| code language-json |
|---|
|
Transformador con formato (para facilitar la lectura):
| code language-jsonata |
|---|
|
Evento de fidelidad de Adobe de salida:
| code language-json |
|---|
|
Una tarea de desafío sin restricciones de inclusión/exclusión contará este evento como una visita que cumple los requisitos: la sola entrada item_set ["store-checkin"] coincide con cualquier tarea que permita todos los elementos.
Escenario: Un sistema de punto de venta envía una carga útil de transacción. Cada elemento de línea tiene un SKU y pertenece a una categoría. Las tareas de desafío utilizan el SKU y la categoría para determinar qué califica.
Evento entrante:
| code language-json |
|---|
|
Definición de evento:
| code language-json |
|---|
|
Transformador con formato:
| code language-jsonata |
|---|
|
Evento de fidelidad de Adobe de salida:
| code language-json |
|---|
|
Una tarea de desafío con include: ["BEVERAGE"] vería que el elemento de línea de café cumple los requisitos (su item_set contiene "BEVERAGE") y acumularía $9,00 de gasto en esa tarea. Se excluiría el elemento de línea de magdalena.
Escenario: Los eventos fluyen a través de Adobe Journey Optimizer. El evento entrante es un evento de experiencia XDM con un ID de esquema conocido. La plataforma utiliza el ID de esquema para la coincidencia en lugar de una comprobación de ruta/valor.
Cuerpo de entidad XDM entrante (el xdmEntity extraído del evento AJO):
| code language-json |
|---|
|
Definición de evento:
| code language-json |
|---|
|
Transformador con formato:
| code language-jsonata |
|---|
|
Nota: Cuando un evento coincide con el ID de esquema XDM, el transformador solo recibe la parte
xdmEntitydel evento, no el sobre exterior de AJO. Todas las rutas de la expresión del transformador son relativas al cuerpo de la entidad XDM.
Adición de la validación del esquema JSON (opcional)
Si desea que la plataforma valide la estructura de los eventos entrantes antes de intentar la transformación, establezca el campo schema en un documento Esquema JSON codificado como una cadena JSON.
Los eventos que no superan la validación del esquema se rechazan antes de ejecutar la transformación. La respuesta de error incluye el error de validación específico, lo que facilita el diagnóstico de eventos ascendentes con formato incorrecto.
| code language-json |
|---|
|
Pase este esquema como una cadena JSON minificada en el campo schema de la definición del evento.
Reserva: eventos de fidelidad nativos
Si ninguna definición de evento coincide con un evento entrante, la plataforma intenta introducirlo directamente como un evento de fidelidad de Adobe nativo. Si la carga útil ya se ajusta al formato de evento de fidelidad descrito anteriormente, no se necesita ningún transformador y el evento se aplica tal cual. Esto permite a los clientes que han formateado previamente sus eventos evitar la transformación por completo.
Referencia de la API
Todas las operaciones de definición de eventos utilizan la ruta base /loyalty/metadata/config/events.
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
| code language-http |
|---|
|
Validación del transformador
Las expresiones JSONata se validan para la sintaxis cuando se guarda la definición del evento. Si la expresión no es válida, la API devuelve un error 422 con una descripción del error de análisis.
Para probar un transformador antes de implementarlo, use JSONata Exerciser: pegue el evento de origen como entrada y la expresión del transformador para comprobar que la salida coincide con el formato de evento de fidelidad esperado.
Problemas comunes
Todos estos errores se ejecutan sin errores en una carga útil de prueba de un solo elemento, por lo que no se detectan. Antes de su implementación, pruebe siempre el transformador con una carga útil con dos o más productos.
El error más frecuente. Si se usa un solo objeto literal con productListItems.SKU, se extraen todos los SKU y todas las cantidades en secuencias agrupadas, en lugar de producir un elemento de línea por producto.
✗Contrae todos los elementos en uno:
| code language-jsonata |
|---|
|
Con dos productos, item_set contiene ambos SKU y quantity se convierte en una matriz como [1, 4].
✓Un elemento de línea por producto:
| code language-jsonata |
|---|
|
El mapa .{ } se ejecuta una vez por producto para que cada uno se convierta en su propia entrada.
identityMap.Email es una matriz. Sin [0], si un perfil tiene más de una identidad en ese área de nombres, id se convierte en una lista de valores en lugar de una sola cadena.
✗ identityMap.Email.id
✓ identityMap.Email[0].id
_yourtenant.identification.core.email. En los datos de ejemplo, devuelve un valor y tiene un aspecto correcto, pero en los eventos de producción suele estar vacío, lo que provoca que loyalty_identity.id salga como nulo. Use siempre identityMap como origen de identidad.item_setAgregar un campo de categoría a item_set parece sencillo, pero si productCategories es en sí mismo una matriz, el resultado se amplía de forma impredecible.
✗puede producir más entradas de las esperadas:
| code language-jsonata |
|---|
|
Un producto con tres categorías genera un(a) item_set con cuatro valores.
✓Indexe la matriz anidada para obtener exactamente un valor:
| code language-jsonata |
|---|
|
item_list está vacío o faltaUn evento con un item_list vacío o ausente se rechazó como no válido. Para los eventos no transaccionales (registros, déclencheur personalizados) no hay elementos de línea naturales, por lo que debe producir uno sintético:
| code language-jsonata |
|---|
|
timestamp como un entero Unix epoch en lugar de ISO 8601La plataforma espera una cadena ISO 8601. Si el evento de origen lleva milisegundos desde epoch, conviértalo:
| code language-jsonata |
|---|
|
utc_offset omitidoutc_offset, la coincidencia de la ventana de la parte del día y el recuento de rachas de día consecutivo se omiten. Asigne el desplazamiento UTC de la tienda o el dispositivo desde el evento de origen siempre que esté disponible.xdmEntity, no el sobre externo de AJO. Todas las rutas deben ser relativas a la raíz de la entidad XDM. Si la expresión hace referencia a campos que residen en el sobre exterior (p. ej. /body/xdmMeta/...), no se encontrarán y generarán un valor nulo de forma silenciosa.