Enviar finalizaciones de evento personalizado

Productos compatibles

Requisitos de ámbito

Los eventos personalizados son eventos definidos por la cuenta que almacenan detalles del evento en las propiedades del evento. Además de personalizar tu código de seguimiento para enviar datos de eventos a HubSpot, también puedes enviar datos de finalización de eventos a través de esta API. A continuación, aprende a utilizar la API para crear eventos personalizados y enviar o recuperar los datos de eventos personalizados.

Definir el evento

Para enviar datos de finalización de eventos a HubSpot, primero debes definir el evento en sí, incluidos sus metadatos, asociaciones de objetos de CRM y propiedades. Puedes definir eventos usando la API de definición de eventos personalizados, o, si tienes una suscripción a Marketing Hub Enterprise, puedes crear el evento en HubSpot. Al crear el evento, HubSpot proporcionará un conjunto de propiedades de evento predeterminadas que puedes usar para almacenar los datos del evento. También puedes crear propiedades adicionales para el evento. Estas propiedades se pueden crear o editar en cualquier momento. Una vez que hayas configurado tu evento, puedes enviarle datos a través de la API o al personalizar tu código de seguimiento de HubSpot.

Enviar datos de eventos

Para enviar datos de eventos a HubSpot, realiza una solicitud POST a https://api.hubspot.com/events/v3/send con los datos del evento en el cuerpo de la solicitud. Antes de enviar datos de eventos, revisa los límites a continuación, ya que exceder estos límites ocasionará un error.

{
  "eventName": "pe1234567_login_event",
  "objectId": "608051",
  "occurredAt": "2024-06-28T12:09:31Z",
  "properties": {
    "hs_city": "Cambridge",
    "hs_country": "United States",
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE",
    "hs_device_type": "PDA;Smartphone",
    "hs_touchpoint_source": "DIRECT_TRAFFIC"
  }
}

Parámetro	Tipo	Descripción
`eventName`	Cadena	El nombre interno del evento. Puedes encontrarlo consultando las definiciones de eventos existentes o dentro de la aplicación HubSpot.
`objectId`	Cadena	El ID del registro del CRM al que se asociará el evento. Para contactos, de forma alterna puedes usar el campo `email` o `utk` para identificar el contacto con la dirección de correo electrónico o el token de usuario de HubSpot. Todos los demás tipos de objetos requieren `objectId`, a menos que se defina un ID personalizado para el evento. Si se define un `customMatchingId` para el evento, HubSpot establecerá o anulará automáticamente el `objectId` según la asignación configurada. Obtén más información en la guía de definiciones de eventos personalizados.
`occurredAt`	Cadena	De forma predeterminada, HubSpot establecerá la marca de tiempo de finalización del evento en el momento en que se envía la solicitud. Para especificar la hora de finalización del evento, incluye una marca de tiempo en un campo `occurredAt` del cuerpo de la solicitud `POST` (formato ISO 8601). Esto puede ser útil para que los datos de eventos se actualicen para reflejar con mayor precisión la finalización de eventos en la realidad.
`properties`	Objeto	Las propiedades del evento al que se enviarán los datos. Esto puede incluir las propiedades de evento predeterminadas de HubSpot o cualquier propiedad personalizada que hayas definido para el evento. La mayoría de las propiedades de evento predeterminadas son propiedades de cadena, pero puedes ver todas las propiedades de evento disponibles consultando la definición del evento o navegando al evento en HubSpot. Si se ha configurado un ID de coincidencia personalizado para el evento, puedes omitir `objectId`. HubSpot intentará vincular el evento con un objeto del CRM ajustando el `objectId` en el evento basándose en la asignación configurada. Más información sobre las propiedades personalizadas del evento a continuación.

Nota:

Exceder cualquiera de los siguientes límites hará que la solicitud falle:

La etiqueta de la propiedad y el nombre interno están limitados a 50 caracteres.
Las propiedades de URL y referente pueden recibir hasta 1024 caracteres, mientras que todas las demás propiedades pueden recibir hasta 256 caracteres.
Cada finalización de evento puede contener datos de hasta 50 propiedades.
Los nombres internos de las propiedades deben empezar por una letra y contener solo letras minúsculas de la A a la Z, números del 0 al 9 y guiones bajos.
Las propiedades con el mismo nombre interno después de las minúsculas se consideran duplicadas y solo se utilizará una de las propiedades al finalizar. HubSpot ordenará de forma lexicográfica ascendente y mantendrá las últimas propiedades vistas entre las primeras 50 propiedades.
Hay un límite de 500 definiciones de eventos únicos por cuenta.
Hay un límite de 30 millones de finalizaciones de eventos por mes.

Recuperar datos de eventos

Para recuperar los datos de eventos de un contacto, haz una solicitud GET a /events/v3/events.

Para devolver todas las finalizaciones de un evento específico, incluye el parámetro eventType junto con el nombre interno del evento (por ejemplo, pe123456_custom_event). Puedes recuperar todos los tipos de eventos utilizando la API de análisis de eventos.
Para devolver las finalizaciones de eventos de un objeto concreto, incluye el parámetro objectType junto con los parámetros objectId o objectProperty.<property>. El objectType debe especificar el tipo de objeto del CRM (por ejemplo, contact), mientras que los otros parámetros especifican el valor del identificador único del objeto (ya sea el ID del registro o un valor de propiedad de identificador único). Para los contactos, puedes utilizar email como propiedad de identificador único.

Por ejemplo, para recuperar todos los eventos completados por un contacto específico, tu URL de solicitud podría ser: /events/v3/events?objectType=contact&objectId=111111. También puedes utilizar la dirección de correo electrónico del contacto: /events/v3/events?objectType=contacts&objectProperty.email=bilbo@shire.com Para filtrar los resultados por finalizaciones de eventos con un valor de propiedad de evento específico, puedes incluir el parámetro property.<propertyName>. Por ejemplo, para recuperar eventos de visitas a páginas de tu página de inicio, tu URL de solicitud podría ser: /events/v3/events?eventType=e_visited_page&property.hs_page_title=home

Para los valores de propiedad con espacios, sustitúyelos por %20 o +. Por ejemplo: property.hs_page_title=home+page.

Obtén más información sobre los parámetros disponibles en la documentación de referencia.

Propiedades de eventos

Los datos de eventos se almacenan en propiedades, ya sea en el conjunto de propiedades de eventos predeterminadas o en las propiedades definidas personalizadas. Cuando envíes los datos de eventos, incluye un objeto properties con pares clave-valor para las propiedades que quieras actualizar junto con los valores de las propiedades a almacenar.

"properties": {
    "property1": "string",
    "property2": "string",
    "property3": "string"
  }

Los valores que envíes dependerán del tipo de propiedad del evento. La mayoría de las propiedades de evento predeterminadas son texto de una sola línea (cadena). Sin embargo, puedes crear propiedades personalizadas de cualquier tipo para cada evento. Reseña la siguiente tabla al formatear valores de propiedad.

Tipo de propiedad	Descripción
`bool`	Un valor booleano, puede ser `true` o `false`.
`enumeration`	Una cadena que representa un conjunto de opciones. Al enviar varios valores, sepáralos con punto y coma. En HubSpot, este tipo corresponde a las propiedades de selección desplegable, selección en lista y múltiples casilla de verificación.
`date`	Un valor que representa un día, mes y año específicos. Los valores deben estar en la zona horaria UTC y el formato puede ser una cadena en notación ISO 8601 o una marca de tiempo EPOCH en milisegundos (es decir, la media noche en la zona horaria UTC).
`datetime`	Una marca de tiempo que representa un día, mes, año y hora específicos del día. Los valores deben estar en la zona horaria UTC y el formato puede ser una cadena en notación ISO 8601 o una marca de tiempo EPOCH en milisegundos.
`number`	Un valor numérico que contiene dígitos y, como máximo, un decimal. En HubSpot, este tipo corresponde a las propiedades numéricas y calculadas.
`string`	Una cadena de texto sin formato, limitada a 65.536 caracteres. En HubSpot, este tipo corresponde a propiedades de texto de una sola línea y de varias líneas.

Para ver las propiedades disponibles de un evento:

En tu cuenta de HubSpot, navega a Gestión de datos > Eventos personalizados.
En la tabla, haz clic en el nombre de la CTA.
En la parte superior, haz clic en la pestaña Propiedades.
En la tabla de propiedades, ve el tipo de propiedad bajo el nombre de la propiedad.

tabla-de-propiedades-de-eventos-personalizados

Informes de atribuciones

Los eventos de JavaScript, como el elemento seleccionado y los eventos de URL visitada, se rellenan automáticamente con datos del tipo de recurso e interacción para los informes de atribución. Para incluir los mismos datos para eventos con seguimiento manual, deberás incluir manualmente los datos en el cuerpo de la solicitud usando las propiedades de evento. Más información sobre cómo analizar los eventos personalizados. A continuación, conoce los valores disponibles para los tipos de recursos y las fuentes de interacción, junto con las solicitudes de ejemplo.

Tipo de recurso

Para atribuir un tipo de recurso específico a una solicitud de evento personalizado de comportamiento, incluye la propiedad hs_page_content_type en el cuerpo de la solicitud. Por ejemplo:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_id": "53005768010",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

También puedes utilizar la propiedad hs_asset_type. Si ambos hs_page_content_type y hs_asset_type están incluidos en una solicitud, hs_page_content_type anulará el valor hs_asset_type.

Los tipos de contenido estándar de HubSpot, como landing pages y publicaciones de blog, se pueden representar con los siguientes valores:

Valor	Descripción
`STANDARD_PAGE`	Una interacción con una página de sitio web.
`LANDING_PAGE`	Una interacción con una landing page.
`BLOG_POST`	Una interacción con un artículo de blog.
`KNOWLEDGE_ARTICLE`	Una interacción con un artículo de la base de conocimientos.

Para todos los demás tipos de recursos, usa los siguientes valores:

Valor	Descripción
`AD`	Una interacción con un anuncio, como un anuncio de Facebook o Google.
`CALL`	Una interacción a través de una llamada.
`CONTACT_IMPORT`	Una interacción a través de una importación de contacto.
`CONVERSATION`	Una interacción relacionada con una conversación de HubSpot.
`CUSTOM_BEHAVIORAL_EVENT_NAME`	El nombre interno de un evento personalizado, como `pe123456_manually_tracked_event`.
`EMAIL`	Una interacción a través de un correo electrónico.
`EXTERNAL_PAGE`	Una interacción con una página externa.
`INTEGRATIONS`	Una interacción a través de una integración.
`MARKETING_EVENT`	Una interacción con un evento de marketing.
`MEDIA_BRIDGE`	Una interacción a través del centro multimedia.
`MEETING`	Una interacción a través de una reunión.
`SALES_EMAIL`	Una interacción a través de un correo electrónico individual.
`SEQUENCE`	Una interacción con una secuencia.
`SOCIAL_POST`	Una interacción con una publicación en redes sociales.
`OTHER`	Una interacción con un recurso que no pertenece a una de las categorías anteriores.

Título del recurso

Para atribuir un evento personalizado a un recurso, incluye la propiedad hs_page_title o hs_asset_title en tu solicitud con el nombre del recurso con el formato como una cadena. Por ejemplo: hs_page_title:

{
  "eventName": "pe1234567_manually_tracked_event",
  "properties": {
    "hs_page_title": "Sweepstakes Sign Up",
    "hs_page_content_type": "LANDING_PAGE"
  },
  "objectId": "6091051"
}

Fuentes de interacción

Para atribuir un evento personalizado de comportamiento a una fuente específica, incluye la propiedad hs_touchpoint_source en tu solicitud con uno de los siguientes valores:

Valor	Descripción
`CONVERSATION`	La fuente de interacción es una conversación.
`DIRECT_TRAFFIC`	La fuente de interacción es el tráfico directo.
`EMAIL_MARKETING`	La fuente de interacción es un correo electrónico de marketing.
`HUBSPOT_CRM`	La fuente de interacción es el CRM de HubSpot.
`INTEGRATION`	La fuente de interacción es una integración.
`MARKETING_EVENT`	La fuente de interacción es un evento de marketing.
`OFFLINE`	La fuente de interacción está offline.
`ORGANIC_SEARCH`	La fuente de interacción es la búsqueda orgánica.
`OTHER_CAMPAIGNS`	La fuente de interacción es de una campaña sin categorizar.
`PAID_SEARCH`	La fuente de interacción es un anuncio de búsqueda de pago.
`PAID_SOCIAL`	La fuente de interacción es un anuncio de pago de redes sociales.
`REFERRALS`	La fuente de interacción es una referencia.
`SALES`	La fuente de interacción es ventas.
`SOCIAL_MEDIA`	La fuente de interacción es redes sociales (no un anuncio de pago de redes sociales).

Cuenta y configuración

Gestión de aplicaciones

Autenticación

Automatización

CMS

Preferencias de comunicación

Conversaciones

CRM

Eventos

Archivos

Marketing

Programador

Webhooks

Enviar finalizaciones de evento personalizado

Definir el evento

Enviar datos de eventos

Nota:

Recuperar datos de eventos

Propiedades de eventos

Informes de atribuciones

Tipo de recurso

Título del recurso

Fuentes de interacción

​Definir el evento

​Enviar datos de eventos

​Nota:

​Recuperar datos de eventos

​Propiedades de eventos

​Informes de atribuciones

​Tipo de recurso

​Título del recurso

​Fuentes de interacción

Definir el evento

Enviar datos de eventos

Nota:

Recuperar datos de eventos

Propiedades de eventos

Informes de atribuciones

Tipo de recurso

Título del recurso

Fuentes de interacción