API de 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. 

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: VÍDEO, ÁUDIO, DOCUMENTO, IMAGEM ou OUTRO. 

Depois de definir seus objetos de mídia, crie e modifique as propriedades dele 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:

• Visite 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 endpoints 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 os objetos de mídia VÍDEO e ÁUDIO, as tabelas abaixo listam todas as propriedades padrão e obrigatórias (* indica obrigatoriedade): 

Para objetos de mídia IMAGEM, as tabelas abaixo listam todas as propriedades padrão e obrigatórias (* indica obrigatoriedade): 

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 endpoints 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 a URL passada para a função oEmbed do HubL à API oEmbed. Valores curingas podem ser usados com * (por exemplo www.domain.com/*).

• URL: a 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 do 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 respectivamente. 

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 endpoints de evento v2, eles são processados de forma assíncrona, ao contrário dos enviados por meio dos endpoints v1. Portanto, recomendamos o seguinte:

• A versão v1 dos endpoints deve ser usada para qualquer teste, pois uma solicitação incorreta ocasionará em erro imediatamente.
• A versão v2 dos endpoints 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 e pageUrl deverão ser incluídos.

A tabela abaixo descreve as propriedades permitidas para os três eventos de mídia: