Selon leur site Web, SoundCloud est “la première plate-forme sociale de son au monde où n’importe qui peut créer des sons et les partager partout”. Pour les artistes, c’est un canal de distribution d’aperçus de leurs morceaux, et pour des gens comme moi, c’est une bonne façon de bricoler l’API. A chacun son goût, j’imagine !
J’ai vu un certain nombre de demandes dans la communauté Google+ Google Tag Manager concernant une intégration SoundCloud, j’ai donc décidé de l’examiner pour voir si je pouvais en créer une.
SoundCloud a quelque chose appelé l’API Widget, qui écoute window.postMessage appels depuis les iframes SoundCloud intégrées. L’avantage de cela par rapport, par exemple, à l’API YouTube est que vous n’avez rien à faire à l’iframe lui-même pour que cela fonctionne. Tout ce que vous avez à faire est de charger l’API Widget, puis d’indiquer quelle(s) iframe(s) vous souhaitez écouter pour les interactions.
La mise en place
Pour que cela fonctionne, vous aurez besoin des éléments suivants :
-
Balise HTML personnalisée qui charge l’API Widget, ajoute les écouteurs et fait le
dataLayer.push()appels -
Déclencheur d’événement personnalisé qui déclenche votre Tag lorsqu’un événement SoundCloud est enregistré
-
Variables de la couche de données pour la catégorie d’événement, l’action d’événement et l’étiquette d’événement
-
Balise d’événement qui se déclenche lorsque le déclencheur est activé et envoie l’appel d’événement à Google Analytics
Le composant le plus complexe est la balise HTML personnalisée, alors commençons par là.
La balise HTML personnalisée
Voici le code Tag complet. Copiez-le et collez-le dans une nouvelle balise HTML personnalisée :
<!-- Load the SoundCloud API synchronously --> <script src="https://w.soundcloud.com/player/api.js"></script> <!-- Initiate the API integration --> <script> (function() { try { // initWidget is called when a SoundCloud iframe is found on the page var initWidget = function(w) { var currentSound, act, pos, q1, q2, q3, go, lab; var cat = 'SoundCloud'; var widget = SC.Widget(w); // Events.READY is dispatched when the widget has been loaded widget.bind(SC.Widget.Events.READY, function() { // Get the title of the currently playing sound widget.getCurrentSound(function(cs) { lab = cs['title']; }); // Fire a dataLayer event when Events.PLAY is dispatched widget.bind(SC.Widget.Events.PLAY, function() { act = 'Play'; sendDl(cat, act, lab); }); // Fire a dataLayer event when Events.PAUSE is dispatched // The only exception is when the sound ends, and the auto-pause is not reported widget.bind(SC.Widget.Events.PAUSE, function(obj) { pos = Math.round(obj['relativePosition'] * 100); if (pos !== 100) { act = 'Pause'; sendDl(cat, act, lab); } }); // As the play progresses, send events at 25%, 50% and 75% widget.bind(SC.Widget.Events.PLAY_PROGRESS, function(obj) { go = false; pos = Math.round(obj['relativePosition'] * 100); if (pos === 25 && !q1) { act = '25%'; q1 = true; go = true; } if (pos === 50 && !q2) { act = '50%'; q2 = true; go = true; } if (pos === 75 && !q3) { act = '75%'; q3 = true; go = true; } if (go) { sendDl(cat, act, lab); } }); // When the sound finishes, send an event at 100% widget.bind(SC.Widget.Events.FINISH, function() { act = '100%'; q1 = q2 = q3 = false; sendDl(cat, act, lab); }); }); }; // Generic method for pushing the dataLayer event // Use a Custom Event Trigger with "scEvent" as the event name // Remember to create Data Layer Variables for eventCategory, eventAction, and eventLabel var sendDl = function(cat, act, lab) { window.dataLayer.push({ 'event' : 'scEvent', 'eventCategory' : cat, 'eventAction' : act, 'eventLabel' : lab }); }; // For each SoundCloud iFrame, initiate the API integration var i,len; var iframes = document.querySelectorAll('iframe[src*="api.soundcloud.com"]'); for (i = 0, len = iframes.length; i < len; i += 1) { initWidget(iframes[i]); } } catch(e) { console.log('Error with SoundCloud API: ' + e.message); } })(); </script>Assurez-vous que cette balise HTML personnalisée se déclenche sur un Affichage des pages Déclencheur, où le type de déclencheur est Prêt pour DOM. Si cela ne fonctionne pas, essayez de changer le type de déclencheur en Fenêtre chargée. Il est possible qu’une condition de concurrence émerge, où la balise HTML personnalisée est déclenchée avant le chargement de vos widgets SoundCloud, et le déplacement du déclencheur pour qu’il se déclenche sur la fenêtre chargée devrait remédier à cela.
Découpons-le en morceaux pour comprendre ce qui se passe. Cette fois, nous allons commencer par la fin !
// For each SoundCloud iFrame, initiate the API integration var i,len; var iframes = document.querySelectorAll('iframe[src*="api.soundcloud.com"]'); for (i = 0, len = iframes.length; i < len; i += 1) { initWidget(iframes[i]); } Le code ci-dessus parcourt tous les iframes de la page. S’il rencontre un iframe qui charge un widget SoundCloud intégré, il appelle le initWidget méthode, en utilisant l’objet iframe comme paramètre. C’est aussi simple que possible. Ce qui est cool, c’est que chaque iframe obtient ses propres liaisons, vous pouvez donc exécuter le script avec plusieurs widgets SoundCloud sur la page !
var initWidget = function(w) { var currentSound, act, pos, q1, q2, q3, go, lab; var cat = 'SoundCloud'; var widget = SC.Widget(w); // Events.READY is dispatched when the widget has been loaded widget.bind(SC.Widget.Events.READY, function() { // Get the title of the currently playing sound widget.getCurrentSound(function(cs) { lab = cs['title']; }); Le initWidget La fonction est appelée pour tous les iframes SoundCloud de la page. Tout d’abord, il déclare certaines variables d’utilité. Ensuite, il utilise l’API Widget SC.Widget constructeur pour créer un nouvel objet widget que l’API utilise pour les liaisons.
Sur les lignes suivantes, le SC.Widget.Events.READY l’événement est lié à l’objet widget. Cet événement est déclenché lorsque l’objet SoundCloud intégré est chargé et prêt à interagir. Tous les écouteurs sont placés dans ce rappel de fonction, car nous ne voulons pas commencer à écouter les événements avant que le fichier intégré ne soit chargé, n’est-ce pas ?
La première chose que nous faisons est d’obtenir le titre du son, et pour cela nous devons utiliser l’asynchrone getCurrentSound fonction, dont le rappel renvoie l’objet son. Ensuite, nous accédons à cet objet title clé et stockez-la dans une variable. Nous avons maintenant toutes les variables statiques définies et nous pouvons créer nos quatre écouteurs.
// Fire a dataLayer event when Events.PLAY is dispatched widget.bind(SC.Widget.Events.PLAY, function() { act = 'Play'; sendDl(cat, act, lab); }); Le premier auditeur est lié à la SC.Widget.Events.PLAY événement, qui, étonnamment, est envoyé lorsqu’un événement “Play” est enregistré dans le widget. Une fois que cela se produit, nous définissons le act variable sur “Play” et invoquez la sendDl (voir ci-dessous) méthode, qui fait le dataLayer.push(). Les paramètres sont les cat (“SoundCloud”), act (“Jouer”), et lab (Titre sonore) variables.
// Fire a dataLayer event when Events.PAUSE is dispatched // The only exception is when the sound ends, and the auto-pause is not reported widget.bind(SC.Widget.Events.PAUSE, function(obj) { pos = Math.round(obj['relativePosition'] * 100); if (pos !== 100) { act = 'Pause'; sendDl(cat, act, lab); } }); Le prochain événement que nous allons lier est SC.Widget.Events.PAUSE, qui est distribué lorsqu’un événement “Pause” est enregistré dans le widget. C’est pratiquement la même chose que l’événement “Jouer”, mais nous devons y ajouter une vérification supplémentaire. SoundCloud met automatiquement le son en pause lorsqu’il est terminé, afin que GA reçoive un certain nombre d’événements “Pause” qui n’ont pas été initiés par l’utilisateur. C’est pourquoi nous avons la vérification sur la première ligne du rappel, où nous voyons essentiellement si l’événement « Pause » s’est produit lorsque la position du son est à 100 %. Cela indiquerait qu’il s’agit d’une pause automatique, et nous n’invoquerons pas sendDl dans ce cas.
// As the play progresses, send events at 25%, 50% and 75% widget.bind(SC.Widget.Events.PLAY_PROGRESS, function(obj) { go = false; pos = Math.round(obj['relativePosition'] * 100); if (pos === 25 && !q1) { act = '25%'; q1 = true; go = true; } if (pos === 50 && !q2) { act = '50%'; q2 = true; go = true; } if (pos === 75 && !q3) { act = '75%'; q3 = true; go = true; } if (go) { sendDl(cat, act, lab); } }); La reliure suivante est pour le SC.Widget.Events.PLAY_PROGRESS. Cet événement est distribué toutes les quelques millisecondes, et l’objet qu’il renvoie a le position relative du son au moment de l’événement. Cette position relative est en fait un pourcentage de la distance parcourue par l’utilisateur. Donc, parce que j’ai choisi d’envoyer un événement à 25 %, 50 %, 75 % et 100 %, je dois vérifier si la position relative se situe à ces jalons. J’utilise aussi quelques booléens, q1 q2 q3 go, ce qui empêche le même jalon d’être envoyé plusieurs fois. Le go garantit que l’événement GA n’est déclenché que lorsque les jalons sont atteints, et non pour chaque itération de l’événement PLAY_PROGRESS.
// When the sound finishes, send an event at 100% widget.bind(SC.Widget.Events.FINISH, function() { act = '100%'; q1 = q2 = q3 = false; sendDl(cat, act, lab); }); Enfin, lorsque le son se termine, nous envoyons l’événement 100 %, et nous réinitialisons également les variables d’utilité. Si nous ne les réinitialisons pas, les écoutes répétées ne seront pas enregistrées.
// Generic method for pushing the dataLayer event // Use a Custom Event Trigger with "scEvent" as the event name // Remember to create Data Layer Variables for eventCategory, eventAction, and eventLabel var sendDl = function(cat, act, lab) { window.dataLayer.push({ 'event' : 'scEvent', 'eventCategory' : cat, 'eventAction' : act, 'eventLabel' : lab }); }; Et voici le sendDl méthode. Il prend juste les paramètres, et les pousse dans un dataLayer objet.
Le déclencheur
Pour activer les balises GTM lorsqu’un événement SoundCloud est enregistré, créez un nouveau déclencheur d’événement personnalisé qui ressemble à ceci :
C’est simple. Ce déclencheur déclenchera vos balises lorsque le sendDl La méthode que nous avons construite ci-dessus est invoquée.
Les variables de la couche de données
Ensuite, assurez-vous d’avoir Trois Variables de la couche de données. Un pour eventCategoryun pour eventActionet un pour eventLabel. Ils ressembleraient à quelque chose comme ça :
Celles-ci sont assez génériques, vous pourriez donc les trouver utiles ailleurs également.
La balise d’événement
Enfin, vous avez besoin d’un tag d’événement pour transmettre ces informations à Google Analytics. Configurez-le comme vous le feriez pour n’importe quel autre tag d’événement et assurez-vous qu’il se déclenche avec le déclencheur que vous avez créé auparavant (Événement – scEvent). Ensuite, ajoutez les trois Variables que vous avez créées à leurs champs respectifs :
Et c’est tout! Votre site devrait maintenant être prêt à collecter les hits des widgets SoundCloud.
Résumé et mises en garde
Tout d’abord, quelques mises en garde.
De temps en temps, j’ai remarqué une condition de concurrence ennuyeuse, où le widget s’était chargé avant que la balise HTML personnalisée GTM n’ait eu le temps de se terminer. Cela signifie que le SC.Widget.Events.READY a été envoyé trop tôt pour que l’auditeur puisse l’attraper. Cette condition de course pourrait être corrigée en ayant un délai d’attente d’une seconde ou quelque chose comme ça, qui fait alors les liaisons de toute façon. Je ne l’ai pas écrit dans cette solution, mais cela devrait être assez simple à mettre en œuvre une fois que vous aurez compris le fonctionnement de l’API Widget.
Certaines autres choses que j’ai remarquées étaient des erreurs de quota de l’API. Vous ne pouvez rien y faire, bien que je pense que vous pouvez vous abonner à un compte Premium où ces erreurs n’apparaissent pas. Pour autant que je sache, cependant, ils n’ont eu aucun impact sur cette solution de suivi, et les événements ont néanmoins été envoyés.
Quoi qu’il en soit, c’est une solution assez simple pour suivre les widgets SoundCloud sur votre site. J’ai essayé de refléter l’excellent guide de suivi YouTube de Cardinal Path.
L’API Widget dispose d’un certain nombre d’autres interfaces que vous pouvez utiliser si vous souhaitez améliorer encore la solution. Faites-moi savoir si vous avez rencontré des problèmes ou si vous avez des idées pour améliorer cette solution !
