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.
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.
Para definir um objeto de mídia, faça uma solicitação POST
para /media-bridge/v1/{appId}/settings/object-definitions
. Você usará o parâmetro mediaTypes para definir o objeto: 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}
.
Todas as chamadas de API feitas incluirão seu ID de conta de desenvolvedor como o parâmetro de consulta portalID.
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 no portal 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 de instalar o aplicativo de media bridge no portal de um cliente, você pode:
- Criar objetos de mídia
- Crie módulos CMS para incorporar seus objetos de mídia
- Enviar eventos 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ídia VIDEO e AUDIO, as tabelas abaixo listam todas as propriedades padrão e obrigatórias (* indica obrigatoriedade):
Parâmetro | Tipo | Descrição |
---|---|---|
id | Número | Um ID usado para identificar a peça específica de mídia no sistema de media bridge 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 | O ID da mídia no sistema de terceiro. Isso permite que os integradores busquem a 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 padrão e obrigatórias (* indica obrigatoriedade):
Parâmetro | Tipo | Descrição |
---|---|---|
id | Número | Um ID usado para identificar a peça específica de mídia no sistema de media bridge 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 | O ID da mídia no sistema de terceiro. Isso permite que os integradores busquem a 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. |
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, id e media_type da 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 crm_objects do HubL com um objeto de mídia, em que 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.
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.
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.
-
Em Nome da variável do HubL, clique em **Copiar **> Copiar snippet.
-
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 Selecionar do [aplicativo de media bridge] e selecione a mídia que você deseja visualizar.
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.
-
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.
-
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.
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.
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.
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.
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
epageUrl
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 a qual este evento está relacionado. |
externalId | String | O ID da mídia no sistema de terceiro. 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 aconteceu. |
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. |
attentionSpanMapString / attentionSpanMap | 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. Exemplo: considere um vídeo de 10 segundos em que cada segundo é um intervalo. Se um visitante assistir aos primeiros 5 segundos do vídeo e, em seguida, reiniciar o vídeo e assistir novamente aos primeiros 2 segundos, o attentionSpanMapString resultante 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. O media bridge 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. |