Global sports widgets

Match Schedule and Results

Phase Schedule and Results

Team and Person

Football

US matches sports

Other major leagues

All Leagues

Technical Implementation Guide

Introduction

In this document you will find how our customers can use Global Sports Widgets by different means of implementation and customization.

Powered by Global Sports Data and with relational linking to Gracenote’s video data, Global Sports Widgets provide real-time, accurate sports scores and stats as well as enabling connectivity to sports event programming across linear TV and streaming. Global Sports Widgets are designed for simplified integration into web, mobile, Set-Top Boxes, Smart TVs and auto in-dash infotainment platforms, requiring minimal customer-side development resources.

Global Sports Widgets take in all relevant data points for a sports event and lay them out in a way appropriate to the sport concerned, updating scores and stats in real-time. Gracenote hosts the widget solution on AWS to secure a solid and high-performing service irrespective of the number of views.

With our react platform we aim to provide multi-platform and multi-view solutions. Our products are responsive with an approach to serve all times of implementations, from mobile apps to large video solutions. We have viewports for mobile devices and larger desktop screens. Our goal is to provide complete product offerings that give the ability to show sports widgets no matter the viewport to users.

In this Technical Implementation Guide we will show you how to add widgets to your platform and how to customize, optimize and configure those widgets.

Browser Support

The widgets work on all latest stable versions of the following major browser and platforms:

Mobile Devices: iOS, Android
Browsers: Safari, Chrome, Edge and Firefox

Gracenote will support each version of these browsers and platforms for two years from their release. We suggest testing on your target platform and contacting Gracenote for any needed support.

Looking at Smart TV and Set-Top Box compatibility specifically, the following requirements are relevant:

Smart TV	Requirements
Android TV	Android 6.x or higher
Tizen OS (Samsung)	2015 Smart TV models or newer
WebOS (LG)	WebOS 2.x and higher
Web Rendering Engine	Requirements
Chromium	Chromium 61 or higher
WebKit	WebKit 538.x or higher

Compatibility with the Chromium browser standards means that this also covers browsers like Chrome, Edge or Opera. Furthermore, compatibility with the WebKit standard also covers Safari.

Language Availability

Our widgets come in multiple languages and we currently support the following languages (where on a league-by-league basis it depends on which widgets/data are translated in which language):

Language	Country	ISO	Language	Country	ISO
American English	USA	en-US	Italian	ITA	it-IT
British English	ENG	en-GB	Japanese	JPN	ja-JP
Brazilian Portuguese	BRA	pt-BR	Korean	KOR	ko-KR
Dutch	NED	nl-NL	Russian	RUS	ru-RU
French	FRA	fr-FR	Spanish	ESP	es-ES
German	GER	de-DE	Swedish	SWE	sv-SE

Security

Nielsen has its cyber security program aligned to the NIST Cyber security framework with its own policies and standards. Nielsen’s cyber security team includes trained professionals who conduct vulnerability scanning, penetration testing and manual testing. For these services, we will be conducting vulnerability scanning on the public facing IP’s on a quarterly basis.

The Nielsen security team will conduct dynamic and static application system testing on the Widgets and API in the development environments before the product is released to the public. Critical and high vulnerabilities will have remediation planned as prioritized within the agreed upon release schedule and will be completed prior to release into production.

Implementation

Global Sports Widgets can be used as a stand-alone hosted solution for clients looking for sports data in a visually attractive way, but have no time to build a complete front-end solution themselves.

Besides that, for customers that use Global Sports Data to create their custom displays of schedules and results and/or alerts to have their audience tune-in, Global Sports Widgets can be used to render details of the events concerned.

Our widgets take into account the idiosyncrasies for each sport by taking in all relevant (match) details, in a lay-out appropriate for each sport and updating the data automatically. This relieves customers of dealing with the complexity of each sport.

The actual implementation of our widgets can be done in two ways:

Publication through the Widget Connect Service URL
Publication through a Widget Script Tag

Publication through the Widget Connect Service URL

The Widget Connect Service URL is a solution where we basically offer a hosted page with a Global Sports Widget on it for each of the relevant use cases. This URL follows the following convention:

https://widgetconnect.sports.gracenote.com/[ClientID]/[Language]/[GNID]/[Use Case]

So after the base URL, it consists of:

ClientIDA numerical value
Created by the Gracenote support team which is linked to the customer account with the entitlements associated to that account
Language
See the list in the Language Availability section for all available languages. This is used to adjust the language and date/time convention.
GNID
The Gracenote ID of the sports event, for which you want to render the data in the widget.

So for the 2022 Super Bowl with GNID GN4SFN6WGV9WBF3 you can construct the following URL to publish the widget in American English for the Gracenote Demo account with ClientID 1422:

https://widgetconnect.sports.gracenote.com/1422/en-US/GN4SFN6WGV9WBF3

Find below some other examples for different sports and languages:

Baseball in British English
https://widgetconnect.sports.gracenote.com/1422/en-GB/GNB7XKDXEKHEWY3
Basketball in Spanish
https://widgetconnect.sports.gracenote.com/1422/es-ES/GN918ABJTEWWA46
Ice Hockey in German
https://widgetconnect.sports.gracenote.com/1422/de-DE/GN4EEXW294VCDXH
Football in French
https://widgetconnect.sports.gracenote.com/1422/fr-FR/GN69KA0ATMR4CN7
Cricket in British English
https://widgetconnect.sports.gracenote.com/1422/en-GB/GNFFX913XWYXAGV
Golf in Korean
https://widgetconnect.sports.gracenote.com/1422/ko-KR/GN7B844HKAQPTKK

The service URL is hosted by Gracenote, including customizations like styling as is explained in the Custom CSS Guide. Furthermore, when passing an irregular Id the service URL will return an error message. See for example:

https://widgetconnect.sports.gracenote.com/1422/fr-FR/WrongSportsEventId

Publication through a Widget Script Tag

It is also possible to publish a widget through the widget script that operates the widgets in similar fashion as those through the Widget Connect Service URL. The widget scripts will be configured for the customer by the Gracenote support team with a [customer_widget_id].

We highly recommend that customers publish their widgets by means of the SDK Loader. This script tag needs to be inserted right before the </body> or body closing tag on the web page they want to publish the widget on. The SDK Loader offers advantages in performance and implementation features. The full documentation of the SDK Loader can be found in Appendix A.

When working with the widget script tag, the customer can be enabled to adjust the customization parameters in the script itself, which would otherwise be configured in the [customer_widget_id] by the Gracenote support team.

The widget tag for the widget using the SDK Loader does not require javascript <script> tags and would consist of the following </div> tags:

										<div class="gnsWidget" data-widget_id="[customer_widget_id]" data-language_id="2" data-language="en_US" data-match_id="GNAJ93QVGZF9DW6" data-custom_css="./custom_css/tv-base.css" data-show_league_header="yes" data-away_first="GN1CZ62RQT2X0R8" ></div>

Without the SDK Loader the script tag would include the javascript <script> tags and then is as follows:

										<script async="" src="https://widgets.sports.gracenote.com/gns.widget.loader.js"  data-widget_id="[customer_widget_id]" data-language_id="2" data-language="en_US" data-match_id="GNAJ93QVGZF9DW6" data-custom_css="./custom_css/tv-base.css" data-show_league_header="yes" data-away_first="GN1CZ62RQT2X0R8" ></script>

Customization

As shown in the publication samples above, the widgets can be operated through a number of parameters to customize both from a data and a look and feel perspective. The data parameters are explained in the Functionality Guide and all information regarding adjustments to the look and feel of the widgets can be found in the Custom CSS Guide.

Appendix A: SDK Loader

Our Widget SDK Loader can be used for all our existing Global Sports Widgets and serves as an alternative to our script tag implementation, driving improvements in the following areas:

Improved loading speeds
Additional features
Improved flexibility

Improved loading speeds

Our widget SDK Loader can improve loading speeds which benefits the overall user experience of our widgets. This can be the result of one or more of the following factors

The widget implementation is placed higher in the html <body> tag and is called upon quicker
Widgets can share resources that save data traffic for the user which results in lower loading times

These improvements in loading speeds are especially noticeable when a client implements multiple widgets on a page.

Additional features

Though currently, few features are available to widgets that are implemented with the SDK Loader, our goal is to implement features during the development of our widget platform. This includes but is not limited to the availability of sponsoring (ads) within widgets or custom remote controls for TV widget implementations.

Improved flexibility

With the widget SDK Loader clients can implement widgets in any html tag, this highly improves the flexibility for customers that add widgets to their platforms. Mostly for clients that have CMS systems that do not support javascript <script> tags, these clients can now implement widgets using a more common <div> tag to implement our widgets.

Technical Documentation

Clients will need to implement a script tag in their main template, which is loaded wherever they wish to load widgets. This script tag needs to be inserted right before the </body> or body closing tag on their page. We recommend implementing the script tag as high in the html body as possible, which results in our widgets getting priority over other elements in the page while being loaded.

										<script>
(function(g,r,a,c,e){r.gnsWidgetObject=e;r[e]=r[e]||function(n,o,t){t=Object.prototype.toString.call(t)==='[object Array]'?t:[t];(r[e].q=r[e].q||[]).push([n,o,t])};r[e].c=r[e].c||{l:a};r.c=r.c||function(fs){r[e].c.featureSwitch=fs};var x=g.getElementsByTagName("script")[0],y=g.createElement("script"),z=g.createElement("script");y.async=0;y.src=c;z.async=1;z.src=a;x.parentNode.insertBefore(y,x);x.parentNode.insertBefore(z,x)})(document,window,"http://widgets.sports.gracenote.com/gns.sdk.loader.js","http://widgets.sports.gracenote.com/featureSwitches.jsonp", "gnsWidget");
gnsWidget('widgets','create');
</script>

Widgets can now be loaded in any tag, as long as they have “gnsWidget” as class name. for example:

										<div class="gnsWidget" data-widget_id="[customer_widget_id]" data-custom_css="./custom_css/tv-base.css" data-language_id="2" data-language="en_US" data-match_id="GNAJ93QVGZF9DW6" data-away_first="GN1CZ62RQT2X0R8"></div>

Furthermore, the SDK Loader can be called upon in the console of the browser and also clients can implement commands in their code by adding the following snippets right after the SDK Loader implementation.

Show all currently executed commands (Only on the browser console)

										gnsWidget.q

Trigger the create function
It transforms the elements in the html code into functional widgets.

										gnsWidget('widgets', 'create')

Trigger the afterCreate function
It runs a custom javascript callback function right after the widgets are rendered on the screen.

										gnsWidget('widgets','afterCreate', function afterCreate() { document.getElementById("loaded").innerHTML = "Widgets created"; });

Trigger the mobileResize function
Sets the width of the iFrame to 1px, and the min-width to 100%. Used to solve problems with sizing for mobile devices.

										gnsWidget('events', 'mobileResize', {iFrameId: 'YOURIFRAMEID'})

Trigger the scrollY function
It scrolls a certain distance, positive values are admitted to scroll down, and negatives to scroll up

										gnsWidget('events', 'scrollY', {distance: 200});

Trigger the hide function

										gnsWidget('events', 'hide', {iFrameId: 'YOURIFRAMEID'});

Trigger the show function

										gnsWidget('events', 'show', {iFrameId: 'YOURIFRAMEID'});

Overwrite linking function
This overwrites the links with custom links. There are endless possibilities so everything depends on what you want to do with it.

										gnsWidget('events','customLinking', function(message) {
    /*
    How to use this function?
    
    The data (which we call message in this example) which is being passed on contains 4 important elements:
    - name
    this contains the name of the link which is clicked. A widget can have more than 1 link to click. By
    using this name, we can find out which link was actually clicked.
    - data
    This contains the data of the row that was clicked. This can contain a lot of different things, like
    athlete names, sport names etc. etc.
    - settings
    This contains the current widget settings. You could potentially do a check on a specific setting, and
    based on its value, change the location of the url.
    - stateToSave
    If we are linking to a new widget, we might want to save the current state of this widget so we can easily
    go back.

To overwrite one or more specific link names only, and let the rest of the links continue as usual, wrap the function in brackets, and specify the link names to overwrite as secondary parameters.

										gnsWidget('events','customLinking',[function(message) {
    // Your function
}, 'linkNameToCatch','additionalLinkNameToCatch']);

Frequently Asked Questions (FAQ)

Can the height of the widget be adjusted?

No. The only way to adjust the height of the widget is to implement this widget inside of a div tag for example and give this div tag a certain height and the right to scroll in CSS (height: 500px; overflow-y: scroll). That way, if the widget is bigger than 500px in height, a scrollbar will appear inside of the div and the height of the div will stay at 500px.

Can the text of the header be adjusted?

This can be handled with css. See below for a code example on how to do this.

										// Hide the original title
.header__titles__title {
	display: none;
}

// Implement new title
.header__titles:after {
	display: block;
	color: #FFFFFF; // Use any color you like. White is default.
font-weight: bold;
font-size: 20px; // 20px for mobile, 22px for larger viewports.
content: 'Your new title';
}

Can I add a single widget to every page of my website?

Some widgets, like Carousel, are indeed suited to implement (sticky) on every page of a website. For these widgets we recommend creating a wrapper div to render the widget instead of a full page refresh. This way the widget doesn’t always reload when a user switches to another page, which doesn’t only have a positive effect on the amount of times the widget has to reload but also will optimize the widget implementation.

How can I change linking from one widget to another or from a widget to another page on my website?

You can link from and to widgets in all sorts of ways.

widget:default
You can link from one widget to another widget by using the widget:default link. This is our default linking possibility.
widget:id/YOURWIDGETID
With this option, you can link to a specific widget id. This option is probably useless, since you can’t set specific widget parameters.
https://yourwebsite.com/$data$/$moreData$
With this option you can link to a specific webpage. Additionally, you can use available data, and set those in between dollar signs. This will then be replaced with available data when clicking on the link.

For example, if you wish to link to a page with a specific match ID (when available), you can do so by simply setting the url to: https://yourwebsite.com/$matchId$
If you wish to also add the league name, you can change the link to: https://yourwebsite.com/$league$/$matchId$

You will then need to make your page able to grab the matchId from the url, and insert this in your widget as a data-match_id variable.
Since there are many different coding languages, and we do not know how your website is set up, you need to ask your webmaster on the best way to implement this.

If you wish to know what data is available, you can find out by using the SDK Loader customLinking function, like this:

										gnsWidget('events','customLinking',[function(message) {
            console.log(‘Link name:’, message.name);
            console.log(‘Link data:’, message.data);
}]);

Then open your browser console, and click the link. The data will show up in the console (F12 for Google Chrome).

And if you wish to only target specific links, use the link names as a second parameter like this:

										gnsWidget('events','customLinking',[function(message) {
    console.log(‘Link name:’, message.name);
    console.log(‘Link data:’, message.data);
    switch (message.name) {
        case 'carouselScheduleLink':
            switch(message.data.leagueId) {
                // MLS
                case "GNBG95JCWFJ1VWX":
                    location.href = 'https://www.google.com/majorleaguesoccer';
                    break;
                case "GNE5YV67YEXTR5R":
                    location.href = 'https://www.clarosports.com/basquetbol/nba/';
                default:
                    break;
            }
            break;
        case 'carouselMatchLink':
            switch(message.data.leagueId) {
                // MLS
                case "GNBG95JCWFJ1VWX":
                    location.href = 'https://www.google.com/matches/majorleaguesoccer';
                    break;
                case "GNE5YV67YEXTR5R":
                    location.href = 'https://www.clarosports.com/matches/basquetbol/nba/';
                default:
                    break;
            }
            break;
        default:
            break;
    }
},'carouselScheduleLink,carouselMatchLink’]);