Usage (Web)¶

The SDK can be used either with the generic ClientAnalytics class or with player-specific builds that provide tighter integration with popular video players.

Generic Usage¶

The SDK is initialized by creating a new instance of the ClientAnalytics class and attaching it to your video element:

<!DOCTYPE html>
<html lang="en">
<head>
  <!-- Rreplace this with your own path -->
  <script src="surfmeter-client-analytics.min.js"></script>
</head>
<body>
  <!-- Replace this with your own video element -->
  <video controls></video>
  <script>
    // Initialize the analytics class
    const sca = new surfmeter.ClientAnalytics(
        // Replace this with your own API key
        "YOUR_API_KEY",
        {
            // Optional: replace this with your own unique identifier for fingerprinting purposes.
            // if you do not provide one, we will generate a random one for you!
            fingerprint: 'unique-identifier',
            // Optional: set additional measurement metadata
            metadata: {
                userId: 'user123',
                channelId: 'channel456',
            }
        }
    );

    // Attach to video element
    const video = document.getElementsByTagName('video')[0];
    const { internalMeasurementId } = sca.measure(video);

    // Optionally set additional measurement metadata
    sca.setMetadata(internalMeasurementId, {
      userId: 'user123',
      channelId: 'channel456',
    });
  </script>
</body>
</html>

The metadata can be retrieved in the dashboard, and are very useful for segmenting your data for analysis purposes.

Warning

Please make sure that if you send personal data such as customer IDs, names, or email addresses, you have the necessary consent of the user to do so.

Player-Specific Builds¶

For better integration with specific video players, we offer dedicated builds that handle player-specific events and states automatically.

Shaka Player Integration¶

For Shaka Player, use the ShakaplayerAnalytics class:

if (shaka.Player.isBrowserSupported()) {
  // Initialize video and player
  const video = document.getElementsByTagName('video')[0];
  const player = new shaka.Player(video);

  // Initialize analytics like in the generic example above
  const surfmeterAnalytics = new surfmeter.ShakaplayerAnalytics(
    "YOUR_API_KEY",
    {
        fingerprint: 'unique-identifier',
        metadata: {
            userId: 'user123',
            channelId: 'channel456',
        }
    }
  );

  // Attach analytics to player
  const handler = surfmeterAnalytics.measure(player);

  // Load content
  player.load('manifest-url');
} else {
  console.error('Browser not supported!');
}

The measure() method returns a handler object with the following interface:

interface ScaHandler {
  surfmeterMonitoringId: string;  // internal ID for the measurement
  destroy: VoidFunction;          // call to stop measurement and cleanup
  onPlaybackError: (message?: string) => void;  // report playback errors
}