Error Handling

#What Is Widget Error Handling?

Widget error handling allows you to gracefully manage situations where widgets encounter problems during loading or runtime. With proper error handling, you can:

• Prevent poor user experience - Hide or replace widgets that fail to load instead of showing error messages
• Maintain page integrity - Keep your page layout clean even when widgets encounter issues
• Provide fallback content - Display alternative content when widgets are unavailable
• Debug integration issues - Identify and resolve configuration problems during development

The error handling system provides multiple approaches: silent mode for production environments, the onTrack callback for custom error handling logic, and visual error indicators for development and debugging.

#Audience

This tutorial is for developers and integrators who are implementing Sportradar widgets and need to handle potential widget errors effectively. Understanding error handling is essential for creating production-ready integrations that gracefully handle failures.

#Goals

In this tutorial you will learn:

• the different types of widget errors and what causes them
• how to use the silent property to suppress error messages in production
• how to implement custom error handling with the onTrack callback
• how to conditionally display widgets based on their loading status
• how to debug widget errors during development

#Prerequisites

In order to complete this tutorial you will need:

• a website with at least one Sportradar widget integrated
  • if you need to integrate a widget first, see the getting started guide
• basic knowledge of JavaScript and HTML
• access to browser developer tools (Chrome DevTools or Firefox Developer Tools)
• a text editor of your choice

#Understanding Widget Errors

Before implementing error handling, it's important to understand the types of errors that can occur and what causes them.

#Common Error Types

Sportradar widgets can encounter several types of errors, each with different causes and solutions:

#Configuration Errors

These errors occur when a widget is missing required parameters or has invalid configuration:

• No widget displayed - The widget container remains empty
• "Something went wrong..." message - Invalid or missing matchId, seasonId, tournamentId, or other required parameters
• Unrecognized widget - The widget name is incorrect or not supported

Common causes:

• Missing or incorrect widget initialization script
• Wrong Client ID in the widgetloader URL
• Incorrect widget element selector
• Invalid widget name

#Data Availability Errors

These errors occur when valid configuration exists but data is not available:

• "No statistics available" - The match has not started yet or statistics are not yet available
• "No data available" - Requested data does not exist for the given parameters

Common causes:

• Match has not started
• Data is temporarily unavailable from the data provider
• Requested resource does not exist

#Licensing Errors

These errors occur when there are issues with widget licensing:

• "No license" error icon - Your account does not have a valid license for the requested widget or data

Common causes:

• Missing or expired license
• Attempting to access data outside your license scope

For detailed information about licensing errors and how to resolve them, see the Licensing page.

#General Errors

Unexpected errors that don't fall into the above categories:

• Generic error icon - System or network errors

If you encounter this type of error, contact support with details about your configuration and any error messages in the browser console.

#Error Handling Approaches

There are two main approaches to handling widget errors: using the silent property for simple error suppression, or implementing custom logic with the onTrack callback for more sophisticated error handling.

#Approach 1: Silent Mode (Production)

The silent property is the simplest way to prevent error messages from being displayed to end users. When set to true, the widget will not render error icons or messages, keeping your page clean even when errors occur.

Example:

SIR('addWidget', '#widget-container', 'match.lmtPlus', {
    matchId: 12345678,
    silent: true  // Suppress error display
});

When to use silent mode:

• Production environments where you want to hide errors from users
• When you have alternative content or fallback mechanisms in place
• For optional widgets that enhance the page but aren't critical

Limitations:

• Errors are suppressed but not handled - the widget simply won't display
• You cannot execute custom logic based on error states
• The container element may remain empty, potentially affecting page layout

#Approach 2: Custom Error Handling With onTrack

The onTrack callback provides fine-grained control over widget behavior by allowing you to execute custom code when specific events occur, including errors. This approach enables conditional display, fallback content, and advanced error recovery strategies.

The onTrack function receives two parameters:

When to use onTrack:

• When you need to show/hide UI elements based on widget status
• To implement fallback content when widgets fail to load
• To track and log errors for monitoring purposes
• For conditional widget display (e.g., tabs that should only appear if the widget loads)

For detailed information about onTrack events and parameters, see the onTrack documentation.

#Interactive Code Tutorial: Conditional Widget Display

Let's implement a complete solution that loads a widget conditionally and only displays a toggle button if the widget loads successfully without errors.

<!DOCTYPE html>
<html lang="en">
<head>
    <title>Widget Error Handling Demo</title>
    <style>
        #page-content {
            display: flex;
            align-items: center;
            justify-content: center;
            flex-direction: column;
        }
    </style>
</head>
<body>
    <!-- Main page content area -->
    <div id="page-content">
        <button id="toggle-button" style="display: none">
            Toggle Widget Display
        </button>
    </div>
    
    <!-- Hidden loading area for widget -->
    <div id="loading-area" style="display: none">
        <div id="widget-container" class="sr-widget"></div>
    </div>
    
    <script>
        // Get DOM elements
        const loadingArea = document.getElementById('loading-area');
        const pageContent = document.getElementById('page-content');
        const widget = document.getElementById('widget-container');
        const toggleButton = document.getElementById('toggle-button');
        
        // Initialize widgets framework
        (function(a,b,c,d,e,f,g,h,i){a[e]||(i=a[e]=function(){
            (a[e].q=a[e].q||[]).push(arguments)},i.l=1*new Date,i.o=f,
            g=b.createElement(c),h=b.getElementsByTagName(c)[0],
            g.async=1,g.src=d,g.setAttribute("n",e),
            h.parentNode.insertBefore(g,h)
        )})(window,document,"script",
            "https://widgets.sir.sportradar.com/sportradar/widgetloader",
            "SIR", {
                language: "en",
                theme: false
            }
        );
        
        // Error handling callback
        const onTrack = (eventType, data) => {
            if (eventType === 'data_change') {
                if (!data.error) {
                    // Widget loaded successfully
                    loadingArea.removeChild(widget);
                    pageContent.appendChild(widget);
                    toggleButton.style.display = 'block';
                } else {
                    // Widget encountered an error
                    console.error('Widget error:', data.error);
                }
            }
        };
        
        // Toggle widget visibility
        const toggleWidget = () => {
            const isHidden = widget.style.display === 'none';
            widget.style.display = isHidden ? 'block' : 'none';
        };
        toggleButton.onclick = toggleWidget;
        
        // Load widget with error handling
        SIR("addWidget", "#widget-container", "match.scoreboard", {
            matchId: 43406689,
            onTrack: onTrack
        });
    </script>
</body>
</html>

#Debugging Widget Errors

When developing and testing your widget integration, debugging errors effectively is crucial for identifying and resolving issues quickly.

#Enable Error Display During Development

Always set silent: false (or omit the silent property, as this is the default) during development. This ensures error messages and icons are displayed, making it easier to identify problems.

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: false  // Show errors during development
});

#Use Browser Developer Tools

Browser developer tools are essential for debugging widget errors:

1. Open the Console

   • Chrome: Press F12 or Ctrl+Shift+J (Windows/Linux) / Cmd+Option+J (Mac)
   • Firefox: Press F12 or Ctrl+Shift+K (Windows/Linux) / Cmd+Option+K (Mac)

2. Look for Error Messages

   • Widget errors often include descriptive messages in the console
   • Check for network errors that might indicate connectivity issues
   • Review any stack traces to identify where errors occur

3. Inspect Network Requests

   • Open the Network tab in developer tools
   • Look for failed requests (marked in red)
   • Check if the widgetloader script loaded successfully
   • Verify that data requests to Sportradar APIs complete successfully

#Common Debugging Steps

// Verify SIR function is available
console.log(typeof SIR); // should output "function"

#Log Error Information

Implement comprehensive error logging to help diagnose issues:

const onTrack = (eventType, data) => {
    console.log('Widget event:', eventType);
    
    if (eventType === 'data_change') {
        if (data.error) {
            // Log detailed error information
            console.error('Widget error occurred:', {
                error: data.error,
                widgetData: data,
                timestamp: new Date().toISOString()
            });
        } else {
            console.log('Widget loaded successfully');
        }
    }
    
    if (eventType === 'license_error') {
        console.error('License error:', data.error);
    }
};

#Best Practices

Follow these best practices to implement robust error handling:

#1. Different Configurations for Development and Production

Use environment-specific settings to balance debugging capabilities with user experience:

const isProduction = window.location.hostname !== 'localhost';

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: isProduction,  // Hide errors in production only
    onTrack: (eventType, data) => {
        if (!isProduction && data.error) {
            // Detailed logging in development
            console.error('Widget error:', data.error);
        }
        // Production error tracking (e.g., send to analytics)
        if (isProduction && data.error) {
            // trackError(data.error);
        }
    }
});

#2. Provide Fallback Content

Always consider what users should see when a widget fails to load:

<div id="widget-wrapper">
    <div id="widget-container"></div>
    <div id="fallback-content" style="display: none;">
        <p>Live match data is temporarily unavailable.</p>
        <a href="/schedule">View match schedule</a>
    </div>
</div>

<script>
const showFallback = () => {
    document.getElementById('widget-container').style.display = 'none';
    document.getElementById('fallback-content').style.display = 'block';
};

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    silent: true,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            showFallback();
        }
    }
});
</script>

#3. Handle Licensing Errors Gracefully

Licensing errors require special attention as they indicate configuration or subscription issues:

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'license_error') {
            console.error('License error:', data.error);
            // Notify your team about license issues
            // notifyAdmin('Widget license error', data.error);
            
            // Show user-friendly message
            document.getElementById('widget-container').innerHTML = 
                '<p>This feature is currently unavailable.</p>';
        }
    }
});

#4. Validate Configuration Before Loading

Prevent errors by validating configuration before attempting to load widgets:

function loadWidget(matchId) {
    // Validate matchId
    if (!matchId || typeof matchId !== 'number') {
        console.error('Invalid matchId:', matchId);
        return;
    }
    
    SIR('addWidget', '#widget-container', 'match.scoreboard', {
        matchId: matchId,
        onTrack: (eventType, data) => {
            if (eventType === 'data_change' && data.error) {
                console.error('Widget failed to load:', data.error);
            }
        }
    });
}

// Usage
loadWidget(12345678);  // Valid
loadWidget('invalid'); // Prevented with error message

#5. Clean up on Errors

Remove or hide widget containers when errors occur to maintain clean page layouts:

SIR('addWidget', '#widget-container', 'match.scoreboard', {
    matchId: 12345678,
    onTrack: (eventType, data) => {
        if (eventType === 'data_change' && data.error) {
            const container = document.getElementById('widget-container');
            // Option 1: Hide the container
            container.style.display = 'none';
            
            // Option 2: Remove it entirely
            // container.remove();
            
            // Option 3: Replace with message
            // container.innerHTML = '<p>Content unavailable</p>';
        }
    }
});

#Further Reading

• onTrack Documentation - Detailed information about the onTrack callback and all available events
• Widget Errors Reference - Comprehensive list of widget error types and solutions
• Troubleshooting Guide - Common widget integration issues and how to resolve them
• Getting Started Guide - Basic widget integration steps
• Licensing Documentation - Information about widget licensing and related errors
• SIR API Reference - Complete API documentation for the SIR global function
• Support - How to get help with widget integration issues