Analytics Setup

This guide explains how to set up web and mobile app analytics for your News Suite installation using Matomo, including proper content attribution and audio analytics tracking.

---

WhiteBeard News Suite uses Matomo for comprehensive web and mobile app analytics. Matomo provides detailed insights into user behavior, content performance, and engagement metrics across your digital properties.

---

Basic Setup

Step 1: Install the Matomo Tag

1. Obtain Your Matomo Tag:

   • Contact WhiteBeard News Suite support to receive your unique Matomo tag
   • The tag will be provided in a format ready for your tag manager

2. Insert the Tag:

   • Add the Matomo tag provided by support into your tag manager
   • Ensure the tag is configured to fire on all pages

This basic setup enables general analytics tracking across your website and mobile applications.

---

Content Attribution Setup

For accurate content performance tracking and detailed article analytics, additional data layer variables must be configured. This setup is essential for understanding which articles drive engagement and revenue.

Required Data Layer Variables

Configure the following variables in your data layer before triggering your pageview event or other tracking events:

Variable Name	Type	Description
ArticleId	String	The unique ID of the content or article the user is viewing
CategoryId	String	The ID of the primary category for the content
ParentId	String	The publication ID that the content belongs to
Premium	String	User subscription status: 0 for non-subscribers, 1 for subscribers

Implementation Example

Push data to the Matomo data layer using the following format:

window._mtm.push({
  'ArticleId': 123,
  'CategoryId': '2',
  'ParentId': '1',
  'Premium': 1
});

When to Push Data

• Article Pages: Push the data layer variables immediately when the article page loads, before any pageview or engagement events
• Dynamic Content: Update the data layer when users navigate to different articles in single-page applications
• Premium Status: Update the Premium variable if the user’s subscription status changes in the same page

Example Implementation

// Example: Push data layer on article page load
document.addEventListener('DOMContentLoaded', function() {
  if (typeof window._mtm !== 'undefined') {
    window._mtm.push({
      'ArticleId': document.querySelector('[data-article-id]').dataset.articleId,
      'CategoryId': document.querySelector('[data-category-id]').dataset.categoryId,
      'ParentId': document.querySelector('[data-publication-id]').dataset.publicationId,
      'Premium': userIsSubscribed ? 1 : 0
    });
  }
});

Additional Resources

For comprehensive documentation on using the Matomo data layer, including advanced configurations and troubleshooting, refer to the official Matomo documentation:

Matomo Tag Manager Data Layer Guide

---

Audio Analytics

If you’re implementing a custom audio player, you can track detailed audio engagement metrics by sending specific events to the Matomo data layer.

Audio Event Structure

Push audio events using the following format:

window._mtm.push({
  'event': 'audio_event',
  'action': 'audio-start',
  'AudioAttachmentId': 123
});

Required Parameters

Parameter	Type	Description
event	String	Always set to 'audio_event' for audio tracking
action	String	The specific audio action being tracked (see below)
AudioAttachmentId	String	The unique ID of the audio attachment being played

Audio Event Actions

Track the following audio playback events to understand listener engagement:

Core Events

Action	When to Fire	Description
audio-start	Audio begins playing	Fired when the user starts audio playback for the first time
audio-end	Audio completes	Fired when audio playback reaches the end of the content
audio-listened	After 10 seconds	Fired once per page after 10 seconds of continuous playback (indicates genuine engagement)

Progress Events

Track listening duration by firing progress events every 10 seconds of playback:

Action	When to Fire
audio-progress-10	After 10 seconds of playback
audio-progress-20	After 20 seconds of playback
audio-progress-30	After 30 seconds of playback
audio-progress-N	Continue every 10 seconds (40, 50, 60, etc.)

Implementation Examples

Starting Audio Playback

audioPlayer.addEventListener('play', function() {
  window._mtm.push({
    'event': 'audio_event',
    'AudioAttachmentId': audioId,
    'action': 'audio-start'
  });
});

Tracking 10-Second Engagement

// After 10 seconds of continuous playback (fires once per page)
let hasTrackedListened = false;

audioPlayer.addEventListener('timeupdate', function() {
  if (!hasTrackedListened && audioPlayer.currentTime >= 10) {
    window._mtm.push({
      'event': 'audio_event',
      'AudioAttachmentId': audioId,
      'action': 'audio-listened'
    });
    hasTrackedListened = true;
  }
});

Tracking Progress Events

// Fire every 10 seconds during playback
audioPlayer.addEventListener('timeupdate', function() {
  const currentTime = Math.floor(audioPlayer.currentTime);

  if (currentTime > 0 && currentTime % 10 === 0) {
    window._mtm.push({
      'event': 'audio_event',
      'AudioAttachmentId': audioId,
      'action': `audio-progress-${currentTime}`
    });
  }
});

Audio Completion

audioPlayer.addEventListener('ended', function() {
  window._mtm.push({
    'event': 'audio_event',
    'AudioAttachmentId': audioId,
    'action': 'audio-end'
  });
});

---

Video Analytics

If you’re implementing a custom video player, you can track detailed video engagement metrics by sending specific events to the Matomo data layer.

Video Event Structure

Push video events using the following format:

window._mtm.push({
  'event': 'video_event',
  'action': 'loaded',
  'VideoAttachmentId': 123
});

Required Parameters

Parameter	Type	Description
event	String	Always set to 'video_event' for video tracking
action	String	The specific video action being tracked (see below)
VideoAttachmentId	String	The unique ID of the video being played
value	Varies	Additional context for the action (see below); may be omitted

Video Event Actions

Track the following video playback events to understand viewer engagement:

Core Events

Action	When to Fire	value	Notes
loaded	Video metadata has loaded	—
start	First time playback begins in the session	—	Fired once per session only
play	Playback starts/resumes	current playback time (seconds)
pause	Playback is paused	current playback time (seconds)	Do not fire if the pause is actually the video reaching its natural end, or if it happens as part of a seek
end	Playback reaches the end	—

Progress Events

Action	When to Fire	value	Notes
time_{N}	Every 10 seconds of playback (time_10, time_20, …)	—
seek	Playhead jumps more than 2 seconds between ticks	{ from, to } (previous/new time in seconds)

Player State Events

Action	When to Fire	value	Notes
volume change	Volume is changed	new volume (0 if muted)
unmuted	Volume changes away from muted/0	new volume
resize - {width}*{height}	Player is resized	—
error	A player error occurs	current playback time (seconds)	Always fire, even if the same error repeats
enter fullscreen / exit fullscreen	Fullscreen is toggled	current playback time (seconds)	Only fire when an ad is not currently playing

Deduplication

If the same action would fire twice in a row, only send the first call to Matomo — skip the repeat. The error action is exempt from this rule and should always be sent.

Implementation Examples

Starting Video Playback

videoPlayer.addEventListener('play', function() {
  window._mtm.push({
    'event': 'video_event',
    'VideoAttachmentId': videoId,
    'action': hasStarted ? 'play' : 'start',
    'value': videoPlayer.currentTime
  });
  hasStarted = true;
});

Tracking Progress Events

// Fire every 10 seconds during playback
videoPlayer.addEventListener('timeupdate', function() {
  const currentTime = Math.floor(videoPlayer.currentTime);

  if (currentTime > 0 && currentTime % 10 === 0) {
    window._mtm.push({
      'event': 'video_event',
      'VideoAttachmentId': videoId,
      'action': `time_${currentTime}`
    });
  }
});

Video Completion

videoPlayer.addEventListener('ended', function() {
  window._mtm.push({
    'event': 'video_event',
    'VideoAttachmentId': videoId,
    'action': 'end'
  });
});

Player Errors

videoPlayer.addEventListener('error', function() {
  window._mtm.push({
    'event': 'video_event',
    'VideoAttachmentId': videoId,
    'action': 'error',
    'value': videoPlayer.currentTime
  });
});

---

Best Practices

Data Quality

• Validate Data: Ensure all data layer variables are populated correctly before pushing to Matomo
• Consistent IDs: Use consistent ID formats across your implementation
• Error Handling: Implement error handling to prevent tracking failures from breaking your site

Privacy Considerations

• User Consent: Ensure you have proper user consent before tracking, in compliance with GDPR and other privacy regulations
• PII Protection: Never include personally identifiable information (PII) in custom variables
• Subscription Status: The Premium variable should only indicate subscription status, not specific user identity

Testing

Before deploying to production:

1. Verify Tag Installation: Confirm the Matomo tag fires correctly on all pages
2. Test Data Layer: Check that all variables are being pushed with correct values
3. Validate Events: Ensure audio and video events fire at the correct times
4. Use Matomo Debugger: Utilize browser developer tools and Matomo’s debugging features to verify tracking

---

Troubleshooting

Data Layer Not Pushing

If data isn’t appearing in Matomo:

• Verify window._mtm is defined before pushing data
• Check browser console for JavaScript errors
• Ensure the Matomo tag is loaded before data layer pushes

Missing Article Data

If article metrics aren’t tracking:

• Confirm CategoryId and ParentId are being set on article pages
• Check that data is pushed before pageview events

Audio Events Not Recording

If audio analytics aren’t working:

• Verify AudioAttachmentId is correct
• Check that events fire at the right playback moments
• Ensure 'event': 'audio_event' is included in all audio pushes

Video Events Not Recording

If video analytics aren’t working:

• Verify VideoAttachmentId is correct
• Check that events fire at the right playback moments
• Ensure 'event': 'video_event' is included in all video pushes
• Confirm duplicate consecutive actions are being skipped (except error, which should always fire)

---

Getting Support

For assistance with analytics setup or custom implementations:

• Contact WhiteBeard News Suite support for your Matomo tag and configuration
• Refer to Matomo’s official documentation for advanced features
• Work with your development team to ensure proper integration with your specific platform architecture