Pular para o conteúdo principal
A API de media bridge permite que os integradores enviem objetos de mídia, como arquivos de vídeo e áudio, bem como dados de consumo de mídia para o HubSpot. Também cria os seguintes recursos na conta da HubSpot do usuário:
  • Módulos para incorporar os objetos de mídia aos editores de arrastar e soltar do HubSpot para páginas e e-mails.
  • Eventos da linha do tempo do CRM que mostram quando os prospects ou clientes se envolveram com vídeos, áudio e outros tipos de mídia.
  • Listas segmentadas para experiências direcionadas e personalizadas.
  • Fluxos de trabalho para automatizar interações, com base em eventos de consumo de mídia.
  • Relatórios para avaliar o impacto dos ativos de mídia.
O media bridge usa objetos personalizados e eventos unificados — o sistema de rastreamento de eventos da HubSpot. Assim, você pode usar a API de media bridge e a API de objetos personalizados para criar sua integração.

​
Usar a API de media bridge

Você precisa de uma conta de desenvolvedor da HubSpot para registrar seu aplicativo de media bridge e configurar suas definições iniciais de objeto de mídia antes de conectar seu aplicativo a uma conta de usuário da HubSpot.

​
Criar e personalizar as definições dos objetos de mídia

Para definir um objeto de mídia, faça uma solicitação POST para /media-bridge/v1/{appId}/settings/object-definitions. No corpo da solicitação, inclua qualquer um dos seguintes valores de tipo de mídia dentro da matriz mediaTypes: VIDEO, AUDIO, DOCUMENT, IMAGE ou OTHER. Depois de definir seus objetos de mídia, crie e modifique as propriedades deles fazendo uma solicitação PATCH para /media-bridge/v1/{appId}/schemas/{objectType} e uma solicitação POST para /media-bridge/v1/{appId}/properties/{objectType}.

​
Conectar o aplicativo de media bridge a uma conta de usuário da HubSpot

Para conectar seu aplicativo de media bridge a uma conta de usuário da HubSpot, você deve criar uma definição de aplicativo em sua conta de desenvolvedor da HubSpot. As definições do aplicativo incluem:
  • Detalhes como o logotipo e o texto a serem mostrados para o usuário do HubSpot quando sua integração tenta estabelecer uma conexão inicial com sua conta.
  • Analisa as necessidades de integração na conta da HubSpot do usuário.
Para conectar seu aplicativo de media bridge a uma conta de usuário da HubSpot:
  • Crie uma definição de aplicativo em sua conta de desenvolvedor para o aplicativo de media bridge.
  • Inclua os seguintes escopos ao definir o aplicativo:
    • media_bridge.read
    • media_bridge.write
  • Use a autenticação OAuth ao autenticar chamadas feitas pelo aplicativo. Saiba mais sobre métodos de autenticação.
Para verificar se o aplicativo está instalado corretamente na conta HubSpot de um cliente:
  • Acesse https://app.hubspot.com/media-bridge-demo/{HubID}, substituindo {HubID} pelo ID da conta.
  • No canto superior direito, clique no menu suspenso Aplicativo e selecione aplicativo de media bridge.
  • No aplicativo, você pode visualizar os tipos de mídia aceitos pelo aplicativo e criar exemplos de mídias.
Depois que o aplicativo Media Bridge for instalado na conta HubSpot de um cliente, você poderá:

​
Criar seus objetos de mídia

Depois de criar as definições de objeto de mídia e instalar o aplicativo de media bridge na conta de um usuário, você pode usar o token de OAuth para criar e modificar objetos de mídia na conta. Como os objetos de mídia são objetos personalizados, use os pontos de extremidade da API de objetos personalizados para criá-los:
  • Faça uma solicitação GET para /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} para encontrar objectType.
  • Faça uma solicitação POST para /crm/v3/objects/{objectType} para criar o objeto de mídia na conta do usuário.
Um objeto de mídia representa um conteúdo incorporável em um sistema de terceiros. Assim que um objeto de mídia for adicionado ao media bridge, ele poderá ser incorporado ao conteúdo do HubSpot CMS e associado aos eventos de mídia. Para objetos de mídiaVIDEO e AUDIO, as tabelas abaixo listam todas as propriedades disponíveis:

Campos marcados com * são obrigatórios.

Para objetos de mídia IMAGE, as tabelas abaixo listam todas as propriedades disponíveis:

Campos marcados com * são obrigatórios.

​
Criar módulos do CMS para incorporar mídia

Cada provedor de aplicativos de media bridge é responsável por criar seu próprio módulo para renderizar mídias no HubSpot CMS. Quando um aplicativo de media bridge é instalado em uma conta da HubSpot, Incorporar campo no módulo tem um tipo de fonte adicional para Integração de mídia. Assim, o usuário pode selecionar a mídia do aplicativo instalado para ser incorporada na página do site. Depois que o usuário seleciona uma peça de mídia para incorporar, o oembed_url e o oembed_response da mídia ficam disponíveis no HubL para renderizar facilmente os reprodutores. Além disso, o id e media_type de mídia selecionada são armazenados para permitir a consulta do objeto CRM subjacente por meio da Função HubL crm_objects. Isso pode ser usado para buscar uma ou todas as propriedades que fazem parte de um objeto de mídia. Um exemplo de uso da Função HubL crm_objects com um objeto de mídia onde os IDs são 459 e 922: {% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }} Para buscar uma imagem específica com o mesmo objeto: {% set object = crm_object("a123_Images", 459) %} {{ object }} Os aplicativos podem buscar o tipo de objeto (“a123_Videos” no exemplo) fazendo uma solicitação GET para/media-bridge/{appId}/settings/object-definitions/{mediaType}. Os desenvolvedores devem usar os pontos de extremidade da API de código-fonte do CMS para enviar seu código de módulo personalizado para as contas dos clientes, assim que eles se conectarem via oAuth. Assim que o código do módulo for enviado para a conta do cliente, ele poderá usar automaticamente o módulo do desenvolvedor no seu conteúdo.

​
Configurar um domínio oEmbed

Para usar a função oEmbed do HubL, o domínio usado para buscar a resposta oEmbed deve ser registrado fazendo uma solicitação para /media-bridge/v1/{appId}/settings/oembed-domains. Os seguintes parâmetros devem ser incluídos:
  • Esquema: o padrão de URL para as URLs de mídia. Este padrão de URL é usado para corresponder o URL passado para a função oEmbed do HubL à API oEmbed. Valores curingas podem ser usados com * (por exemplo, www.domain.com/*).
  • URL: o URL da sua API oEmbed. A URL de mídia é passada para essa URL por meio de um parâmetro URL.
  • Descoberta (Booleano): determina se sua API oEmbed suporta ou não o recurso Descoberta de oEmbed.
Por padrão, os domínios oEmbed registrados serão disponibilizados para todos os clientes que instalaram o aplicativo. Se você tiver domínios personalizados que são exclusivos para cada cliente, poderá especificar em qual conta um domínio oEmbed pode ser usado, passando um valor portalId na solicitação da API ao configurar o domínio oEmbed. Isso garantirá que apenas a conta da HubSpot especificada possa usar esse domínio oEmbed.

​
Criar um módulo personalizado

Para criar um módulo personalizado:
  • Acesse Marketing > Arquivos e modelos > Ferramentas de design.
  • No canto superior esquerdo, clique em Arquivo > Novo arquivo.
  • Na caixa de diálogo, clique no menu suspenso O que você gostaria de construir hoje? e selecione Módulo.
  • Clique em Próximo.
  • Marque a caixa de seleção ao lado de cada tipo de conteúdo no qual o módulo será usado: páginas, posts de blog, listas de blogs, e-mails ou orçamentos. Os módulos usados em modelos de e-mail não podem incluir CSS ou JavaScript.
  • Selecione se esse módulo será um **módulo local **ou um módulo global. Se você criar ummódulo global, a edição do conteúdo desse módulo atualizará cada local onde o módulo é usado.
  • Insira um nome de arquivo para seu módulo e clique em Criar.
  • Na seção Campos à direita, clique no menu suspenso Adicionar campo e selecione Incorporar.
  • Na seção Tipos de fonte compatíveis, selecione Integração de mídia.
  • Na seção Incorporar conteúdo padrão, clique em Selecionar do [aplicativo de media bridge].
  • No painel direito, selecione a mídia que você deseja incorporar ao módulo.
  • Defina qualquer uma das opções do editor, condições de exibição e opções do repetidor do campo.
  • Sob Nome da variável HubL, clique Cópiar > Copiar trecho.
  • Cole o snippet na seção module.html.
  • Para visualizar como o módulo será exibido na sua página, clique em Visualizar.
  • Na seção esquerda, clique em Selecione entre [aplicativo Media Bridge], então selecione a mídia que você deseja visualizar.

​
Enviar eventos de mídia

Um evento de mídia é um evento que acontece em relação a um objeto de mídia, como um evento de reprodução. Uma vez enviado um evento de mídia para o aplicativo de media bridge, ele poderá ser usado nos relatórios e nos cartões de linha do tempo do CRM. Há três tipos de eventos de mídia:
  • Evento Reproduzido: representa quando um usuário começou a reproduzir uma peça de mídia. Este evento está disponível na linha do tempo de contato e na ferramenta de relatórios.
  • Evento Quartil: representa quando um usuário atingiu marcos do quartil (0%, 25%, 50%, 75%, 100%) na peça de mídia que está visualizando. Este evento está apenas disponível na linha do tempo de contato.
  • Evento Atenção: representa quando um usuário consumiu totalmente uma peça de mídia ou quando o usuário concluiu sua sessão. Este evento está apenas disponível na ferramenta de relatórios.
Os eventos podem ser enviados fazendo uma solicitação POST para /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent e /media-bridge/v2/events/attention-span respectively. Para que os eventos de mídia sejam exibidos na linha do tempo de contato do usuário no HubSpot, um evento Reproduzido deve ser enviado ao aplicativo de media bridge para cada sessão. Os eventos de uma única sessão serão mostrados em um cartão na linha do tempo de atividades do contato. Quando os eventos são enviados usando os pontos de extremidade de evento v2, eles são processados de forma assíncrona, ao contrário dos enviados por meio dos pontos de extremidade v1. Portanto, recomendamos o seguinte:
  • A versão v1 dos pontos de extremidade deve ser usada para qualquer teste, pois uma solicitação incorreta ocasionará em erro imediatamente.
  • A versão v2 dos pontos de extremidade deve ser usada na produção, pois sua natureza assíncrona ajudará a evitar atrasos no cliente enquanto o evento estiver sendo gravado na media bridge. Os eventos também são retidos e repetidos em caso de falha temporária no servidor de media bridge.

​
Conectar um evento a um registro de contato

Para conectar um evento de mídia a um registro de contato, você deve fornecer um contactId ou um contactUtk. Se apenas um contactUtk for fornecido, ele será convertido em um contactId. Se ambos forem fornecidos na solicitação, contactId será usado como fonte da verdade. Este parâmetro permite que o aplicativo de media bridge crie uma associação entre o registro do contato e o evento. Depois de conectar um evento de mídia a um registro de contato, o evento poderá ser usado nos relatórios entre objetos. Assim, os clientes poderão vincular seus eventos de mídia a registros de contato, bem como a empresas e negócios associados.

​
Conexão de um evento a uma peça de mídia

Para associar um evento de mídia a uma peça de mídia, os parâmetros mediaID ou externalID devem ser incluídos na solicitação. Se ambos forem fornecidos, mediaID será usado como fonte da verdade.

​
Observação:

A HubSpot só oferece suporte às associações de Eventos disputados e Eventos de quartil com um pedaço de mídia.

​
Conectar um evento a uma página

Para associar um evento de mídia a uma página do HubSpot, os seguintes parâmetros devem ser incluídos na solicitação:
  • Se a página estiver hospedada no HubSpot CMS, pageId deverá ser fornecido.
  • Se a página não estiver hospedada no HubSpot CMS, pageName e pageUrl deverão ser incluídos.
A tabela abaixo descreve as propriedades permitidas para os três eventos de mídia:
Última modificação em 11 de maio de 2026