API de Centro multimedia

La API de Centro multimedia permite a los integradores insertar objetos multimedia como archivos de video y audio, y datos de consumo de medios en HubSpot. También crea las siguientes características en la cuenta de HubSpot del usuario: 

• Módulos para incrustar objetos multimedia en los editores de arrastrar y soltar de HubSpot para páginas y correos electrónicos. 
• Eventos de la cronología del CRM que se muestran cuando los prospectos o clientes han interactuado con videos, audio y otros tipos de medios. 
• Listas segmentadas para experiencias específicas y personalizadas.
• Workflows para automatizar interacciones, según eventos de consumo de elementos multimedia.
• Informes para medir el impacto de los materiales multimedia.

El centro multimedia utiliza tanto objetos personalizados como eventos unificados, el sistema de seguimiento de eventos de HubSpot. Esto significa que puedes usar tanto la API de Centro multimedia como la API de objetos personalizados para crear tu integración. 

Necesitas una cuenta de desarrollador de HubSpot para registrar tu aplicación de Centro multimedia y configurar tus definiciones iniciales de objetos multimedia antes de conectar tu aplicación a la cuenta de un usuario de HubSpot. 

Para definir un objeto multimedia, realiza una solicitud POST a /media-bridge/{appId}/settings/object-definitions. Usarás el parámetro mediaTypes para definir el objeto: VIDEO, AUDIO, DOCUMENT, IMAGE u OTHER. 

Después de definir los objetos multimedia, crea y modifica las propiedades del objeto multimedia realizando una solicitud PATCH a /media-bridge/v1/{appId}/schemas/{objectType} y una solicitud POST a /media-bridge/v1/{appId}/properties/{objectType}. 

Cualquier llamada a la API realizada incluirá su ID de cuenta de desarrollador como el parámetro de consulta portalID. 

Para conectar tu aplicación de centro multimedia con la cuenta de un usuario de HubSpot, debes crear una definición de aplicación en la cuenta de tu desarrollador de HubSpot para la aplicación. Las definiciones de la aplicación incluyen:

• Detalles como el logotipo y el texto que se mostrarán al usuario de HubSpot cuando tu integración intente realizar una conexión inicial a su cuenta.
• Examina tus necesidades de integración en la cuenta de HubSpot del usuario. 

Para conectar tu aplicación de centro multimedia con la cuenta de un usuario de HubSpot: 

• Crea una definición de aplicación en tu cuenta de desarrollador para la aplicación de centro multimedia.
• Incluye los siguientes alcances al definir tu aplicación: 
  • media_bridge.read
  • media_bridge.write
• Utiliza la autenticación OAuth al autenticar las llamadas realizadas por tu aplicación. Más información sobre métodos de autentificación.

Para verificar que la aplicación está instalada correctamente en el portal de un cliente:

• Visita https://app.hubspot.com/media-bridge-demo/{HubID}, reemplazando {HubID} con el ID de la cuenta.
• En la esquina superior derecha, haz clic en el menú desplegable Aplicación y selecciona la aplicación de centro multimedia. 
• En la aplicación, puedes ver los tipos de medios compatibles de la aplicación y crear elementos multimedia de ejemplo.

Una vez que la aplicación de centro multimedia se ha instalado en el portal de un cliente, puedes:

• Crear objetos multimedia
• Crear módulos del CMS para incrustar tus objetos de medios
• Enviar eventos multimedia

Después de crear tus definiciones de objetos multimedia e instalar tu aplicación de centro multimedia en la cuenta de un usuario, puedes usar el token OAuth para crear y modificar objetos multimedia en la cuenta. Como los objetos multimedia son objetos personalizados, usa los puntos de terminación de la API de objetos personalizados para crearlos:

• Haz una solicitud GET a /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} para encontrar el objectType.
• Haz una solicitud POST a /crm/v3/objects/{objectType} para crear el objeto multimedia en la cuenta del usuario. 

Un objeto multimedia representa un fragmento de contenido incrustable en un sistema de tercero. Una vez que se agrega un objeto multimedia al centro multimedia, se puede incrustar en el contenido de CMS de HubSpot y asociarlo con eventos multimedia.

Para los objetos multimedia VIDEO y AUDIO, las tablas a continuación indican todas las propiedades predeterminadas y requeridas (* denota requerido): 

Para los objetos multimedia de IMAGE, las tablas a continuación indican todas las propiedades predeterminadas y requeridas (* denota requerido): 

Cada proveedor es responsable de crear su propio módulo para representar sus medios en el CMS de HubSpot. 

Cuando se instala una aplicación de centro multimedia en una cuenta de HubSpot, el campo Insertar en el módulo tiene un tipo de fuente Integración de elementos multimedia adicional. Esto le permite al usuario seleccionar elementos multimedia de la aplicación instalada para incrustarlos en la página de su sitio web.

Después de que el usuario selecciona un elemento multimedia específico que se va a incrustar, la oembed_url y la oembed_response de los medios están disponibles en HubL para renderizar fácilmente los reproductores. Además, el id y el media_type de los medios seleccionados se almacenan para habilitar la consulta del objeto del CRM subyacente a través de la función crm_objects de Hubl. Esto se puede usar para extraer cualquiera o todas las propiedades que son parte de un objeto multimedia.

Un ejemplo de uso de la función crm_objects HubL con un objeto multimedia donde los ID son 459 y 922:

{% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }}

Para buscar una imagen específica con el mismo objeto: {% set object = crm_object("a123_Images", 459) %}{{ object }}

Las aplicaciones pueden buscar el tipo de objeto ("a123_Videos" en el ejemplo) haciendo una solicitud GET a /media-bridge/{appId}/settings/object-definitions/{mediaType}.

Los desarrolladores deben usar los puntos de terminación de la API del código fuente de CMS para insertar su código de módulo personalizado en las cuentas de los clientes una vez que los clientes se hayan conectado a través de oAuth. Una vez que el código del módulo se introduce en la cuenta del cliente, automáticamente podrán comenzar a usar el módulo del desarrollador en su contenido.

Para utilizar la función HubL oEmbed, el dominio que se utiliza para obtener la respuesta oEmbed debe registrarse haciendo una solicitud a /media-bridge/v1/{appId}/settings/oembed-domains. Se deben incluir los siguientes parámetros:

• Esquema: el patrón de URL para las URL de los elementos multimedia. Este patrón de URL se usa para hacer coincidir la URL pasada a la función oEmbed HubL con tu API de oEmbed. Los valores comodín son compatibles con * (por ejemplo, www.domain.com/*).

• URL: la URL de la API de oEmbed. La URL del elemento multimedia se pasa a esta URL a través de un parámetro de URL. 
• Descubrimiento (booleano): determina si tu API de oEmbed admite o no la función Discovery de oEmbed. 

Por opción predeterminada, los dominios oEmbed registrados estarán disponibles para todos los clientes que hayan instalado tu aplicación. Si tienes dominios personalizados que son únicos para cada cliente, puedes especificar en qué cuenta se debe permitir el uso de un dominio oEmbed pasando un valor portalId a la solicitud de API al configurar el dominio oEmbed. Esto garantizará que solo la cuenta de HubSpot especificada pueda usar ese dominio oEmbed. 

Para crear un módulo personalizado:

• Navega a Marketing > Archivos y plantillas > Herramientas de diseño. 
• En la parte superior izquierda, haz clic en Archivo  > Archivo nuevo.
• En el cuadro de diálogo, haz clic en el menú desplegable ¿Qué te gustaría construir hoy? y selecciona Módulo. 
• Haz clic en Siguiente. 
• Selecciona la casilla de comprobación junto a cada tipo de contenido en el que se utilizará el módulo: páginas, publicaciones de blog, anuncios de blogs, correos electrónicos o cotizaciones. Los módulos utilizados en plantillas de correo electrónico no pueden incluir CSS o JavaScript. 
• Selecciona si este módulo será un módulo local o un módulo global. Si creas un módulo global, editar el contenido de este módulo actualizará cada ubicación donde se use el módulo. 
• Introduce un nombre de archivo para tu módulo y haz clic en Crear.
• En la sección Campos a la derecha, haz clic en el menú desplegable Agregar campo y selecciona Incrustar. 

• En la sección Tipos de fuentes compatibles, selecciona Integración multimedia.
• En la sección Contenido incrustado predeterminado, haz clic en Seleccionar desde [media bridge app].
• En el panel derecho, selecciona el elemento multimedia que deseas incrustar en el módulo. 
• Establece cualquiera de las opciones de editor, condiciones de presentación de campos y opciones de repetidor de campos. 
• En Nombre de la variable HubL, haz clic en Copiar > Copiar fragmento.
• Pega el fragmento en la sección module.html.
• Para obtener una vista preliminar de cómo se verá el módulo en tu página, haz clic en Vista preliminar.
• En la sección de la izquierda, haz clic en Seleccionar desde [media bridge app] y luego selecciona el elemento multimedia que deseas previsualizar. 

Un evento multimedia es un evento que ocurre en relación con un objeto multimedia, como un evento de reproducción. Una vez que se envía un evento multimedia a la aplicación de centro multimedia, se puede usar en informes y en tarjetas CRM de línea de tiempo. 

Hay tres tipos de eventos multimedia:

• Evento reproducción: representa cuándo un usuario comienza a reproducir un elemento multimedia. 

• Evento de cuartil: representa cuándo un usuario alcanzó hitos trimestrales (0%, 25%, 50%, 75%, 100%) en términos de cuántos elementos multimedia ha consumido. 

• Evento de período de atención: representa cuando un usuario haya consumido completamente un elemento multimedia o cuando el usuario haya completado su sesión.

Los eventos se pueden enviar haciendo una solicitud POST a /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent y /media-bridge/v2/events/attention-span respectivamente. 

Para que los eventos multimedia se muestren en la cronología de contacto del usuario en HubSpot, se debe enviar un evento de reproducción a la aplicación de centro multimedia para cada sesión. Los eventos de una sola sesión se mostrarán en una tarjeta en la cronología de actividad de contacto. 

Cuando los eventos se envían utilizando los puntos de terminación de eventos v2, se procesan de forma asíncrona, a diferencia de los enviados a través de los puntos de terminación v1. Como tal, recomendamos lo siguiente:

• La versión v1 de los puntos de terminación debe usarse para cualquier prueba, ya que una solicitud errónea se eliminará inmediatamente.
• La versión v2 de los puntos de terminación debe usarse en la producción, ya que su naturaleza asíncrona ayudará a evitar retrasos en el cliente mientras se escribe el evento en el centro multimedia. Los eventos también se retienen y se vuelven a intentar en caso de una falla temporal en el servidor del centro multimedia.

Para conectar un evento multimedia con un registro de contacto, los integradores deben proporcionar un contactId o un contactUtk. Si solo se proporciona un contactUtk, se convertirá en un contactId. Si ambos se proporcionan en la solicitud, el contactId se utilizará como fuente de la verdad. Este parámetro permite a la aplicación de centro multimedia crear una asociación entre el registro de contacto y el evento.

Una vez que un evento multimedia se ha conectado a un registro de contacto, el evento se puede usar en informes de objetos cruzados. Esto permite a los clientes vincular sus eventos multimedia con los registros de contacto, así como con las empresas y negocios asociados.

Para asociar un evento multimedia a un elemento multimedia específico, se deben incluir en la solicitud los parámetros mediaID o externalID. Si se proporcionan ambos, el mediaID se utilizará como fuente de la verdad.

Para asociar un evento multimedia a una página de HubSpot, se deben incluir los siguientes parámetros en la solicitud:

• Si la página está alojada en el CMS de HubSpot, se debe proporcionar el pageId.
• Si la página no está alojada en el CMS de HubSpot, se debe incluir pageName y pageUrl.

La siguiente tabla describe las propiedades compatibles para los tres eventos multimedia: