API do CMS | Media Bridge

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 objetos de mídia
• Crie módulos CMS para incorporar seus objetos de mídia
• Enviar eventos de mídia

​

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.

Parâmetro	Tipo	Descrição
id	Número	Um ID usado para identificar a parte específica da mídia no sistema de ponte de mídia da HubSpot. Isso é gerado automaticamente pela HubSpot e não pode ser definido pelos desenvolvedores.
hs_duration	Número	A duração da mídia em milissegundos.
hs_oembed_url*	String	Um URL que deve retornar uma resposta oEmbed válida que segue a especificação oEmbed. Requer tipo video ou rich com um iframe em html.
hs_file_url	String	A URL do arquivo de mídia bruto. Futuramente, isso pode ser usado para ajudar a oferecer suporte à incorporação social.
hs_thumbnail_url	String	O URL de uma imagem usada como miniatura para incorporar a mídia ao conteúdo. O tamanho ideal para essa miniatura é de 640x480 pixels.
hs_poster_url	String	URL de uma imagem que representa a mídia. Essa imagem deve ter as mesmas dimensões da mídia original e pode ser usada em locais em que um espaço reservado para a imagem é necessário (por exemplo, quando a mídia é inserida em um e-mail).
hs_external_id	String	A ID da mídia no sistema de terceiros. Isso dá aos integradores a capacidade de buscar mídia do Media Bridge com base no mesmo ID que eles usam em seu próprio sistema. (Este é o ponto de extremidade de API que aproveita esse mapeamento)
hs_folder_path	String	Um caminho fornecido pelo provedor para o objeto, destinado a representar a localização do objeto no sistema de pastas do terceiro (se houver). A HubSpot tentará representar essa estrutura de diretório ao exibir esses objetos para o usuário, mas pode aninhar os objetos e pastas de cada provedor em uma pasta de nível superior com o nome do provedor.
hs_title*	String	O nome da mídia. Isso será mostrado na interface do usuário da HubSpot em locais como o seletor de mídia.
hs_details_page_link	String	Um URL que permite que um usuário visualize ou interaja com a mídia no sistema do provedor de mídia. Isso é usado na interface de usuário da HubSpot para que os usuários possam identificar a mídia sem depender apenas do título.

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

Campos marcados com * são obrigatórios.

Parâmetro	Tipo	Descrição
id	Número	Um ID usado para identificar a parte específica da mídia no sistema de ponte de mídia da HubSpot. Isso é gerado automaticamente pela HubSpot e não pode ser definido pelos desenvolvedores.
hs_oembed_url*	String	Um URL que deve retornar uma resposta oEmbed válida que segue a especificação oEmbed. Requer tipo video ou rich com um iframe em html.
hs_file_url*	String	A URL do arquivo de mídia bruto. Futuramente, isso pode ser usado para ajudar a oferecer suporte à incorporação social.
hs_thumbnail_url	String	URL para uma imagem que será usada como a miniatura para incorporar a mídia ao conteúdo em lugares como o seletor de mídia. O tamanho ideal para essa miniatura é de 640x480 pixels.
hs_poster_url	String	URL de uma imagem que representa a mídia. Essa imagem deve ter as mesmas dimensões da mídia original e pode ser usada em locais em que um espaço reservado para a imagem é necessário (por exemplo, quando a mídia é inserida em um e-mail).
hs_external_id	String	A ID da mídia no sistema de terceiros. Isso dá aos integradores a capacidade de buscar mídia do Media Bridge com base no mesmo ID que eles usam em seu próprio sistema. (Este é o ponto de extremidade de API que aproveita esse mapeamento)
hs_folder_path	String	Um caminho fornecido pelo provedor para o objeto, destinado a representar a localização do objeto no sistema de pastas do terceiro (se houver). A HubSpot tentará representar essa estrutura de diretório ao exibir esses objetos para o usuário, mas pode aninhar os objetos e pastas de cada provedor em uma pasta de nível superior com o nome do provedor.
hs_title*	String	O nome da mídia. Isso será mostrado na interface do usuário da HubSpot em locais como o seletor de mídia.
hs_details_page_link	String	Um URL que permite que um usuário visualize ou interaja com a mídia no sistema do provedor de mídia. Isso é usado na interface de usuário da HubSpot para que os usuários possam identificar a mídia sem depender apenas do título.

​

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.

​

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:

Propriedade	Tipo de evento	Descrição
mediaBridgeObjectId	Todos os eventos	O ID da mídia à qual este evento está relacionado.
externalId	String	A ID da mídia no sistema de terceiros. Isso permite que os desenvolvedores se refiram à mídia no media bridge com base no mesmo ID que eles usam em seu próprio sistema. Isso pode ser usado em vez do mediaBridgeObjectId em eventos. Se um externalId e um mediaBridgeObjectId forem fornecidos, o mediaBridgeObjectId será usado e o externalId será ignorado.
sessionId	Todos os eventos	Um identificador exclusivo para representar uma sessão de visualização. Isso pode significar coisas diferentes para diferentes provedores, e a HubSpot está permitindo que os provedores decidam o que uma sessão significa para eles. Isso será usado para agrupar eventos que aconteceram na mesma sessão. Espera-se que isso seja gerado pelo sistema do terceiro.
contactId	Todos os eventos	ID do contato no sistema da HubSpot que consumiu a mídia. Isso pode ser obtido usando a API Obter contato por token de usuário (utk) da HubSpot. A API também pode fornecer um token de usuário e fará a conversão dele em um ID de contato automaticamente.
contactUtk	Todos os eventos	O token de usuário (utk) que identifica qual contato consumiu a mídia.
pageId	Todos os eventos	O ID de conteúdo da página em que um evento ocorreu.
pageName	Todos os eventos	O nome ou o título da página em que um evento aconteceu.
pageUrl	Todos os eventos	A URL da página na qual um evento aconteceu.
occurredTimestamp	Todos os eventos	A marca de data/hora em que esse evento ocorreu, em milissegundos desde a época.
rawDataString / rawDataMap	Intervalo de atenção	Estes são os dados brutos que fornecem os dados mais granulares sobre os intervalos da mídia e quantas vezes cada intervalo foi consumido pelo usuário. Por exemplo, para um vídeo de 10 segundos em que cada segundo é um intervalo, se um visitante assistir aos primeiros 5 segundos do vídeo, reiniciar o vídeo e assistir aos primeiros 2 segundos novamente, o resultado será rawDataString seria “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”.
totalPercentPlayed	Intervalo de atenção	A porcentagem da mídia que o usuário consumiu. Os provedores podem calcular isso de forma diferente dependendo de como consideram visualizações repetidas da mesma porção de mídia. Por esse motivo, a API não tentará validar o totalPercentWatched em relação às informações de intervalo de atenção para o evento. Se estiver faltando, a HubSpot calculará isso por meio do mapa de intervalo de atenção da seguinte forma: (número de intervalos com um valor de 1 ou mais)/(número total de intervalos).
totalSecondsPlayed	Intervalo de atenção	Os segundos que um usuário ficou consumindo a mídia. A ponte de mídia calcula isso como totalPercentPlayed*mediaDuration. Se um provedor quiser que isso seja calculado de forma diferente, ele pode fornecer o valor pré-calculado quando criar o evento
playedPercent	Evento de quartil	Um valor percentual de quartil (0, 25, 50, 75, 100) para a quantidade de mídia consumida até o momento.
iframeUrl	Evento reproduzido	O URL que pode ser usado para exibir dados de um sistema externo usando um iFrame. Quando presente, o evento na linha do tempo do contato exibirá um link que, quando clicado, abrirá uma janela modal com o conteúdo do iFrame.
mediaType	String	O tipo de mídia ao qual o evento pertence (por exemplo, VÍDEO ou ÁUDIO) Isso nos permite atribuir corretamente o evento aos objetos corretos quando um único provedor tem suporte a vários tipos de mídia.