API du CMS | Media Bridge

L’API de passerelle multimédia permet aux intégrateurs de transférer des objets multimédia tels que des fichiers vidéo et audio ainsi que des données de consommation multimédia dans HubSpot. Elle crée également les fonctionnalités suivantes dans le compte HubSpot de l’utilisateur :

• Modules pour intégrer des objets multimédia dans les éditeurs de glisser-déposer de HubSpot pour les pages et les e-mails.
• Événements de chronologie CRM indiquant quand les prospects ou les clients ont interagi avec du contenu vidéo, audio et d’autres types de contenu multimédia.
• Listes segmentées pour des expériences ciblées et personnalisées.
• Workflows pour automatiser les interactions, en fonction des événements de consultation de contenu multimédia.
• Rapports pour mesurer l’impact des ressources multimédia.

La passerelle multimédia utilise à la fois des objets personnalisés et des événements unifiés, le système de suivi des événements de HubSpot. Cela signifie que vous pouvez utiliser à la fois l’API de passerelle multimédia et l’API d’objets personnalisés pour créer votre intégration.

​

Utiliser l’API de passerelle multimédia

Vous avez besoin d’un compte de développeur HubSpot pour enregistrer votre application de passerelle multimédia et configurer vos définitions d’objets multimédia initiales avant de connecter votre application au compte d’un utilisateur HubSpot.

​

Créer et personnaliser vos définitions d’objet multimédia

Pour définir un objet multimédia, effectuez une requête POST à /media-bridge/v1/{appId}/settings/object-definitions. Dans le corps de la requête, incluez l’une des valeurs de type de média suivantes dans le tableau mediaTypes : VIDEO, AUDIO, DOCUMENT, IMAGE, ou OTHER. Après avoir défini vos objets multimédia, créez et modifiez les propriétés de l’objet multimédia en effectuant une requête PATCH à /media-bridge/v1/{appId}/schemas/{objectType} et une requête POST à /media-bridge/v1/{appId}/properties/{objectType}.

​

Connecter votre application de passerelle multimédia au compte d’un utilisateur HubSpot

Pour connecter votre application de passerelle multimédia au compte d’un utilisateur HubSpot, vous devez créer une définition d’application dans le compte de votre développeur HubSpot. Les définitions d’application incluent :

• Des détails tels que le logo et le texte à afficher à l’utilisateur HubSpot lorsque votre intégration tentera de créer une connexion initiale à son compte ;
• Les périmètres dont votre intégration a besoin dans le compte HubSpot de l’utilisateur.

Pour connecter votre application de passerelle multimédia à un compte utilisateur HubSpot :

• Créez une définition d’application dans votre compte de développeur pour l’application de passerelle multimédia.
• Incluez les périmètres suivants lors de la définition de votre application :
  • media_bridge.read
  • media_bridge.write
• Utilisez l’authentification OAuth lors de l’authentification des appels effectués par votre application. Découvrez-en davantage sur les méthodes d’authentification.

Pour vérifier que l’application est correctement installée sur le portail HubSpot d’un client :

• Visitez https://app.hubspot.com/media-bridge-demo/{HubID}, en remplaçant {HubID} par l’ID de compte.
• Dans l’angle supérieur droit, cliquez sur le menu déroulant Application et sélectionnez votre application de passerelle multimédia.
• Dans l’application, vous pouvez afficher les types de fichiers multimédia pris en charge par l’application et créer des exemples.

Une fois que l’application de passerelle multimédia a été installée sur le portail HubSpot d’un client, vous pouvez :

• Créer des objets multimédia
• Créer des modules CMS pour l’intégration de vos objets multimédia
• Envoyer des événements multimédia

​

Créer vos objets multimédia

Après avoir créé vos définitions d’objet multimédia et installé votre application de passerelle multimédia dans le compte d’un utilisateur, vous pouvez utiliser le jeton OAuth pour créer et modifier des objets multimédia dans le compte. Étant donné que les objets multimédia sont des objets personnalisés, utilisez les points de terminaison d’API d’objets personnalisés pour les créer :

• Effectuez une requête GET à /media-bridge/v1/{appId}/settings/object-definitions/{mediaType} pour trouver le objectType.
• Effectuez une requête POST à /crm/v3/objects/{objectType} pour créer l’objet multimédia dans le compte de l’utilisateur.

Un objet multimédia représente un élément de contenu pouvant être intégré dans un système tiers. Une fois qu’un objet multimédia est ajouté à la passerelle multimédia, il peut être intégré dans le contenu CMS de HubSpot et associé aux événements multimédia. Pour les objets multimédia VIDEO et AUDIO, les tableaux ci-dessous répertorient toutes les propriétés disponibles :

Les champs marqués par sont * obligatoires.

Paramètre	Type	Description
id	Nombre	Un ID utilisé pour identifier l’élément multimédia spécifique dans le système de passerelle multimédia de HubSpot. Cette propriété est générée automatiquement par HubSpot et ne peut pas être définie par les développeurs.
hs_duration	Nombre	Une durée du contenu multimédia en millisecondes.
hs_oembed_url*	Chaîne	Une URL qui doit renvoyer une réponse oEmbed valide respectant la spécification oEmbed. Nécessite un type video ou rich avec un iFrame en html.
hs_file_url	Chaîne	L’URL du fichier multimédia brut. Elle pourra être utilisée à l’avenir à des fins d’intégration sur les réseaux sociaux.
hs_thumbnail_url	Chaîne	L’URL d’une image utilisée comme vignette pour l’intégration de l’élément multimédia dans le contenu La taille idéale pour cette miniature est de 640 x 480 pixels.
hs_poster_url	Chaîne	L’URL d’une image représentant le contenu multimédia. Cette image doit avoir les mêmes dimensions que le média original et peut être utilisée aux endroits où une variable d’image est requise (par exemple quand le média est inséré dans un e-mail).
hs_external_id	Chaîne	L’ID du contenu multimédia dans le système du tiers. Il permet aux intégrateurs de récupérer du contenu multimédia à partir de la passerelle multimédia selon le même ID utilisé dans leur propre système. (Il s’agit du point de terminaison d’API qui exploite ce mappage.)
hs_folder_path	Chaîne	Un chemin d’accès vers l’objet fourni par le fournisseur, désignant l’emplacement de l’objet dans le système de dossiers du tiers (le cas échéant). HubSpot tentera de représenter cette structure de répertoire lors de l’affichage de ces objets à l’utilisateur, mais pourra imbriquer les objets et dossiers de chaque fournisseur dans un dossier de premier niveau nommé en fonction du fournisseur.
hs_title*	Chaîne	Le nom du contenu multimédia. Il sera affiché dans l’interface utilisateur HubSpot dans des endroits tels que le sélecteur de contenu multimédia.
hs_details_page_link	Chaîne	L’URL qui permet à un utilisateur de visualiser ou d’interagir avec le contenu multimédia dans le système du fournisseur de contenu multimédia. Elle est utilisée dans l’interface utilisateur HubSpot pour permettre aux utilisateurs d’identifier le contenu multimédia sans se baser uniquement sur son titre.

Pour les objets multimédia IMAGE, les tableaux ci-dessous répertorient toutes les propriétés disponibles :

Les champs marqués par sont * obligatoires.

Paramètre	Type	Description
id	Nombre	Un ID utilisé pour identifier l’élément multimédia spécifique dans le système de passerelle multimédia de HubSpot. Cette propriété est générée automatiquement par HubSpot et ne peut pas être définie par les développeurs.
hs_oembed_url*	Chaîne	Une URL qui doit renvoyer une réponse oEmbed valide respectant la spécification oEmbed. Nécessite un type video ou rich avec un iFrame en html.
hs_file_url*	Chaîne	L’URL du fichier multimédia brut. Elle pourra être utilisée à l’avenir à des fins d’intégration sur les réseaux sociaux.
hs_thumbnail_url	Chaîne	L’URL d’une image qui sera utilisée comme vignette pour l’intégration du contenu multimédia dans des endroits tels que le sélecteur de contenu multimédia. La taille idéale pour cette miniature est de 640 x 480 pixels.
hs_poster_url	Chaîne	L’URL d’une image représentant le contenu multimédia. Cette image doit avoir les mêmes dimensions que le média original et peut être utilisée aux endroits où une variable d’image est requise (par exemple quand le média est inséré dans un e-mail).
hs_external_id	Chaîne	L’ID du contenu multimédia dans le système du tiers. Il permet aux intégrateurs de récupérer du contenu multimédia à partir de la passerelle multimédia selon le même ID utilisé dans leur propre système. (Il s’agit du point de terminaison d’API qui exploite ce mappage.)
hs_folder_path	Chaîne	Un chemin d’accès vers l’objet fourni par le fournisseur, désignant l’emplacement de l’objet dans le système de dossiers du tiers (le cas échéant). HubSpot tentera de représenter cette structure de répertoire lors de l’affichage de ces objets à l’utilisateur, mais pourra imbriquer les objets et dossiers de chaque fournisseur dans un dossier de premier niveau nommé en fonction du fournisseur.
hs_title*	Chaîne	Le nom du contenu multimédia. Il sera affiché dans l’interface utilisateur HubSpot dans des endroits tels que le sélecteur de contenu multimédia.
hs_details_page_link	Chaîne	Une URL qui permet à un utilisateur de visualiser ou d’interagir avec le contenu multimédia dans le système du fournisseur de contenu multimédia. Elle est utilisée dans l’interface utilisateur HubSpot pour permettre aux utilisateurs d’identifier le contenu multimédia sans se baser uniquement sur son titre.

​

Créer des modules de CMS pour intégrer du contenu multimédia

Chaque fournisseur d’applications de passerelle multimédia est responsable de la création de son propre module pour rendre son contenu multimédia dans CMS Hub. Lorsqu’une application de passerelle multimédia est installée dans un compte HubSpot, le champ d’intégration du module présente le type de source supplémentaire Intégration de média. Cela permet à l’utilisateur de sélectionner du contenu multimédia à partir de l’application installée pour l’intégrer sur sa page de site web. Une fois que l’utilisateur a sélectionné un élément multimédia à intégrer, les éléments oembed_url et oembed_response du contenu multimédia sont disponibles dans le HubL pour restituer facilement les lecteurs. De plus, les éléments id et media_type du contenu multimédia sélectionné sont stockés pour permettre l’interrogation de l’objet CRM sous-jacent via la fonction HubL crm_objects. Cela peut être utilisé pour récupérer une ou toutes les propriétés qui font partie d’un objet multimédia. Exemple d’utilisation de la fonction HubL crm_objects avec un objet multimédia dont les identifiants sont 459 et 922 : {% set objects = crm_objects("a123_Videos", [459,922]) %} {{ objects }} Pour récupérer une image spécifique avec le même objet : {% set object = crm_object("a123_Images", 459) %} {{ object }} Les applications peuvent récupérer le type d’objet (« a123_Videos » dans l’exemple) en effectuant une requête GET à /media-bridge/{appId}/settings/object-definitions/{mediaType}. Les développeurs doivent utiliser les points de terminaison de l’API de code source du CMS pour insérer leur code de module personnalisé dans les comptes des clients une fois que ceux-ci se sont connectés via oAuth. Une fois que le code du module est inséré dans le compte du client, il pourra automatiquement commencer à utiliser le module du développeur dans son contenu.

​

Configurer un domaine oEmbed

Pour utiliser la fonction HubL oEmbed, le domaine utilisé pour récupérer la réponse oEmbed doit être enregistré en effectuant une requête à /media-bridge/v1/{appId}/settings/oembed-domains. Les paramètres suivants doivent être inclus :

• Schéma : la structure d’URL pour les URL de contenu multimédia. Cette structure d’URL est utilisée pour faire associer l’URL transmise dans la fonction HubL oEmbed à votre API oEmbed. Les caractères génériques sont pris en charge avec * (par exemple : www.domain.com/*).
• URL : l’URL de votre API oEmbed. L du contenu multimédia est transmise à cette URL via un paramètre URL.
• Découverte (booléen) : détermine si votre API oEmbed prend en charge la fonctionnalité Découverte de oEmbed.

Par défaut, les domaines oEmbed enregistrés seront mis à disposition de tous les clients ayant installé votre application. Si vous disposez de domaines personnalisés propres à chaque client, vous pouvez spécifier dans quel compte un domaine oEmbed doit être autorisé à être utilisé en transmettant une valeur portalId dans la requête d’API lors de la configuration du domaine oEmbed. Cela garantira que seul le compte HubSpot spécifié peut utiliser ce domaine oEmbed.

​

Créer un module personnalisé

Pour créer un module personnalisé :

• Accédez à Marketing > Fichiers et modèles > Outils de conception.
• Dans l’angle supérieur gauche, cliquez sur Fichier > Nouveau fichier.
• Dans la boîte de dialogue, cliquez sur le menu déroulant Que souhaiteriez-vous créer aujourd’hui ? et sélectionnez Module.
• Cliquez sur Suivant.
• Sélectionnez la case à cocher à côté de chaque type de contenu où votre module sera utilisé : pages, articles de blog, listings de blog, e-mails ou devis. Les modules utilisés dans les modèles d’e-mails ne peuvent pas inclure de code CSS ou JavaScript.
• Indiquez si ce module sera un module local ou un module global. Si vous créez un module global, la modification du contenu de ce module actualisera chaque emplacement où le module est utilisé.
• Saisissez un nom de fichier pour votre module, puis cliquez sur Créer.
• Dans la section Champs à droite, cliquez sur le menu déroulant Ajouter un champ et sélectionnez Intégrer.

• Dans la section Types de sources pris en charge, sélectionnez Intégration de média.
• Dans la section Contenu intégré par défaut, cliquez sur Sélectionner à partir de [application de passerelle multimédia].
• Dans le panneau de droite, sélectionnez le contenu multimédia que vous souhaitez intégrer dans le module.
• Définissez les options d’éditeur, conditions d’affichage du champ et options de répéteur de champ.
• Dans Nom de variable HubL, cliquez sur Copier > Copier le bloc de texte.
• Collez le bloc de texte dans la section module.html.
• Pour prévisualiser l’apparence du module sur votre page, cliquez sur Aperçu.
• Dans la section de gauche, cliquez sur Sélectionner à partir de [application de passerelle multimédia], puis sélectionnez le contenu multimédia que vous souhaitez prévisualiser.

​

Envoyer vos événements multimédia

Un événement média est un événement qui se produit par rapport à un objet multimédia, comme un événement de lecture. Une fois qu’un événement multimédia est envoyé à l’application de passerelle multimédia, il peut être utilisé dans les rapports et dans les cartes CRM de chronologie. Il existe trois types d’événement multimédia :

• Événement Lu : indique lorsqu’un utilisateur a commencé à lire un contenu multimédia. Cet événement est disponible à la fois sur la chronologie du contact et dans l’outil Rapports.
• Événement Quartile : indique lorsqu’un utilisateur a atteint des étapes (0 %, 25 %, 50 %, 75 %, 100 %) concernant le volume de contenu multimédia consulté. Cet événement est uniquement disponible sur la chronologie du contact.
• Événement Niveau d’attention : indique lorsqu’un utilisateur a entièrement consulté un contenu multimédia ou une fois qu’il a terminé sa session. Cet événement est uniquement disponible dans l’outil Rapports.

Les événements peuvent être envoyés en effectuant une requête POST à /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent et /media-bridge/v2/events/attention-span respectively. Pour que les événements multimédia soient affichés sur la chronologie de contact de l’utilisateur dans HubSpot, un événement lu doit être envoyé à l’application de passerelle multimédia pour chaque session. Les événements d’une seule session seront affichés dans une carte sur la chronologie d’activité du contact. Lorsque les événements sont envoyés à l’aide des points de terminaison d’événements v2, ils sont traités de manière asynchrone, contrairement à ceux envoyés via les points de terminaison v1. À ce titre, nous recommandons ce qui suit :

• La version v1 des points de terminaison doit être utilisée pour n’importe quel test car une requête erronée sera immédiatement supprimée.
• La version v2 des points de terminaison doit être utilisée en production car sa nature asynchrone permettra d’éviter les retards dans l’environnement client pendant que l’événement est rédigé sur la passerelle multimédia. Les événements sont également conservés et retentés en cas de défaillance temporaire du serveur de la passerelle multimédia.

​

Connecter un événement à une fiche d’informations de contact

Pour connecter un événement multimédia à une fiche d’informations de contact, les intégrateurs doivent fournir le contactId ou un contactUtk. Si seul un élément contactUtk est fourni, il sera converti en contactId. Si les deux sont fournis dans la requête, le contactId sera utilisé comme le centre unique d’informations. Ce paramètre permet à l’application de passerelle multimédia de créer une association entre la fiche d’informations de contact et l’événement. Une fois l’évènement multimédia connecté à la fiche d’informations de contact, il peut être utilisé dans des rapports d’objets croisés. Ainsi, les clients pourront associer leurs événements multimédia à des fiches d’informations de contact ainsi qu’à des entreprises et transactions associées.

​

Connexion d’un événement à un contenu média

Pour associer un événement multimédia à un contenu multimédia, les paramètres mediaID ou externalID doivent être inclus dans la requête. Si les deux sont fournis, le mediaID sera utilisé comme le centre unique d’informations.

​

Connecter un événement à une page

Pour associer un évènement multimédia à une page HubSpot, les paramètres suivants doivent être inclus dans la requête :

• Si la page est hébergée sur CMS Hub, le pageId doit être fourni.
• Si la page n’est pas hébergée sur CMS Hub, le pageName et le pageUrl doivent être inclus.

Le tableau ci-dessous présente les propriétés prises en charge pour les trois événements multimédia :

Propriété	Type d’événement	Description
mediaBridgeObjectId	Tous les événements	L’ID du contenu multimédia auquel cet événement est relié.
externalId	Chaîne	L’ID du contenu multimédia dans le système du tiers. Il permet aux développeurs de mentionner le contenu multimédia dans la passerelle multimédia selon le même ID utilisé dans leur propre système Il peut être utilisé à la place de mediaBridgeObjectId dans les événements. Si un externalId et un mediaBridgeObjectId sont fournis, le mediaBridgeObjectId sera utilisé et le externalId sera ignoré.
sessionId	Tous les événements	Un identifiant unique pour désigner une session de visualisation. Cela peut signifier différentes choses pour différents fournisseurs. HubSpot laisse les fournisseurs décider de ce qu’une session signifie pour eux. Il sera utilisé pour regrouper des événements qui se sont déroulés dans la même session. L’identifiant devrait être généré par le système du tiers.
contactId	Tous les événements	L’identifiant du contact dans le système de HubSpot qui a consulté le contenu multimédia. Cela peut être récupéré à l’aide de l’API Get contact by usertoken (utk) de HubSpot. L’API prend également en charge la fourniture d’un jeton d’utilisateur et gérera la conversion automatique de celui-ci en ID de contact.
contactUtk	Tous les événements	Le jeton d’utilisateur (utk) qui identifie quel contact a consulté le contenu multimédia.
pageId	Tous les événements	L’ID de contenu de la page sur laquelle un événement s’est produit.
pageName	Tous les événements	Le nom ou le titre de la page sur laquelle un événement s’est produit.
pageUrl	Tous les événements	LURL de la page sur laquelle un événement s’est produit.
occurredTimestamp	Tous les événements	L’horodatage auquel cet événement s’est produit (en millisecondes epoch).
rawDataString / rawDataMap	Niveau d’attention	Ce sont les données brutes qui fournissent les données les plus granulaires sur les niveaux du contenu multimédia ainsi que sur le nombre de consultations de chaque niveau par l’utilisateur. Par exemple, pour une vidéo de 10 secondes où chaque seconde est un niveau, si un visiteur regarde les 5 premières secondes de la vidéo, puis redémarre la vidéo et regarde les 2 premières secondes à nouveau, l’élément rawDataString résultant sera “0=2;1=2;2=1;3=1;4=1;5=0;6=0;7=0;8=0;9=0;”.
totalPercentPlayed	Niveau d’attention	Le pourcentage du contenu multimédia consulté par l’utilisateur. Les fournisseurs peuvent calculer cela différemment en fonction de la façon dont ils considèrent les vues répétées de la même portion du contenu multimédia. Pour cette raison, l’API ne tentera pas de valider totalPercentWatched par rapport aux informations de niveau d’attention de l’événement. S’il est manquant, HubSpot calculera cela à partir de la carte de niveau d’attention comme suit : (nombre de niveaux avec une valeur supérieure ou égale à 1)/(nombre total de niveaux).
totalSecondsPlayed	Niveau d’attention	Les secondes qu’un utilisateur a passées à consulter le contenu multimédia. La passerelle multimédia calcule cela comme suit : totalPercentPlayed*mediaDuration. Si un fournisseur souhaite que cela soit calculé différemment, il peut fournir la valeur précalculée lorsqu’il crée l’événement.
playedPercent	Événement Quartile	Une valeur de pourcentage de quartile (0, 25, 50, 75, 100) pour la quantité de contenu multimédia qui a été consultée jusqu’à présent.
iframeUrl	Événement Lu	Une URL qui peut être utilisée pour afficher des données provenant d’un système externe via un iFrame. Une fois inclus, l’événement sur la chronologie de contact affichera un lien vers une fenêtre modale qui affichera le contenu de iFrame en cliquant dessus.
mediaType	Chaîne	Le type multimédia auquel l’événement appartient (par exemple : VIDEO ou AUDIO). Cela nous permet d’assigner correctement l’événement aux bons objets lorsqu’un fournisseur prend en charge plusieurs types de contenu multimédia.