Referencia de eventos de aplicación (BETA)

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).

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.
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.

{
  "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 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 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.

 "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.

 "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 con Handlebars. 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. Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos.

Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos.

"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 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..

Captura de pantalla que muestra cómo se vería el código de ejemplo en la cronología de contactos.

"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. Captura de pantalla de un enlace incluido en una ficha de actividad de cronología gracias al campo timelineIFrame

Captura de pantalla de un enlace incluido en una ficha de actividad de cronología gracias al campo timelineIFrame

"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.

Enviar una ocurrencia única
Enviar un lote de ocurrencias

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.

{
  "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.

{
  "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.

{
  "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 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.
`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.
`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.
`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.
`timestamp`	Cadena	Establece la hora de ocurrencia del evento (formatoISO 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 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.
`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.
`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. Captura de pantalla de un ejemplo de mensaje de error que puedes recibir al enviar datos de sucesos

Captura de pantalla de un ejemplo de mensaje de error que puedes recibir al enviar datos de sucesos

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.

Crear aplicaciones

Agregar funciones

Publicar en el mercado de HubSpot

Referencia de eventos de aplicación (BETA)

Estructura del proyecto

Esquema del tipo de evento

Propiedades de eventos

Sellado de propiedades

Plantillas de renderizado

Usar iframes

Ocurrencias del evento

Asociación de registros del CRM

​Estructura del proyecto

​Esquema del tipo de evento

​Propiedades de eventos

​Sellado de propiedades

​Plantillas de renderizado

​Usar iframes

​Ocurrencias del evento

​Asociación de registros del CRM

Estructura del proyecto

Esquema del tipo de evento

Propiedades de eventos

Sellado de propiedades

Plantillas de renderizado

Usar iframes

Ocurrencias del evento

Asociación de registros del CRM