API del CMS | Centro multimedia

La API del 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 insertar 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 basadas en eventos de consumo de contenido multimedia.
• Informes para medir el impacto de los recursos multimedia.

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

​

Usar la API del centro multimedia

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

​

Crear y personalizar las definiciones de objetos multimedia

Para definir un objeto multimedia, realiza una solicitud POST a /media-bridge/v1/{appId}/settings/object-definitions. En el cuerpo de la solicitud, incluye cualquiera de los siguientes valores de tipo de medio mediaTypes dentro de la matriz: VIDEO, AUDIO, DOCUMENT, IMAGE o 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}.

​

Conectar la aplicación del centro multimedia con la cuenta de un usuario de HubSpot

Para conectar tu aplicación del centro multimedia con la cuenta de un usuario de HubSpot, debes crear una definición de aplicación en tu cuenta de 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.
• Permisos que tu integración necesita en la cuenta de HubSpot del usuario.

Para conectar tu aplicación del 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 del centro multimedia.
• Incluye los siguientes permisos 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. Consulta más información sobre los métodos de autenticación.

Para verificar que la aplicación está instalada correctamente en la cuenta de HubSpot del cliente:

• Visita https://app.hubspot.com/media-bridge-demo/{HubID}, y reemplaza el {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 del 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 del centro multimedia se ha instalado en la cuenta de HubSpot del cliente, puedes:

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

​

Crear objetos multimedia

Después de crear las definiciones de objetos multimedia e instalar tu aplicación del 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 endpoints de la API de objetos personalizados para crearlos:

• Haz una solicitud GET a /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} para encontrar 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 de inserción en un sistema de terceros. Una vez que se agrega un objeto multimedia al centro multimedia, se puede insertar en el contenido del CMS de HubSpot y asociarlo con eventos multimedia. Para los objetos multimedia VIDEO y AUDIO, las siguientes tablas enumeran todas las propiedades disponibles:

Los campos marcados con * son obligatorios.

Parámetro	Tipo	Descripción
id	Número	Un ID utilizado para identificar el contenido multimedia específico en el sistema del centro multimedia de HubSpot. Esto se autogenera por HubSpot y no pueden configurarlo los desarrolladores.
hs_duration	Número	La duración del contenido multimedia en milisegundos.
hs_oembed_url*	Cadena	Una URL que debe devolver una respuesta válida oEmbed que sigue la especificación oEmbed. Requiere un tipo video o rich con un iframe en html.
hs_file_url	Cadena	La URL del archivo multimedia sin formato. Esto puede utilizarse en el futuro para permitir la inserción en redes sociales.
hs_thumbnail_url	Cadena	URL de una imagen utilizada como miniatura para insertar los elementos multimedia en el contenido. El tamaño ideal para esta miniatura es de 640x480 píxeles.
hs_poster_url	Cadena	URL de una imagen que representa el contenido multimedia. Esta imagen debe tener las mismas dimensiones que los medios originales y se puede usar en los lugares donde se necesita un parámetro de sustitución de imagen (por ejemplo, cuando se inserta el contenido multimedia en un correo electrónico).
hs_external_id	Cadena	El ID del contenido multimedia en el sistema de terceros. Esto les da a los integradores la capacidad de recuperar medios del centro multimedia según el ID que usan en su propio sistema. (Este es el endpoint de API que utiliza este mapeo)
hs_folder_path	Cadena	Una ruta suministrada por el proveedor al objeto, destinada a representar la ubicación del objeto en el sistema de carpetas del tercero (si existe). HubSpot intentará representar la estructura de directorios al mostrar estos objetos al usuario, pero puede anidar los objetos y carpetas de cada proveedor dentro de una carpeta de nivel superior con el nombre del proveedor.
hs_title*	Cadena	El nombre del contenido multimedia. Esto se mostrará dentro de la interfaz de usuario de HubSpot en lugares como el selector de medios.
hs_details_page_link	Cadena	Una URL que permite a un usuario ver los elementos multimedia o interactuar con ellos en el sistema del proveedor de elementos multimedia. Esto se utiliza en la interfaz de usuario de HubSpot para dar a los usuarios la capacidad de identificar el contenido multimedia sin depender solo del título.

Para los objetos multimedia IMAGE, las siguientes tablas muestran todas las propiedades disponibles:

Los campos marcados con * son obligatorios.

Parámetro	Tipo	Descripción
id	Número	Un ID utilizado para identificar el contenido multimedia específico en el sistema del centro multimedia de HubSpot. Esto se autogenera por HubSpot y no pueden configurarlo los desarrolladores.
hs_oembed_url*	Cadena	Una URL que debe devolver una respuesta válida oEmbed que sigue la especificación oEmbed. Requiere un tipo video o rich con un iframe en html.
hs_file_url*	Cadena	La URL del archivo de medios sin formato. Esto puede utilizarse en el futuro para permitir la inserción en redes sociales.
hs_thumbnail_url	Cadena	URL de una imagen que se usará como miniatura al insertar contenido multimedia en ubicaciones como el selector de contenido. El tamaño ideal para esta miniatura es de 640x480 píxeles.
hs_poster_url	Cadena	URL de una imagen que representa el contenido multimedia. Esta imagen debe tener las mismas dimensiones que los medios originales y se puede usar en los lugares donde se necesita un parámetro de sustitución de imagen (por ejemplo, cuando se inserta el contenido multimedia en un correo electrónico).
hs_external_id	Cadena	El ID del contenido multimedia en el sistema de terceros. Esto les da a los integradores la capacidad de recuperar medios del centro multimedia según el ID que usan en su propio sistema. (Este es el endpoint de API que utiliza este mapeo)
hs_folder_path	Cadena	Una ruta suministrada por el proveedor al objeto, destinada a representar la ubicación del objeto en el sistema de carpetas del tercero (si existe). HubSpot intentará representar la estructura de directorios al mostrar estos objetos al usuario, pero puede anidar los objetos y carpetas de cada proveedor dentro de una carpeta de nivel superior con el nombre del proveedor.
hs_title*	Cadena	El nombre del contenido multimedia. Esto se mostrará dentro de la interfaz de usuario de HubSpot en lugares como el selector de medios.
hs_details_page_link	Cadena	Una URL que permite a un usuario ver el contenido multimedia o interactuar con ellos en el sistema del proveedor de medios. Esto se utiliza en la interfaz de usuario de HubSpot para dar a los usuarios la capacidad de identificar el contenido multimedia sin depender solo del título.

​

Crear módulos del CMS para insertar elementos multimedia

Cada proveedor de aplicación del centro multimedia es responsable de crear su propio módulo para renderizar su contenido multimedia en el CMS de HubSpot. Cuando se instala una aplicación del centro multimedia en una cuenta de HubSpot, el campo insertar en el módulo tiene un tipo de origen de integración de elementos multimedia adicional. Esto le permite al usuario seleccionar elementos multimedia de la aplicación instalada para insertarlos en la página de su sitio web. Después de que el usuario selecciona el elemento multimedia específico que se va a insertar, el contenido multimedia oembed_url y oembed_response están disponibles en HubL para renderizar fácilmente los reproductores. Adicionalmente, el id y el media_type del contenido multimedia seleccionado 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 HubL crm_objects 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 endpoints de la API del código origen del 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.

​

Configurar un dominio oEmbed

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 a la función HubL oEmbed con la API de oEmbed. Los valores comodín se admiten utilizando * (por ejemplo, www.domain.com/*).
• URL: la URL de la API de oEmbed. La URL multimedia se pasa a esta URL a través de un parámetro URL.
• Descubrimiento (booleano): determina si tu API 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.

​

Crear un módulo personalizado

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 crear hoy y selecciona Módulo.
• Haz clic en Siguiente.
• Selecciona la casilla de verificación junto a cada tipo de contenido en el que se utilizará el módulo: páginas, publicaciones de blog, páginas de índice de blogs, correos electrónicos o cotizaciones. Los módulos utilizados en las 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á toda ubicación donde se utilizó 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 Insertar.

• En la sección Tipos de origen compatibles, selecciona Integración multimedia.
• En la sección Contenido insertado predeterminado, haz clic en Seleccionar desde la [aplicación del centro multimedia]
• En el panel derecho, selecciona el contenido multimedia que deseas insertar en el módulo.
• Establece cualquiera de las opciones de edición, condiciones de presentación de campos y opciones de repetidor de campos.
• Bajo el 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 la [aplicación del centro multimedia] y luego selecciona el elemento multimedia que deseas previsualizar.

​

Envía tus eventos multimedia

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 del centro multimedia, se puede usar en informes y en las tarjetas CRM de la cronología. Hay tres tipos de eventos multimedia:

• Evento de reproducción: representa cuándo un usuario comienza a reproducir un elemento multimedia. Este evento está disponible tanto en la cronología de los contactos como en la herramienta de informes.
• 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. Este evento solo está disponible en la cronología de contactos.
• 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. Este evento solo está disponible dentro de la herramienta de informes.

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 respectively. 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 del 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 endpoints de eventos v2, se procesan de forma asincrónica, a diferencia de los enviados a través de los endpoints v1. Por lo tanto, recomendamos lo siguiente:

• La versión v1 de los endpoints debe usarse para cualquier prueba, ya que una solicitud errónea se eliminará inmediatamente.
• La versión v2 de los endpoints debe usarse en producción, ya que su naturaleza asincrónica 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.

​

Conectar un evento con un registro de contacto

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 veraz. Este parámetro permite a la aplicación del 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 multiobjeto. Esto permite a los clientes vincular sus eventos multimedia con los registros de contacto, así como con las empresas y negocios asociados.

​

Conexión de un evento con un elemento multimedia

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

​

Conectar un evento con una página

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:

Propiedad	Tipo de evento	Descripción
mediaBridgeObjectId	Todos los eventos	El ID del contenido multimedia con los que se relaciona este evento.
externalId	Cadena	El ID del contenido multimedia en el sistema de terceros. Esto les da a los desarrolladores la capacidad de referirse al contenido multimedia en el centro multimedia basándose en el mismo identificador que usan en su propio sistema. Esto se puede utilizar en lugar del mediaBridgeObjectId en eventos. Si se proporcionan tanto un externalId como mediaBridgeObjectId, se utilizará el mediaBridgeObjectId y el externalId se ignorará.
sessionId	Todos los eventos	Un identificador único para representar una sesión de visualización. Esto puede significar cosas diferentes para diferentes proveedores y HubSpot permite que los proveedores decidan qué significa una sesión para ellos. Esto se utilizará para agrupar eventos que ocurrieron en la misma sesión. Se espera que esto lo genere el sistema del tercero.
contactId	Todos los eventos	El ID del contacto en el sistema de HubSpot que consumió el contenido multimedia. Esto se puede buscar utilizando la API para obtener contactos mediante el token de usuario (utk) de HubSpot. La API también admite el suministro de un usertoken, y se encargará de convertirlo en un ID de contacto automáticamente.
contactUtk	Todos los eventos	El usertoken (utk) que identifica qué contacto consumió los medios.
pageId	Todos los eventos	El ID de contenido de la página en la que se produjo un evento.
pageName	Todos los eventos	El nombre o el título de la página en la que se produjo un evento.
pageUrl	Todos los eventos	La URL de la página en la que se produjo un evento.
occurredTimestamp	Todos los eventos	La marca de tiempo en la que ocurrió este evento, en milisegundos desde la época (epoch).
rawDataString / rawDataMap	Capacidad de atención	Estos son los datos sin formato que proporcionan los datos más granulares sobre los períodos del contenido multimedia y cuántas veces cada período fue consumido por el usuario. Por ejemplo, en un video de 10 segundos donde cada segundo representa un tramo, si un visitante ve los primeros 5 segundos del video, luego lo reinicia y vuelve a ver los primeros 2 segundos, el rawDataString resultante sería “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”.
totalPercentPlayed	Capacidad de atención	El porcentaje del contenido multimedia que el usuario consumió. Los proveedores pueden calcular esto de manera diferente según la forma en que consideren las vistas repetidas de la misma parte del contenido multimedia. Por esta razón, la API no intentará validar totalPercentWatched con respecto a la capacidad de atención del evento. Si hace falta, HubSpot calculará a partir del mapa de capacidad de atención de la siguiente manera: número de períodos con un valor de 1 o más sobre el número total de capacidades).
totalSecondsPlayed	Capacidad de atención	Los segundos que un usuario pasó consumiendo el contenido multimedia. El centro multimedia calcula esto como totalPercentPlayed*mediaDuration. Si un proveedor desea que esto se calcule de manera diferente, puede proporcionar el valor previamente calculado cuando crea el evento
playedPercent	Evento de cuartil	Un valor de porcentaje del cuartil (0, 25, 50, 75, 100) para saber cuánto de los elementos multimedia se ha consumido hasta ahora.
iframeUrl	Evento de reproducción	Una URL que se puede utilizar para mostrar datos de un sistema externo utilizando un iFrame. Cuando se incluya, el evento de la cronología del contacto mostrará un enlace que abrirá una ventana modal que muestra el contenido del iFrame cuando se hace clic.
mediaType	Cadena	El tipo multimedia al que pertenece el evento (por ejemplo, VIDEO o AUDIO) Esto nos permite asignar adecuadamente el evento a los objetos correctos cuando un solo proveedor admite varios tipos de elementos multimedia.