API de passerelle multimédia
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.
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.
Pour définir un objet multimédia, effectuez une demande POST à /media-bridge/v1/{appId}/settings/object-definitions. Vous utiliserez le paramètre mediaTypes pour définir l'objet : 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 demande PATCH à /media-bridge/v1/{appId}/schemas/{objectType} et une demande POST à /media-bridge/v1/{appId}/properties/{objectType}.
Tous les appels d'API effectués incluront votre ID de compte de développeur en tant que paramètre de demande portalID.
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.readmedia_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 d'un client :
- Rendez-vous sur
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 fichier 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 d'un client, vous pouvez :
Create your media objects
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 demande
GETà/media-bridge/v1/{appId}/settings/object-definitions/{mediaType}pour trouver l'élément objectType. - Effectuez une demande
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 par défaut et requises (* indique un élément obligatoire) :
| Parameter | Type | Description |
|---|---|---|
id
| Number | 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
| Number | Durée du contenu multimédia en millisecondes. |
hs_oembed_url*
| String | Une URL qui doit renvoyer une réponse oEmbed valide respectant la spécification oEmbed. Nécessite un type |
hs_file_url
| String | 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
| String | 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
| String | 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
| String | 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
| String | 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*
| String | 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
| String | 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 par défaut et requises (* indique un élément obligatoire) :
| Parameter | Type | Description |
|---|---|---|
id
| Number | 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*
| String | Une URL qui doit renvoyer une réponse oEmbed valide respectant la spécification oEmbed. Nécessite un type |
hs_file_url*
| String | 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
| String | 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
| String | 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
| String | 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
| String | 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*
| String | 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
| String | 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. |
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 demande 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.
Pour utiliser la fonction HubL oEmbed, le domaine utilisé pour récupérer la réponse oEmbed doit être enregistré en effectuant une demande à /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'URL 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 demande d'API lors de la configuration du domaine oEmbed. Cela garantira que seul le compte HubSpot spécifié peut utiliser ce domaine oEmbed.
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.
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 : désigne lorsqu'un utilisateur a commencé à lire un contenu multimédia.
- Événement Quartile : désigne lorsqu'un utilisateur a atteint des étapes (0 %, 25 %, 50 %, 75 %, 100 %) concernant le volume de contenu multimédia consulté.
- Événement Niveau d'attention : désigne lorsqu'un utilisateur a entièrement consulté un contenu multimédia ou une fois qu'il a terminé sa session.
Les événements peuvent être envoyés en effectuant une demande POST à /media-bridge/v2/events/media-played, /media-bridge/v2/events/media-played-percent et /media-bridge/v2/events/attention-span respectivement.
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 demande 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.
Pour connecter un événement multimédia à une fiche d'informations de contact, les intégrateurs doivent fournir contactId ou contactUtk. Si seul l'élément contactUtk est fourni, il sera converti en contactId. Si les deux sont fournis dans la demande, 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.
Pour associer un évènement multimédia à une page HubSpot, les paramètres suivants doivent être inclus dans la demande :
- Si la page est hébergée sur CMS Hub,
pageIddoit être fourni. - Si la page n'est pas hébergée sur CMS Hub,
pageNameetpageUrldoivent ê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
| All Events | L'ID du contenu multimédia auquel cet événement est relié. |
externalId
| String | 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 |
sessionId
| All Events | 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
| All Events | 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
| All Events | Le jeton d'utilisateur (utk) qui identifie quel contact a consulté le contenu multimédia. |
pageId
| All Events | L'ID de contenu de la page sur laquelle un événement s'est produit. |
pageName
| All Events | Le nom ou le titre de la page sur laquelle un événement s'est produit. |
pageUrl
| All Events | L'URL de la page sur laquelle un événement s'est produit. |
occurredTimestamp
| All Events | L'horodatage auquel cet événement s'est produit (en millisecondes epoch). |
attentionSpanMapString/attentionSpanMap
| Attention Span | 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. Exemple : supposons 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 |
totalPercentPlayed
| Attention Span | 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
| Attention Span | Les secondes qu'un utilisateur a passées à consulter le contenu multimédia. La passerelle multimédia calcule cela comme suit : |
playPercent
| Quartile Event | 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
| Played Event | 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 l'iFrame. |
mediaType
| String | 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. |
Merci d'avoir partagé votre avis.