> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.es/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referencia de eventos de aplicación (BETA)
> Información de referencia para los eventos de la aplicación en la última versión de la plataforma para desarrolladores.
A continuación, encontrarás información de referencia para utilizar los eventos de la aplicación, incluidos esquemas de tipos de eventos, plantillas de representación de cronologías de eventos, campos de ocurrencia de eventos y mucho más.
## Estructura del proyecto
En el contexto de un proyecto, pondrás las definiciones de los tipos de eventos en un directorio `app-events` dentro de `app/`. El directorio `app-events` debe contener un archivo de definición del esquema JSON para cada tipo de evento (`*-hsmeta.json`).
```shell theme={null}
project-folder/
└── src/
└── app/
├── app-hsmeta.json
└── app-events/
└── my-event-type-hsmeta.json
```
Para incluir definiciones de tipo de evento en un proyecto se requiere lo siguiente:
* Tu aplicación debe utilizar la autenticación de OAuth y estar configurada para su distribución en el mercado de aplicaciones. Además, la aplicación debe incluir `timeline` en su `requiredScopes`. Más información sobre la [configuración de aplicaciones](/apps/developer-platform/build-apps/app-configuration).
* Tu proyecto debe desplegarse correctamente antes de que puedas incluir un componente de eventos de aplicación.
## Esquema del tipo de evento
Abajo se indican las opciones de configuración disponibles para los esquemas de tipo de evento (`*-hsmeta.json`). Ten en cuenta que algunos de los atributos que aparecen no se pueden cambiar una vez creado el tipo de evento.
Cada aplicación está limitada a 750 tipos de eventos.
```json theme={null}
{
"uid": "customer_login_event",
"type": "app-event",
"config": {
"name": "Customer login",
"headerTemplate": "{{customerName}} logged in.",
"detailTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"objectType": "CONTACT",
"properties": [
{
"name": "customerName",
"label": "Customer Name",
"type": "string"
},
{
"name": "loginLocation",
"label": "Login location",
"type": "enumeration",
"options": [
{
"value": "mobileApp",
"label": "Mobile app"
},
{
"value": "website",
"label": "Website"
}
]
}
]
}
}
```
Los campos marcados con \* son obligatorios.
| Campo | Tipo | Descripción |
| ------------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uid`\* | Cadena | Un identificador único interno para el tipo de evento. |
| `type`\* | Cadena | El tipo de componente. Debe ser `app-event`. |
| `name`\* | Cadena | La etiqueta que se muestra en HubSpot (hasta 50 caracteres). Este valor no se puede actualizar después de la creación. |
| `objectType`\* | Cadena | El nombre completo del tipo de objeto del CRM al que se pueden asociar los eventos. Este valor no se puede cambiar después de la creación. Puede ser uno de los siguientes: `COMPANY`, `CONTACT`, `CUSTOM_OBJECT`, `DEAL`, `TICKET`, `APP_OBJECT`. |
| `headerTemplate` | Cadena | La [plantilla de representación](#rendering-templates) del encabezado de la tarjeta de actividad de la cronología del CRM. Puede tener hasta 1000 caracteres de longitud. |
| `detailTemplate` | Cadena | La [plantilla de representación](#rendering-templates) para el cuerpo de la tarjeta de actividad de la cronología del CRM. Puede tener hasta 10.000 caracteres de longitud. |
| `properties` | Matriz | Propiedades definidas para el tipo de evento en el que vas a almacenar los datos de ocurrencia del evento. Cada tipo de evento puede tener hasta 500 propiedades. Más información sobre las propiedades personalizadas del evento a continuación. |
### Propiedades de eventos
Cuando definas el esquema de sucesos, utiliza la matriz `properties` para definir los campos a los que enviarás los datos de eventos. Cada tipo de evento puede tener hasta 500 propiedades.
```json theme={null}
"properties": [
{
"name": "customerName",
"label": "Customer Name",
"type": "string"
},
{
"name": "loginLocation",
"label": "Login location",
"type": "enumeration",
"options": [
{
"value": "mobileApp",
"label": "Mobile app"
},
{
"value": "website",
"label": "Website"
}
]
}
]
```
Los campos marcados con \* son obligatorios.
| Campo | Tipo | Descripción |
| -------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`\* | Cadena | El nombre interno de la propiedad. Debe estar en minúsculas y tener entre 1 y 500 caracteres. Los nombres de las propiedades deben ser únicos por tipo de evento. Este valor no puede coincidir con la expresión regular `"[A-Za-z0-9_\\-.]+"` ni empezar por `hs_`. |
| `label`\* | Cadena | La etiqueta que se muestra en HubSpot. Debe estar en minúsculas y tener entre 1 y 500 caracteres. |
| `type`\* | Cadena | Tipo de datos capturados en la propiedad. Puede ser uno de los siguientes: `STRING`, `NUMBER`, `DATE`, `ENUMERATION`. |
| `options` | Matriz | Para las propiedades de tipo `ENUMERATION`, este campo proporciona las opciones disponibles. Debe contener al menos una opción. Cada opción es un objeto que contiene: - `name`: la etiqueta de la opción mostrada en HubSpot.
- `value`: el valor interno proporcionado por la ocurrencia del evento.
Los `name` y `label` deben ser únicos dentro del tipo de evento. |
| `objectPropertyName` | Cadena | Si se incluye, el nombre de la propiedad del objeto del CRM que debe actualizarse cuando se envíen los datos del evento a HubSpot. El valor de esta propiedad sobrescribirá cualquier valor existente en esa propiedad. Más información sobre el sellado de propiedades de registros del CRM abajo. |
### Sellado de propiedades
En algunos casos, puede que quieras modificar los valores de las propiedades del registro del CRM basándote en los datos de ocurrencia del evento de la aplicación. Por ejemplo, puede que quieras actualizar el nombre y apellidos de un contacto con los nuevos valores establecidos por la ocurrencia (por ejemplo, envío de formularios).
Para actualizar las propiedades de los registros del CRM mediante ocurrencias de eventos, puedes vincular una propiedad de evento a una propiedad de CRM dentro del esquema del tipo de evento. En los campos de definición de una determinada propiedad de evento, incluye el campo `objectPropertyName` y especifica la propiedad del CRM a enlazar. Una vez vinculada una propiedad, HubSpot siempre actualizará el valor de la propiedad en el registro del CRM utilizando el valor de la aparición más reciente basado en el campo `timestamp`.
Por ejemplo, el siguiente esquema de tipo de evento vincula la propiedad de evento `customerName` con una propiedad de contacto personalizada denominada `custom_property_name`. Cuando los datos de ocurrencia del evento incluyan un valor para `customerName`, se actualizará `custom_property_name` para el registro del CRM asociado.
```json theme={null}
"properties": [
{
"name": "customerName",
"label": "Customer Name",
"type": "string",
"objectPropertyName": "custom_property_name"
}
]
```
### Plantillas de renderizado
Los esquemas de tipo de evento pueden incluir los campos `headerTemplate` y `detailTemplate` para configurar cómo se muestran los eventos en las cronologías de los registros del CRM.
* `headerTemplate`: una descripción de una línea del acontecimiento en la parte superior de la tarjeta de actividad (hasta 1.000 caracteres).
* `detailTemplate`: los detalles del evento en el cuerpo de la tarjeta de actividad (hasta 10.000 caracteres).
Las plantillas de renderizado se escriben utilizando plantillas [Markdown](https://www.markdownguide.org/basic-syntax/) con [Handlebars](https://handlebarsjs.com/guide/). Estas plantillas pueden representar los datos de ocurrencias eventos de la siguiente manera:
* En ambas plantillas, puedes acceder a cualquier dato de `property` pasado por la ocurrencia del evento utilizando la sintaxis `{{propertyName}}`.
* En `detailTemplate`, puedes acceder adicionalmente a los valores `extraData` pasados por la ocurrencia del evento utilizando la sintaxis `{{extraData.fieldName}}`. Puedes acceder a cualquier nivel de atributo en `extraData` mediante la notación con puntos, como `{{extraData.person1.preferredName}}`.
El objeto `extraData` solo puede contener JSON válido. Si el JSON está malformado, la ocurrencia será rechazada y recibirás una respuesta de error.
Por ejemplo, las plantillas siguientes utilizan los datos de las propiedades `customerName` y `loginLocation`, junto con el campo `surveyData` de `extraData` [enviado a través de la ocurrencia del evento](#event-occurrences).
```json theme={null}
"headerTemplate": "{{customerName}} logged in via the {{loginLocation}}.",
"detailTemplate": "#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}",
```
Como las plantillas se construyen con Markdown y Handlebars, puedes aprovechar los ayudantes de Handlebars para que el contenido sea más dinámico. Por ejemplo, la `detailTemplate` incluye el [`#if` ayudante](https://handlebarsjs.com/guide/builtin-helpers.html#if) para renderizar condicionalmente el contenido en función de si los datos de ocurrencia del evento incluyen el campo `surveyData` en `extraData`.
* Si `extraData` contiene `surveyData`, muestra las respuestas de las encuestas posteriores al inicio de sesión.
* Si no había ningún `surveyData` en la ocurrencia del evento, muestra `No additional information.`.
```json theme={null}
"detailTemplate": "{{#if extraData.surveyData}}#### Post-login survey\n{{#each extraData.surveyData}}\n- **{{question}}**: {{answer}}\n{{/each}}{{else}}No additional information."
```
### Usar iframes
Cuando los datos de ocurrencia del evento contengan el campo `timelineIFrame`, la tarjeta de actividad de cronología incluirá un hipervínculo en el que los usuarios podrán hacer clic para abrir el contenido vinculado en un iframe.
```json theme={null}
"timelineIFrame": {
"linkLabel": "Click me",
"headerLabel": "This is an iframe",
"url": "https://hubspot.mintlify.io/en-us/apps/developer-platform/build-apps/overview",
"width": 300,
"height": 300
}
```
| Campo | Tipo | Descripción |
| ------------- | ------ | -------------------------------------------------------------------- |
| `linkLabel` | Cadena | El texto del hipervínculo que lanzará el iframe al hacer clic. |
| `headerLabel` | Cadena | La etiqueta de la ventana modal que muestra el contenido del iframe. |
| `url` | Cadena | La URL del contenido del iframe. |
| `width` | Entero | La anchura del modal del iframe. |
| `height` | Entero | La altura del modal del iframe. |
## Ocurrencias del evento
Para enviar ocurrencias de evento de un tipo de evento determinado, haz una petición a `POST` a los puntos finales que se indican a continuación. La API de eventos de la aplicación incluye endpoints para enviar ocurrencias de eventos individuales y lotes de ocurrencias de eventos múltiples. Para ambos endpoints, los datos de ocurrencia del evento tendrán que validarse con respecto a un esquema de tipo de evento existente, que especificarás con `eventTypeName` en el cuerpo de la solicitud.
Para enviar una ocurrencia de evento única, haz una solicitud de `POST` a `/integrators/timeline/v4/events`.
En el cuerpo de la solicitud, incluye los datos de la ocurrencia del evento, respetando el esquema definido para el tipo de suceso.
```json theme={null}
{
"eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"objectId": "123456",
"id": "login-1",
"properties": {
"customerName": "Mark S.",
"loginLocation": "mobileApp"
}
},
```
Para enviar un lote de ocurrencias, haz una solicitud de `POST` a `/integrators/timeline/v4/events/batch`.
En el cuerpo de la solicitud, incluye hasta 500 objetos de ocurrencias de eventos separadas por comas dentro de una matriz `inputs`. Si alguna ocurrencia no se valida, las ocurrencias validadas con éxito seguirán aceptándose y persistiendo.
```json theme={null}
{
"inputs": [
{
"EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"id": "login_event_100",
"objectId": "769851",
"properties": {
"customerName": "Tim",
"loginLocation": "mobileApp"
},
"extraData": {
"surveyData": [
{
"question": "How was your login experience?",
"answer": "Fine!"
},
{
"question": "How likely are you to recommend logging in to a co-worker?",
"answer": "Extremely likely"
}
]
}
},
{
"EventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"id": "login_event_101",
"objectId": "769851",
"properties": {
"customerName": "Tim",
"loginLocation": "website"
},
"extraData": {}
}
]
}
```
En el cuerpo de la solicitud, incluye datos basados en el esquema de tipo de evento definido. El cuerpo de la solicitud debe incluir la dirección `eventTypeName`, que puedes [recuperar a través de la API](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname).
```json theme={null}
{
"eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
"objectId": "8675309",
"properties": {
"customerName": "Mark S.",
"loginLocation": "mobileApp"
},
"id": "login-1529a3gda23",
"extraData": {
"surveyData": [
{
"question": "How was your login experience?",
"answer": "Fine!"
},
{
"question": "How likely are you to recommend logging in to a co-worker?",
"answer": "Extremely likely"
}
]
}
}
```
Los campos marcados con \* son obligatorios.
| Campo | Tipo | Descripción |
| ---------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventTypeName`\* | Cadena | El nombre completo del tipo de evento, que utilizarás para identificarlo a través de la API. Este valor lo establece automáticamente HubSpot y se puede [obtener a través de la API](/apps/developer-platform/add-features/app-events/create-and-manage-event-types#retrieve-the-fullyqualifiedname) después de crear el tipo de evento. Este valor no se puede cambiar después de la creación. |
| `objectId`\* | Cadena | El ID del registro del CRM a asociar con la ocurrencia del evento. Este campo puede utilizarse para todos los tipos de registros de CRM, y es el identificador recomendado. Más información sobre [la asociación de registros del CRM](#crm-record-association). |
| `email` | Cadena | Para la asociación de contactos, puedes proporcionar la dirección de correo electrónico del contacto a asociar. Más información sobre [la asociación de registros del CRM](#crm-record-association). |
| `utk` | Cadena | Para la asociación de contactos, puedes proporcionar la ficha de usuario de un contacto existente para asociarlo. Más información sobre [la asociación de registros del CRM](#crm-record-association). |
| `domain` | Cadena | Para la asociación de empresas, puedes proporcionar el dominio del sitio web de una empresa existente. Más información sobre [la asociación de registros del CRM](#crm-record-association). |
| `timestamp` | Cadena | Establece la hora de ocurrencia del evento (formato[ISO 8601](https://en.wikipedia.org/wiki/ISO_8601)). Si no se proporciona, HubSpot utilizará por defecto la marca de tiempo de cuando se envían los datos de ocurrencia del evento. |
| `properties` | Objeto | Pares clave-valor de nombres y valores de [propiedades](/apps/developer-platform/add-features/app-events/reference#event-properties) que has definido en el tipo de evento. |
| `extraData` | Matriz | Cuando se incluye, proporciona información adicional para la representación de la cronología. Debe ser JSON válido. Más información sobre [los datos adicionales en las plantillas de representación](#rendering-templates). |
| `timelineIFrame` | Objeto | Cuando se incluya, la tarjeta de cronología incluirá un hipervínculo que permitirá a los usuarios abrir los contenidos enlazados en un iframe. Más información sobre [el uso de iframes](#using-iframes). |
| `id` | Cadena | Un identificador único para la ocurrencia del evento. Debe ser único dentro del tipo de evento. Si no se proporciona, HubSpot generará un UUID aleatorio. Cuando varios eventos tengan el mismo ID, se aceptará el primero y se rechazarán todos los demás. |
Si alguna ocurrencia no se valida, las ocurrencias validadas con éxito seguirán aceptándose y persistiendo. El mensaje de error de la respuesta te proporcionará información sobre lo que tendrás que arreglar.
### Asociación de registros del CRM
Cada suceso debe estar asociado a un registro del CRM, con el tipo de objeto del CRM definido por el esquema de tipo de evento. La API de eventos de la aplicación incluye múltiples campos para asociar los datos de ocurrencia de eventos con los registros del CRM. Para todos los objetos del CRM compatibles, se recomienda utilizar el campo `objectId`. Sin embargo, hay algunas situaciones en las que puede que quieras utilizar los otros campos.
* `utk`/`email`: si no conoces el ID del contacto, utiliza el campo `utk` y/o `email` para identificarlo. Proporcionar estos dos identificadores también te permite crear y actualizar contactos. Por ejemplo:
* Si `utk` coincide con un contacto existente pero `email` no coincide, HubSpot actualizará el contacto con la nueva dirección de correo electrónico.
* Si no se proporciona `objectId`, el evento se asociará a un contacto existente que coincida con `utk`/`email`, o HubSpot creará un nuevo contacto si no se encuentra ninguna coincidencia.
* Ten en cuenta que `utk` por sí solo no puede crear nuevos contactos. Siempre debes incluir `email` con `utk` para garantizar una asociación adecuada.
* `domain`: para la asociación de empresas, debes proporcionar la dirección `objectId`, pero también puedes incluir `domain` para actualizar la propiedad `domain` de esa empresa.