Vizrt Feed Streamer User s Guide 1.1

Transcription

1 Vizrt Feed Streamer User s Guide 1.1

2

3 . All rights reserved. No part of this software, documentation or publication may be reproduced, transcribed, stored in a retrieval system, translated into any language, computer language, or transmitted in any form or by any means, electronically, mechanically, magnetically, optically, chemically, photocopied, manually, or otherwise, without prior written permission from Vizrt. Vizrt specifically retains title to all Vizrt software. This software is supplied under a license agreement and may only be installed, used or copied in accordance to that agreement. Disclaimer Vizrt provides this publication as is without warranty of any kind, either expressed or implied. This publication may contain technical inaccuracies or typographical errors. While every precaution has been taken in the preparation of this document to ensure that it contains accurate and up-todate information, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained in this document. Vizrt s policy is one of continual development, so the content of this document is periodically subject to be modified without notice. These changes will be incorporated in new editions of the publication. Vizrt may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time. Vizrt may have patents or pending patent applications covering subject matters in this document. The furnishing of this document does not give you any license to these patents. Technical Support For technical support and the latest news of upgrades, documentation, and related products, visit the Vizrt web site at Last Updated

4

5 Table of Contents 1 Introduction Social TV Components Related Documents Customer Feedback and Suggestions Customer Support Request Before Submitting a Support Request Submitting a Support Request System Log Files Requirements Data Hub and Social TV Server Requirements Hardware Software Social TV Client Requirements Social TV Plugin Requirements Upgrading Installation Installation Recommendations Installing the Data Hub Installing the Social TV Server Installing the Social TV Client Installing the Social TV Plugins Configuration Configuring Ports Configuring the Viz Trio Client Configuring the Feed Streamer Internet Access via Proxy Feed Streamer Cache and Proxy Settings Adding Custom Reader Configurations Changing the Data Hub URI, Trio MSE or Ticker MSE Configuring Data Analytics Configuring Data Hub Backup and Load Balancing Hot Backup Cold Backup Load Balancing and Failover... 30

6 5 Working with Feed Streamer Feed Streamer Workflow Sources Groups Moderation Previewing Items Moderation by Source Moderation by Group Moderating Items Filtering Items Copy URI Destinations Destination - Ticker Destination - Trio Working with External Viz Applications Working in Viz Trio Feed Streamer External Moderation Dialog Working with Viz Multichannel Working with Viz Content Pilot Working with Data Analytics Overview Data Analytics Reports Third Party Integrations Activating an Integration Mass Relevance Never.No Excitem CellJournalist Bloomberg News and Pictures Wochit Applicaster Defining Custom Readers How to Define a Custom Reader Understanding Requests Understanding Responses Including Media Objects in Feed Streamer Atom Entries Including VDF payloads in Feed Streamer Atom Entries... 62

7 9.1.5 Reading JSON Feeds Template Switching Concatenating Selected Nodes The Configuration File Format Overview Caption DateFormat Entry Image Name NameSpaces Option Options Parameter Parameters Reader ReaderTypes Request Response Root Template Templates Type Url Value Social TV API Groups List Create Read Update Delete Sources List Create Read Delete... 85

8 10.3 Messages List Create Read Update Delete Group Association (temporary API) Search (temporary API) Scene Design Standard Field Identifiers Scene Design for Trio Scene Presenting a Single Message Scene Presenting Multiple Messages Accessing VDF Payload Data Scene Design for Ticker3D Social TV Plugins Common Properties STV_GroupsReader STV_HttpRecognizer STV_MessagesReader STV_PlaylistsReader STV_ReportsReader STV_SourcesReader STV_SplitAuthor STV_TextHighlight STV_WordCloud Control Plugins Scene Design Examples Troubleshooting Troubleshooting Tips Known Limitations...124

9 1 Introduction Vizrt s Social TV solution provides an easy-to use means to capture social media content from a wide range of Internet services, organize it, and make it available for broadcast. With Social TV, it s easy for presenters to transform a chaotic flood of tweets, Facebook posts, Instagrams and so on into coherent, visually compelling broadcasts. Content can be captured from many sources, including Twitter, Facebook, Flickr, YouTube, Instagram, Picasa, Weibo and Tudou as well as third-party partners such never.no, TrendrrTV and Mass Relevance. In addition, the Feed Streamer tool can easily be configured to capture content from any internet service that publishes feeds in RSS, Atom or most XML- or JSON-based formats. Using the Feed Streamer, users can easily: Define searches to select content related to specific subjects from a variety of social services Moderate the incoming streams of messages Merge approved messages into a single group or multiple groups intended for different outputs Push the various streams to Viz Ticker or Viz Trio for on-air presentation Moderate items from within Viz Trio Merge captured content with Viz scenes Feed Streamer s streamlined, logical user interface puts the journalist in full control of what content is selected, and where it is broadcast. When integrated with the social media monitoring service TrendrrTV, the Social TV solution uses the Data Analytics tool to display analytics data, enabling designers to build interactive scenes that visualize social media activity and trends. The world of social media is a rapidly changing one, with new services appearing almost daily, and significant regional differences - it s impossible for a single static application to meet all possible current and future requirements. The Social TV solution therefore includes several different customization mechanisms: Page 9

10 XML configuration files that let you capture content from almost any XML- or JSONbased feed An HTTP REST API for integrating other applications with the Social TV platform A.NET SDK for creating your own Social TV plugins to meet highly specialized requirements. This section contains information on the following topics: Social TV Components Related Documents Customer Feedback and Suggestions Customer Support Request 1.1 Social TV Components The components of the Social TV solution are: 1. Data Hub: This is where captured social media content is stored ready for broadcast. 2. Social TV Server: This contains the Data Pusher service, which is responsible for bringing the data that the Social TV clients request. 3. Social TV Client: This package consists of three parts, as follows. Feed Streamer for moderating content Data Analytics for generating Viz graphics from social network monitoring data, Page 10

11 The Feed Streamer External Moderation dialog for Viz Trio Social TV Plugins: (STV Plugins) This package contains a set of Viz plugins that can be used to incorporate Social TV content into scene designs. Related Documents Viz Artist User s Guide: Contains information on how to create graphics scenes in Viz Artist. Viz Engine Administrator s Guide: Contains information on how to install the Viz Engine software and supported hardware. Viz Ticker3D User s Guide: How to install, configure and use the Viz Ticker 3D client, and configure the output channels. Viz Trio User s Guide: How to install, configure and use the Viz Trio client, and configure the output channels. Viz Content Pilot User s Guide: How to install, configure and use Viz Content Pilot. Viz Multichannel User s Guide: How to install, configure and use Viz Multichannel. 1.3 Customer Feedback and Suggestions We encourage suggestions and feedback about our products and documentation. To give feedback and, or suggestions, please identify your local Vizrt customer support team at 1. Click on Contact (top of page). 2. The Vizrt office which is nearest to your location will be shown, or select from the list of Vizrt offices. 3. Click on the Contact button for the office you want. 4. Complete the required details in the window that opens. Note: If this message is for Customer Support, and there is a Support Contract in place, then click on the For support requests, please visit our support portal link in the message window. A Vizrt representative will contact you as soon as possible. 1.4 Customer Support Request Support Requests are supported by Vizrt if Customers have a valid Service Agreement in operation. Customers who do not have a Service Agreement and would like to set up a Service Agreement should contact their regional sales representative (see Customer Feedback and Suggestions). When submitting a Support Request relevant and correct information should be given to Vizrt Support, to make sure that Vizrt Support can give the quickest and best solution to your Support Request. This section contains information on the following topics: Before Submitting a Support Request Page 11

12 Submitting a Support Request System Log Files Before Submitting a Support Request Before a Support Request is submitted make sure that you: Read: The relevant User Guide or Guides (see Related Documents). The release notes. and Check: That the system is configured correctly. That you have the specified hardware, tested and recommended versions Always refer to your Vizrt Service Level Agreement document Submitting a Support Request When completing a Support Request, add as much information as possible. This section contains information on the following topics: Content of a Support Request To submit a Support Request Content of a Support Request The report should contain information about these topics: Problem description: Include a good description of what the problem is and how to reproduce it. Remember to use simple English. Screen shots and illustrations: Use to simplify the message. System log files: Send the System Log Files. System dump files: Send the system dump files from the crash (e.g. Viz Artist program folder <Viz install directory>). Note: Check: If the operating system is Windows 7 and up, dump files can be stored at: <userdir>\appdata\local\virtualstore\<viz install directory> (check user rights). System Config file: Send the system config file (e.g. Viz Artist program folder <Viz install directory>). Note: If the operating system is Windows 7 and up, the config file can be stored at: <userdir>\appdata\local\virtualstore\<install_directory> (check user rights). Software configuration: Add exact versions of software (-build) used. Hardware configuration: Add exact versions of hardware used. System setup: Describe differences in the installation, if any, from the recommended setup. Page 12

13 System Network: Add a description of how the network, bandwidth, routers, and switches are configured. Always refer to your Vizrt Service Level Agreement document. To submit a Support Request 1. On the page, click on Support. 2. Click on Report a case. 3. Click on LOG IN to login to the Customer and Partner portal. 4. At the top of the Case Management page, click on Report a Case. 5. In the online form complete the required minimum information (shown by a red asterisk) and click SAVE. 6. In the saved Support Case that opens, complete the various text boxes and upload any required documents, files, etc. (see Content of a Support Request). To track the status of open support tickets, login to the Customer and Partner portal. Add information or communicate about the cases directly with the support team System Log Files Feed Streamer and Data Analytics: C:\ProgramData\Vizrt\Logs\VizSocialize Data Hub: C:\ProgramData\Vizrt\Logs\VizDataHub Page 13

14 Page 14

15 2 Requirements The Social TV solution is extremely flexible and expandable. It can be installed in many different configurations and integrated in many different ways with other Vizrt systems and components. The requirements are therefore to a large degree dependent upon the particular configurations and integrations you select. Bearing that in mind, the following sections describe the basic hardware and software requirements for the Social TV installation packages: Data Hub and Social TV Server Requirements Social TV Client Requirements Social TV Plugin Requirements Upgrading 2.1 Data Hub and Social TV Server Requirements It is recommended that the Data Hub and Social TV Server are installed on the same machine. The machine must have internet access (either direct or via proxy). This section contains information on the following topics: Hardware Software Hardware Minor installations require: Any PC (capable of running Windows 7 or 8) Any network card Major installations also require: SSD drive with at least 0.5 TB available for data, and ~40 GB for a separate OS partition Software For a minor installation: Windows 7 or 8 For a major installation: Windows 2003 Server SP2 or 2008 Server 32/64 bit Microsoft.NET Framework 4 Oracle Java Runtime Environment 1.7 or later Microsoft Visual C Redistributable Package (x86) ( ) In addition, for a major installation: Antivirus SW without endpoint protection No other SW installed alongside the Data Hub and Social TV server Page 15

16 Note: Social TV Server was tested and works best with the Windows 7 64-bit operating system or Windows Server 2008 or newer. 2.2 Social TV Client Requirements The Social TV Client needs to be able to access the internet (either direct or via proxy). The Feed Streamer can be enabled to use a proxy to access the internet, for more information see Feed Streamer Cache and Proxy Settings. Hardware Any PC (capable of running Windows 7 or 8) Any network card Software Windows 7 or 8 Microsoft.NET Framework 4 * IE 8 or above (for Feed Streamer) Media Sequencer 1.22 or above Note: Social TV client was tested and works best with the Windows 7 64-bit operating system but can also be used with Windows 7 32-bit and Windows XP. If using Windows XP one must obtain the latest Windows updates and upgrade to the latest Internet Explorer version. Note: * It is recommended to avoid using Microsoft.NET Framework 4.5 on the Feed Streamer machine as some unexpected UI behavior has been reported when using this version. 2.3 Social TV Plugin Requirements The Social TV Plugins can only be installed on a machine where Viz Artist and/or Viz Engine is already installed. Hardware No additional requirements beyond those imposed by Viz Artist/Viz Engine Software Windows XP machines require MSXML4 and MSXML6 Viz Engine or above DataPool or above Viz Artist 3.0 or above For Viz Trio integration: Viz Trio 2.11 or above* and the relevant Media Sequencer for that Trio version For Viz Ticker integration: Page 16

17 Viz Ticker3D 2.4 and the relevant Media Sequencer 1.21 or (Note that Viz Ticker Client 2.4 cannot work with Media Sequencer 1.23). Or, Viz Ticker3D 2.5 and Media Sequencer 1.23 Note: * Viz Trio 2.11 and earlier do not come with the Feed Streamer External Moderation dialog macro built-in and require additional configuration. See Configuring Viz Trio 2.11 and Earlier. 2.4 Upgrading If upgrading from a previous version, one must uninstall all software components and ensure that their folders are removed from the hard disk. Data is not removed when uninstalling Data Hub. This can be done by removing the data folder C:\Program Files (x86)\apache Software Foundation\CouchDB\var \lib\couchdb. Page 17

18 Page 18

19 3 Installation The Social TV solution consists of separate packages that can be installed in a variety of configurations. A separate installer is supplied for each package, allowing you to install them in whatever configuration best suits your requirements. For more information read the detailed Installation Recommendations. The installation packages supplied with the Social TV solution are: 1. Data Hub: See Installing the Data Hub. 2. Social TV Server: This package contains the Data Pusher service. See Installing the Social TV Server. 3. Social TV Client: This package contains the Feed Streamer, the Data Analytics tool, and the Feed Streamer External Moderation dialog for Viz Trio. It also includes the License File. See Installing the Social TV Client Social TV Plugins: See Installing the Social TV Plugins. Installation Recommendations The packages can be installed in various ways, according to the following recommendations. You can install all the packages on one machine, or install them all on different machines in your network. In practice, however, these are the principles that should govern where you install the various packages: A standard installation consists of one Data Hub installation, one Social TV server installation, and many Social TV client installations 2. All machines on which the Social TV server and client are installed must have an Internet connection, either directly or via proxy. 3. It is required, that the Data Hub and Social TV Server packages are installed on the same machine. 4. You can install the Social TV client package on any machine(s). They do not need to be in the same LAN as the Social TV server, but clients need to be able to access the server through HTTP. 5. You must install the Social TV client package on any machines where you want to use the Viz Trio Feed Streamer External Moderation dialog - even if you don t want to use Feed Streamer or Data Analytics on that machine. 6. The Social TV Plugins must be installed on machines where Viz Artist and/or Viz Engine is installed. Installing the Data Hub The Data Hub is where captured social media content is stored ready for broadcast. The underlying storage system is Apache CouchDB, and a CouchDB instance is included in the installation. As the Data Hub is not a resource intensive process you can install it as a service on a 1 rack unit server or on an existing server. Page 19

20 To install the Data Hub 1. Ensure that all software prerequisites are installed (see Data Hub and Social TV Server Requirements) 2. Start the Data Hub installer (VizDataHub- version.msi) 3. Click Next 4. Choose setup type. Click Typical 5. Viz Data Hub Configuration. Select Install database on this machine, and click Next 6. Click Install to start the installation Window s User Account Control Settings: If notified, click on the hyperlink Change when these notifications appear, and set the level to Never Notify During the installation, CouchDB is also installed. This installation may take some time to complete - just be patient. 7. Click Finish and restart your computer if prompted See Also Configuring Ports 3.3 Installing the Social TV Server The Social TV server installation contains DataPusherService.exe, which brings the data that the Social TV clients request. It is recommended that this package is installed on the same host machine as the Data Hub. To install the Social TV Server 1. Start the Social TV Server installer (VizSocialTVServer- version.msi) 2. Click Next 3. Click Close The Social TV server will be installed in the following location: Windows 64-bit: C:\Program Files \vizrt\viz Feed Streamer Windows 32-bit: C:\Program Files(x86)\vizrt\Viz Feed Streamer See Also Configuring Ports 3.4 Installing the Social TV Client The Social TV client installation contains: The Feed Streamer application for moderating content The Data Analytics application for generating Viz graphics from social network monitoring data The Feed Streamer External Moderation dialog for Viz Trio Page 20

21 To install the Social TV Client 1. Start the Social TV Client installer (VizSocialTVClient- version.msi) 2. Enter the settings in the Setup Configuration dialog: If everything is installed on the same machine, use the following values: Data Hub URI: localhost Ticker MediaSequencer Hostname/IP: localhost Trio MediaSequencer Hostname/IP: localhost If this is not the case then set the values as follows: Data Hub URI: Host name or IP address of the machine on which the Data Hub is installed Ticker MediaSequencer Hostname/IP: Host name or IP address of the machine on which the Viz Ticker3D Media Sequencer is installed Trio MediaSequencer Hostname/IP: Host name or IP address of the machine on which the Viz Trio Media Sequencer is installed If you don t know these settings or get them wrong, you can change them after installation. See Changing the Data Hub URI, Trio MSE or Ticker MSE for details. 3. Click Next 4. Select installation folder. Click Next 5. Optional: Feed Streamer Information, for users of Trio versions before Copy the text provided and create a new script macro. This will allow the external moderation tool to be opened from Trio. See 6. Click Next 7. Click Close The Social TV client will be installed in the following location: Windows 64-bit: C:\Program Files \vizrt\viz Feed Streamer Windows 32-bit: C:\Program Files(x86)\vizrt\Viz Feed Streamer License File The license file (licenses.lic) is placed in the following location during installation: Windows 64-bit: C:\Program Files \vizrt\viz Feed Streamer Windows 32-bit: C:\Program Files(x86)\vizrt\Viz Feed Streamer See Also Configuring Ports Configuring the Feed Streamer 3.5 Installing the Social TV Plugins This package contains a set of Viz plugins that can be used to incorporate Social TV content into scene designs. The plugins help other applications, especially interactive applications, to access the Data Hub. Page 21

22 These plugins are needed for integration with Viz Multichannel, as it is not yet directly integrated with Social TV. Viz Multichannel can then control the plugin, telling it what source or group to read messages from, and the plugin will get the data from Data Hub. The plugins are not required for integration with Viz Trio, Viz Ticker3D or Viz Content Pilot. The Social TV Plugins can only be installed on machines where Viz Artist and/or a Viz Engine is already installed. To install the Social TV Plugins 1. Start the Social TV Plugins installer (SocialTVVizPluginsSetup- version.msi) 2. Select installation folder. Click Next 3. Click Close See Also Social TV Plugins Page 22

23 4 Configuration Configuring the Social TV solution in its simplest form basically requires you to configure the client machine s Data Hub connection. This section contains information on the following topics: Configuring Ports Configuring the Viz Trio Client Configuring the Feed Streamer Configuring Data Analytics Configuring Data Hub Backup and Load Balancing 4.1 Configuring Ports Firewalls should either be turned off, or allow for communication on the following ports: Data Hub requires port 8089 for HTTP The Media Sequencer(s) used for Viz Ticker3D and Viz Trio require: port 8580 for HTTP port 8594 for TCP 4.2 Configuring the Viz Trio Client If the Social TV client package (that is, the Feed Streamer) is installed on the same machine as Viz Trio, then you can display the Feed Streamer External Moderation Dialog within Viz Trio from which it is possible to moderate feeds. Configuration of the Viz Trio client differs slightly between versions. The details are provided below: Configuring Viz Trio 2.12 and Later Configuring Viz Trio 2.11 and Earlier Configuring Viz Trio 2.12 and Later The only configuration required to enable this function is assignment of a keyboard shortcut for displaying the Feed Streamer External Moderation dialog. To assign a keyboard shortcut in Viz Trio 1. Start Viz Trio 2. Click Config (upper left) 3. Under the User Interface section select the Keyboard Shortcuts and Macros option 4. Double-click on gui:show_feed_streamer_moderation in the displayed list of commands 5. Press the key combination you want to assign to the Feed Streamer External Moderation dialog Page 23

24 6. Click OK Configuring Viz Trio 2.11 and Earlier Note: This is only relevant for users of Trio versions 2.11 and earlier. In addition to assigning a keyboard shortcut (see To assign a keyboard shortcut in Viz Trio), a script macro must be created in Trio. The macro allows the external moderation tool to be opened from within Trio. Create a new script macro in Viz Trio and copy the following code into it (changing the path to "Program Files (x86)" if needed): Dim Shell Set shell = CreateObject("WScript.Shell") cmd = """C:\Program Files\Vizrt\Viz Feed Streamer \ExternalTrioModeration.exe""" cmd = cmd & " -template " & TrioCmd("page:getpagetemplate") cmd = cmd & " -show " & """" & TrioCmd("show:get_show_name") & """" shell.run cmd Set shell = Nothing These instructions are also available in the Feed Streamer installation dialog and in the file: C:\Program Files (x86)\vizrt\viz Feed Streamer\readme.rtf If Media Sequencer is not running on the same machine as Trio then a -mse [MSE host or ip] parameter can be added to the calling macro. See Also Installing the Social TV Client Working in Viz Trio 4.3 Configuring the Feed Streamer In many cases, the Feed Streamer requires no configuration. It includes a set of readyconfigured plugins for consuming feeds from a number of the most popular social web services such as Facebook and Twitter. The only situations in which any configuration is required are: You want to set up proxies to be used by the Social TV Client and/or Server, or change the cache location. You want to gather content from a social network that is not covered by the one of the standard plugins, in which case you may want to add your own custom reader configuration You need to change the host name/ip address settings you entered when installing the Feed Streamer. This section contains information on the following topics: Internet Access via Proxy Feed Streamer Cache and Proxy Settings Page 24

25 Adding Custom Reader Configurations Changing the Data Hub URI, Trio MSE or Ticker MSE Internet Access via Proxy Feed Streamer must have access to the internet, either directly or via a proxy. If the system administrators do not want to open the whole client machine to the internet directly, and there is no existing proxy server, then a Squid proxy can be set up on the server. Squid is a very powerful tool and it can be used in a variety of cases. Therefore Vizrt recommends that your Squid proxy be set up by a network professional. Also note that intensive testing of all applications using Data Hub with every setup with Squid is required. To install Squid 1. Download Squid from 2. Install Squid on the Data Hub server 3. Configure it to run as a service using the command line: C:\squid\sbin\squid.exe -i 4. Start Squid via the command line: net start squid Alternatively you can start it from the Windows services list and also configure it to run automatically when the machine starts Feed Streamer Cache and Proxy Settings The Settings window in Feed Streamer is opened by clicking the Settings button at the top of the Feed Streamer window and allows the user to view the following settings: Data Hub (Host and Port): The host and port of the Data Hub. Page 25

26 If the Data Hub connection information is set as part of the program s shortcut properties, then any changes made in the Settings window will not be stored. In this case a message appears, warning that changes will not be stored. To change the Data Hub settings, see Changing the Data Hub URI, Trio MSE or Ticker MSE. If an argument is not provided in the shortcut properties, then the Data Hub host/port are stored in a registry and so changing the setting here can have an effect. Media Folder: The path on a local or network drive where Feed Streamer caches media that has been downloaded (e.g. messages, thumbnails, images, videos). Note that Feed Streamer clients should run under a user with sufficient permissions to write into this folder. Other Viz apps such as Viz Engine, and Viz Trio, which use the media should be able to read from this location. For more information see Media Item Life Cycle. Clients Proxy (Host, Username and Password): Defines the proxy settings to be used by all client machines. These settings are stored in the Data Hub and only need to be set once, and will then apply to all clients connecting to the Data Hub. Pusher Proxy (Host, Username and Password): Defines the proxy settings to be used by the Data Pusher server. Media Item Life Cycle The life cycle of media items is as follows: The media belonging to a message is downloaded when the message is added to a group. The media is verified when a message/group is being sent to Trio/Ticker or used through the Social TV Plugins. This also applies to author thumbnails. Media is removed when a message is deleted. Thumbnails are never removed Adding Custom Reader Configurations The world of social media is rapidly changing, with new services appearing on a regular basis. There are also many services that are popular only in certain countries or regions. For this reason the Feed Streamer includes a generic plugin called Socialize.Plugins.XML_JSON that can be used to consume any XML- or JSON-based feed. In order to create a reader for a particular service, you simply add information about the service and how you want to use it to an XML configuration file called Socialize.Plugins.XML_JSON.xml. Socialize.Plugins.XML_JSON.xml can be found in the plugins folder of your Feed Streamer installation: Windows 64-bit: C:\Program Files \vizrt\viz Feed Streamer\Plugins Windows 32-bit: C:\Program Files(x86)\vizrt\Viz Feed Streamer\Plugins The reader configurations defined in this file are used by the Social TV server as well as by Feed Streamer clients: any changes you make should be made on all Feed Streamer clients and on the server installation. So if you modify this file you must copy it to your Social TV server installation and to all the other Feed Streamer clients that use the same server. Page 26

27 Note: After copying your modified Socialize.Plugins.XML_JSON.xml to all the required installations, you must restart the Data Pusher service. The Data Pusher service is part of the Social TV Server installation. On a server installation, Socialize.Plugins.XML_JSON.xml can be found in the plugins folder of the Social TV server installation: Windows 64-bit: C:\Program Files \vizrt\viz Social TV\Plugins Windows 32-bit: C:\Program Files\vizrt\Viz Social TV\Plugins For information on how to create custom feed readers by editing Socialize.Plugins.XML_JSON.xml, see Defining Custom Readers. See Also Third Party Integrations Changing the Data Hub URI, Trio MSE or Ticker MSE During installation of the Social TV Client package, you can set the following values: Data Hub URI: The URI of the Data Hub Ticker MediaSequencer Hostname/IP: The host name or IP address of the machine on which the Viz Ticker3D Media Sequencer is installed Trio MediaSequencer Hostname/IP: The host name or IP address of the machine on which the Viz Trio Media Sequencer is installed These values are used to set parameters in the startup commands executed by the Feed Streamer desktop shortcut. So if you need to change them all you need to do follow the procedure below. To change Feed Streamer s shortcut properties 1. Right-click on the Feed Streamer shortcut 2. Select Properties... from the displayed menu 3. Edit the command line in the Target field 4. Click OK The parameters you can edit in the Target field are: -DataHubURI: The URI of the Data Hub -TrioMse: The host name or IP address of the machine on which the Viz Trio Media Sequencer is installed -TickerMse: The host name or IP address of the machine on which the Viz Ticker3D Media Sequencer is installed For example: "C:\Program Files (x86)\vizrt\viz Feed Streamer\FeedStreamer.exe" DataHubURI localhost -TrioMse localhost -TickerMse localhost Page 27

28 4.4 Configuring Data Analytics The Data Analytics tool depends on third party monitoring services, currently TrendrrTV. The tool needs to be configured with information about the monitoring service being used. TrendrrTV is a paid service, so you need to specify an authentication key in order for the Data Analytics tool to be able to access your account. To configure the Data Analytics tool 1. Open the configuration file called DataAnalytics.exe.config Windows 64-bit: C:\Program Files \vizrt\viz Feed Streamer Windows 32-bit: C:\Program Files(x86)\vizrt\Viz Feed Streamer 2. Find the setting TrendrrAuth 3. Enter your TrendrrTV authentication key. For example: <setting name="trendrrauth" serializeas="string"> <value>authentication key here</value> </setting> 4. Save the file 5. Start the Data Analytics tool See Also Installing the Social TV Client Working with Data Analytics 4.5 Configuring Data Hub Backup and Load Balancing Users can configure two types of backup for the Data Hub, and should also consider installing up a load balancing and failover solution. Hot Backup Cold Backup Load Balancing and Failover Hot Backup Hot backup is achieved by using a CouchDb replication feature, as described below. For more information see Preparation The following steps describe how to set up replication of the Data Hub between the main and the backup machine. 1. On the backup Data Hub machine, configure CouchDB to accept connections from other machines: 1. Page 28 Start Futon, the CouchDB configuration tool. This is available from the Windows Start Menu under Apache CouchDB.

29 2. 2. From the Tools menu in CouchDB, select Configuration. 3. On the Configuration page, change bind_address parameter the from to On the main Data Hub machine, prepare the replication command: 1. Create a batch file in the "C:\Program Files (x86)\vizrt\viz FeedStreamer" folder. The command must be on a single line. Replace BackupDatahubHost with the host name of the backup Data Hub machine. curl -s -S -X POST _replicate -d "{"""source""":"""viz_data_hub""", """target""":""" """continuous""":true}" -H "Content-Type: application/json" 2. Run the batch file. 3. Add a shortcut to the batch file on the Startup folder so that it will be executed each time the main machine starts. Note: To ensure that up-to-date data is available, the batch file on the main machine also needs to be run each time the backup machine is restarted. During Operation To enable faster failover, the backup machine should be installed with all of the required services. Some services should also be running on the backup machine, as follows: The server machine should be running at all times. Data Pusher service should NOT be running. It should only be started when switching to backup. The data required is retrieved through the replication. Page 29

30 Note: To ensure that up-to-date data is available, the replication command described in the Preparation steps must be run every time the main or backup machine is restarted Cold Backup Cold backup can be achieved by simply copying database files on a regular basis. 1. On the main Data Hub machine, go to: C:\Program Files (x86)\apache Software Foundation\CouchDB\var\lib \couchdb 2. Make a copy of the following: viz_data_hub.couch file.viz_data_hub_design folder On the backup Data Hub machine: 1. Paste the files into the corresponding locations on the backup machine Note: Backup is updated to the last copy time of the files. When using this option neither the Data Hub nor CouchDB services should be running on the backup machine. They should only be started upon failover. For more information see How_to_make_filesystem_backups Load Balancing and Failover It is possible to setup Data Hub to support failover and load balancing. This can easily be achieved by setting up a failover and load balancing cluster. Squid can be used for this purpose. Squid is a very powerful tool and it can be used in a variety of cases. Therefore Vizrt recommends that your Squid proxy and the DNS failover is set up by a network professional. Also note that intensive testing of all applications using Data Hub with every setup with Squid is required. See how To install Squid. Page 30

31 5 Working with Feed Streamer This section describes how to collect content on a particular subject from a range of social platforms and web sites, moderate and organize that content and then forward it for playout to Viz Trio and/or Viz Ticker 3D. This section contains information on the following topics: Feed Streamer Workflow Sources Groups Moderation Destinations 5.1 Feed Streamer Workflow The Feed Streamer is the heart of the Social TV solution. Using it you can: 1. Define sources. Sources are queries that select items about a subjects you are interested in from a social media service such as Twitter or Facebook. 2. Add groups (if required). Define your own Groups in addition to the predefined Approved, Rejected and Favorites groups. This lets you classify approved items according to how they are to be broadcast or which show they are to be broadcast with 3. Moderate the items arriving from the sources you have defined. Moderation means to select the items that you consider suitable for broadcast. The Feed Streamer constantly monitors all the sources you define and generates a stream of items for you to moderate. Your basic choices as a moderator are to: Approve items that you think are suitable for broadcast. Reject items that you think are not suitable for broadcast. Mark items as Favorites. You can mark any items as favorites, even ones you have already approved or rejected - it s simply a way of highlighting them. You Page 31

32 might, for example, want to highlight difficult items so that you can discuss them with someone before making the decision to approve or reject them. Add items to your own custom groups. Adding an item to a user-defined group automatically adds it to the Approved group as well (if it is not already approved) Send content to your Destinations. Send groups of items to air. You can send groups either to Viz Ticker3D tickers or to Viz Trio shows. Sources The Sources panel contains a list of the currently defined sources. This section contains information on the following topics: Add a Source Modify a Source Delete a Source Message Limitation Profanity Filter Add a Source You can add new sources by clicking on the Add button on the right of the panel s title bar. The Add New Source dialog allows you to choose the feed from which you want to pull items and define query parameters that will be used to select items. Page 32

33 Modify a Source The name and settings of each Source can be edited by clicking the Pencil button and editing the desired details. The context menu which is presented by right-clicking on a source name contains options for Edit, Rename and Delete. Sources can also be renamed by selecting a source and pressing F2. Delete a Source Sources can be deleted by selecting them and pressing the Delete key, or by using the Delete option in the context menu on the source name. Note: All items from this source will be deleted, even if they are already approved. Message Limitation Each source has two important parameters which control the how many items each source can have, and how long they will be stored. A regular automatic cleanup removes the messages that are outside these limits. Lifespan (days): Any unmoderated items which have not been changed within this time frame are removed. Changed means that the item has been either moderated, unmoderated, or updated from the external feed. Maximum (items): Any unmoderated items above this number, will be removed chronologically (from oldest to newest), regardless of their age (see previous parameter). Message limitation has two main benefits. 1. It is easier to work with a smaller source, for example, search results are narrower and there is less need for pagination. 2. The data size is limited. If not limited, the system will get slower over time as the server hard disk fills up. These parameters can be changed when you Add a Source or Modify a Source. Page 33

34 Profanity Filter When adding a Twitter or Facebook source, a profanity filter can be enabled. If a message contains unacceptable words, either the entire message can be removed, or the offending words can be hidden and replaced with ***. The list of profanities is stored in the following file: C:\Program Files (x86)\vizrt\viz Feed Streamer\profanity.txt 5.3 Groups This panel contains a list of the groups to which items can be assigned. The list always includes the default groups Approved, Favorites and Rejected, but may also contain groups you have defined yourself. This section contains information on the following topics: Add a Group Modify a Group Delete a Group Add a Group You can add new groups by clicking on the Add (+) button on the right of the panel s title bar. Modify a Group A Group can be renamed by selecting it and pressing F2, or by using the Rename option in the context menu on the group name. Delete a Group Groups can be deleted by selecting them and pressing the Delete key, or by using the Delete option in the context menu on the group name. Page 34

35 Note: Any existing items belonging to this group will be deleted. 5.4 Moderation The Moderation panel contains two lists of items. The precise contents of each list depends on what is currently selected in the Sources or Groups panel, but in general the list on the left contains unmoderated items, while the list on the right contains moderated items. This section contains information on the following topics: Previewing Items Moderation by Source Moderation by Group Moderating Items Filtering Items Copy URI Previewing Items Page 35

36 Media items in the Moderation pane can be clicked to see a preview of the item, for example, an image, video, or link to a web page Moderation by Source If a source is selected in the Sources panel, then in the Moderation panel only items from that source will be listed: unmoderated items on the left and moderated items on the right. Unmoderated items are those that have not been approved, rejected or added to favorites. Both the unmoderated and moderated lists can be filtered, see Filtering Items. Items can be moved between the lists (see Moderating Items) Moderation by Group If a group is selected in the Groups panel, then the Moderation panel displays items from all sources: unmoderated items on the left, and items belonging to the selected group on the right. In this case, the unmoderated list shows items that have not been approved, rejected, added to favorites, or added to a custom group. Both the unmoderated and moderated lists can be filtered, see Filtering Items. Items can be moved between the lists, see Moderating Items Moderating Items Items can be moved between the unmoderated and moderated lists by either dragging them or using the moderation buttons. Dragging multiple items is possible by pressing the CTRL key while selecting several items. Page 36

37 The moderation buttons appear on the right side of an item when the cursor is on the item. You can move several items at once by selecting them and then using a moderation button in any one of the items in your selection. Moderation Buttons - Sources Items in the unmoderated list can be moved to the Rejected, Favorites or Approved lists, by clicking on the buttons next to an item. Items in the moderated list can be moved back to the unmoderated list by clicking on the - button, or can be marked as a Favorite using the star button. Moderation Buttons - Groups Items in the unmoderated list can be moved to the Rejected, Favorites or Approved lists, by clicking on the buttons next to an item. Clicking the +Add button will move the selected item to the right-hand list and thereby add it to the selected group. To add items to a custom group, select that group in the Groups panel and then use the Moderation panel to add items to the group list. To retrieve rejected items, select the Rejected group in the Groups panel and then use the Moderation panel to remove items from the Rejected list. These items will be moved back to the unmoderated list. Items in the moderated list can be moved back to the unmoderated list by clicking on the - button, or can be marked as a Favorite using the star button Filtering Items Items in the lists can be filtered using the controls displayed at the top of the lists. The controls that are displayed vary depending on the source or group selected, and include the following: Tagged As Click the desired tag (group) names. Only items tagged with these groups will be listed. From Source Select the required sources from the drop-down menu. Only items from these sources will be listed. Geolocation Click to filter by geolocation data. Only items which have geolocation data will be listed. In Group Select the required groups from the pull-down menu. Only items in these groups will be listed. Page 37

38 Word Search Enter one or more words you are interested in. Only items containing one or more of the words you enter will be listed Copy URI The Copy URI button is available at the top of each list in the Moderation panel. This button copies the URI of the currently displayed list to the clipboard. The URI includes source, filter and sort criteria. For example: urn:uuid:681c584b dc-8863-b0f4b8b4a321") AND +category:message AND +(category:"geolocation") AND -(category:"urn:uuid:5e9228b8eda8-4c44-99f7-c984ddb78314") AND "happy"*&limit=15&sort=\published<date> 5.5 Destinations This panel contains the destinations to which you can send approved items, that is, Viz Ticker3D tickers and Viz Trio Shows. The TICKER pane contains a queue for each of your tickers. The TRIO pane contains a queue for each of your Trio shows. You can send items to Ticker or Trio by dragging one of your groups on to the Ticker queue or Trio show. Note: You can only send groups of items to a destination, you cannot send individual items. This section contains information on the following topics: Destination - Ticker Destination - Trio Page 38

39 5.5.1 Destination - Ticker Each row in the Ticker pane is organised into two areas. On the left is the ticker queue, and on the right is the ticker carousel. This section contains information on the following topics: Add Groups to a Ticker Remove Groups from a Ticker Ticker System Controls Carousel Minimum Size Add Groups to a Ticker You can send items to Ticker by dragging one of your groups on to the Ticker queue. Drag the group you want to publish onto the required ticker queue and drop it. Note: The items you add to a ticker queue are only queued and will only appear in the broadcast carousel when you press the Add button. Click the ticker queue s Add button carousel. to move the items from the queue to the ticker Note: When a group has been Added to a carousel, then any changes that are made to the contents of the group are directly reflected in the broadcast carousel. That is, the Feed Streamer keeps adding more items on the carousel as new messages are added to the group. Assuming that the system, program and this particular ticker are all switched ON, the items in your selected group are now displayed in the ticker carousel, and a green activity indicator is displayed above the ticker queue. If the ticker carousel was already displaying items, the new group of items replaces the old items. Note: When assigning a group to a carousel Social TV only supports the use of the default templates from each carousel. The Play all Pending Queues button at the top of the list of carousels will play all pending groups at once instead of taking each one individually. Page 39

40 Remove Groups from a Ticker To remove a group from a ticker queue, hold your mouse pointer over the queue and then click on the Delete button that appears. To remove a group from a ticker carousel, click on the carousel s Delete button Note: You do not necessarily need to remove groups in this way: dropping a new group on a ticker queue replaces the old one, and adding a new group to a carousel replaces the old one. Ticker System Controls The TICKER pane contains controls that can control the tickers directly from the Feed Streamer. You can stop and start the ticker system as a whole (Main), stop and start the Program and stop and start individual tickers. Any custom buttons created in the Viz Ticker Wizard will appear in the TICKER pane as well as in the Viz Ticker client, and work in exactly the same way. Note: Social TV only supports the Main Channel. It is possible to filter what carousels are visible in Feed Streamer by using access groups. which are managed from the Ticker application. Note: For more information on setting up a ticker or using access groups, see the Viz Ticker3D User s Guide. Carousel Minimum Size You can set the minimum size of a ticker carousel, so that it is not possible to run it with fewer than a specified number of items. Enter the required minimum number of items in the Minimum items field or set it by clicking on the increment/decrement buttons to the right. If you now drag a group containing fewer than the specified number of items onto the ticker queue, you will see that the Add button changes appearance and is disabled. It will not work until you add sufficient items to the group. If you remove items from a group that is being displayed in a carousel, so that the number of items falls below the specified minimum, then the activity indicator for the carousel will change color from green to amber as a warning. Tip: For more information on setting up a ticker carousel see the Viz Ticker3D User s Guide. Page 40

41 5.5.2 Destination - Trio You can send items to Trio by dragging one of your groups on to the Trio show. First select the required show from the SHOWS drop-down menu, then drag the group you want to publish onto the required Trio template. To add the pages, click the template s Add button. Viz Trio pages are now created from the items currently in the group, and are available for the Viz Trio operator to use. Updates in the group are not automatically translated to new pages. That means that if the group is updated, and corresponding new pages are needed in Trio, then the Add button must be clicked again. You can drop a group on top of an existing group, the new group replaces the old group. To remove a group from a template, hold your mouse pointer over the template and then click on the Delete button that appears. Note: You do not necessarily need to remove groups in this way: dropping a new group on a template replaces the old one. Page 41

42 Page 42

43 6 Working with External Viz Applications This section describes how to use Social TV to send and moderate data for use in other Viz applications, such as Viz Trio, Viz Multichannel and Viz Content Pilot. This section contains information on the following topics: Working in Viz Trio Working with Viz Multichannel Working with Viz Content Pilot 6.1 Working in Viz Trio Social TV includes a Viz Trio plugin that lets you moderate feeds directly in Viz Trio instead of using the stand-alone Feed Streamer application. The plugin provides a Feed Streamer External Moderation Dialog that allows you to directly select entries from the Sources defined in the Feed Streamer, and add them to your Viz Trio playlists. You can open the Feed Streamer External Moderation dialog by pressing the keyboard shortcut that has been associated with it (see Configuring the Viz Trio Client). You can then use it to select social media items that you want to add to a playlist. Workflow 1. Start Viz Trio 2. Open your show 3. Import and read the template that has been created for handling social content 4. Open the Feed Streamer External Moderation Dialog by pressing the associated keyboard key (see Configuring the Viz Trio Client) 5. Filter Items, if required. 6. Moderate Items until the right-hand list contains all the items that you want to add to your playlist. 7. Click the Add buttonto generate pages based on the current template and add them to the Viz Trio page list. The pages are added as a group with the name Feed Streamer. 8. Click OK to close the Feed Streamer External Moderation dialog Page 43

44 6.1.1 Feed Streamer External Moderation Dialog The dialog contains two lists. The list on the left contains unmoderated items, while the list on the right contains moderated items. Moderate Items You can move items between the two lists in various ways: By dragging them from one list to another. You can select several items from a list and drag them together. By clicking on buttons that appear on the right side of an item when you point to it with the cursor. You can move several items at once by selecting them and then using a button in any one of the items in your selection. The buttons to use are: +Add (in the left hand list) moves selected items to the right hand list. - (in the right hand list) moves selected items to the left hand list. The other buttons displayed on the items have the following purposes: [check] Approve the selected items if they are suitable for broadcast. [delete] Reject the selected items if they are not suitable for broadcast. [star] Mark the selected items as favorites. Filter Items You can filter the items in left-hand list of unselected items using the controls displayed at the top of the list: From source Select the required sources from the pull-down menu. Only items from these sources will be listed. Page 44

45 In group Select the required groups from the pull-down menu. Only items in these groups will be listed. Word search Enter one or more words you are interested in. Only items containing one or more of the words you enter will be listed. 6.2 Working with Viz Multichannel When working with Viz Multichannel, the Social TV Plugins are used to automate what comes out of the Data Hub and into pages of Multichannel. Channels The Social TV solution can work with any number of channels. For example, when working with Viz Multichannel, an operator can create a group of mediated postings, and point them at a template for Channel A, then create a new group and point them over to Channel B. 6.3 Working with Viz Content Pilot When working with Viz Content Pilot (VCP), Social TV uses the Feed Browser/Feed Linker features in VCP in order to pass data from Feed Streamer to VCP. Feed Browser and Feed Linker The Feed Linker control can be added to VCP templates in Template Wizard and is used to define a feed source. When a template with a Feed Linker control is used in VCP or the Newsroom ActiveX Component, the Feed Browser window is opened and lists the items from the feed source that was defined in the template. When an entry is selected by the user, the data is mapped to fields in the template. This allows the user to pick an item from a feed and have the corresponding data applied to fields in the template, instead of manually typing in information. The template designer uses scripting to map the feed data to fields in the template. The Feed Linker supports many types of feeds, including those provided by Social TV. Example URI The following URI links to a list of the Sources defined in Feed Streamer: From this list of sources, you can click to view the individual messages in each source. Tip: You can get a specific URI from Feed Streamer by using the Copy URI function. See Also Viz Content Pilot User s Guide - For information on the Feed Browser. Viz Template Wizard User s Guide - For information on the Feed Linker control. Page 45

46 Page 46

47 7 Working with Data Analytics This section describes how to use the Data Analytics tool to generate graphics showing statistics about currently trending topics. This section contains information on the following topics: Overview Data Analytics Reports 7.1 Overview Data Analytics is a tool for generating reports from data supplied by social media monitoring services. You can use it to create a variety of broadcast graphics that visualize statistics about trending topics on social media such as Twitter, Facebook and so on. The current version of Data Analytics generates data supplied by the monitoring service TrendrrTV but may in future support other services too. The data to be collected must be configured using the monitoring service s interface. The Data Analytics tool is used to select what parts of the collected data are to be included in a report, and how the report is to be presented. Supplied data can be used to create graphics that visualize metrics about a selected set of trending topics. The metrics supplied by monitoring services as typically include values such as volume, sentiment, gender, source and so on. A variety of different report types can be generated: pie charts, line graphs, map-based breakdowns of geo-located data and so on. Graphics can be generated by: Interactive applications designed in Viz Artist Viz Content Pilot or Viz Trio (using a report reader plugin that makes data available to Viz DataPool plugins). Page 47

48 7.2 Data Analytics Reports The Data Analytics application is very simple, consisting of a single window composed of four panels: Report Topics Time Save Report You can use this panel to: Create new reports. Enter the required name, dates and topics and click Execute. This saves your report definition (Execute All saves all reports). If a report contains relative dates, then a report for the first reporting period is generated immediately. If it contains absolute dates, then a report will be generated at 24:00 on the To date. Export all your existing reports. Exported reports can be copied to other computers and imported into other instances of the Data Analytics tool. The default export file type is XML. Page 48

49 Import reports. The file you import must be a file that was previously exported from the Data Analytics tool. All the reports in the selected file are imported. Imported reports replace any existing reports with the same name. Delete reports. Select the report and press the Delete key on your keyboard. Topics Displays the list of topics on which your monitoring service is collecting data. You can select which of these topics you want to include in your report. Time You can use this to specify when your report is to be generated, and what period of time it is to cover. You can either define: Absolute dates: Based on the From and To dates, the report is generated once when the period defined is over, that is, 24:00 on the specified To date. Relative dates: This is used together with values for interval length (hourly, daily, weekly, monthly or yearly) and reporting period (the last x hours, days, weeks, months or years). The report is generated at regular intervals, and includes data collected during the reporting period. Note that a report includes absolute and timeline values and is divided by designated market area (DMA) geographical regions. Save You can use the buttons in this panel to save one or all of the defined reports. Once you have saved a report, it is generated as specified. This means that: A report with absolute dates is generated at 24:00 on the specified To date A report with relative dates is generated immediately and then repeated at the specified interval. Page 49

50 Page 50

51 8 Third Party Integrations Social TV has many third party integrations. This section includes information on each third party provider and the specific information that is required in each case. This section contains information on the following topics: Activating an Integration Mass Relevance Never.No Excitem CellJournalist Bloomberg News and Pictures Wochit Applicaster 8.1 Activating an Integration Third party integration files include customer specific information, such as the subscription of the provider, and must be configured inside the corresponding file. Template integration files for each third party provider can be found under: C:\Program Files (x86)\vizrt\viz Feed Streamer\Plugins\Custom Readers To activate a particular integration, the specific file should be moved to: C:\Program Files (x86)\vizrt\viz Feed Streamer\Plugins\ After moving the file you must restart the Feed Streamer service (on the client machine) and the Data Pusher service on the Data Hub (server) machine. 8.2 Mass Relevance Replace the contents of the Value field with the customer s account in the files below: Streams of messages: Integration to Messages Streams is included in the file Socialize.Plugins.XML_JSON.MassRelevanceMessages.xml <Reader Name="Mass Relevance Stream Messages"> <Image>Resources/icons/MassRelevance.png</Image> <Request> <Url> {user}/{stream}.json</url> <Parameters> <Parameter Internal="true"> <Name>{user} </Name> <Caption></Caption> <Type>textbox</Type> Page 51

52 <Value>MyAccount</Value> </Parameter> <Parameter Mandatory="True"> <Name> {stream}</name> <Caption>Stream</Caption> <Type>combobox</Type> <Value></Value> <Options SourceUri=" Root="streams/ stream" Caption="name" Value="name"/> </Parameter> Mass Relevance Stream Statistics Integration to Stream Statistics is included in the file: MassRelevanceStatsTopics.xml <Reader Enabled="True"> <Name>Mass Relevance Stream Statistics</Name> <Group>Mass Relevance</Group> <Image>Resources/icons/MrStreamGraph.png</Image> <Request> <Url> <Name>{account}" class="external-link"> {account}/{0}/meta.xml</url> <Parameters> <Parameter Mandatory="True"> <Name>{account}</Name> <Caption></Caption> <Type>textbox</Type> <Value>MyAccount</Value> </Parameter> <Parameter Mandatory="True" Internal="True"> <Name>{stream} </Name> <Caption>Stream</Caption> <Type>checkcombobox</Type> <Value></Value> <Options SourceUri=" Root="streams/ stream" Caption="name" Value="name"/> </Parameter> Mass Relevance Stream Topics (MetaAPI): Integration to Stream Topics or MetaAPI is included in the file: MassRelevanceStatsTopics.xml <Reader Enabled="True"> <Name>Mass Relevance Stream Topics</Name> <Group>Mass Relevance</Group> <Image>Resources/icons/MrPoll.png</Image> <Request> <Url> {account}/{0}/meta.xml</url> <Parameters> <Parameter Mandatory="True"> Page 52

53 <Name>{account} </Name> <Caption></Caption> <Type>textbox</Type> <Value>MyAccount</Value> </Parameter> <Parameter Mandatory="True" Internal="True"> <Name> {stream}</name> <Caption>Stream</Caption> <Type>checkcombobox</Type> <Value></Value> <Options SourceUri=" Root="streams/ stream" Caption="name" Value="name"/> </Parameter> Facebook Keyword Insights Integration to Facebook Keyword Insights is included in the file: Socialize.Plugins.XML_JSON.MassRelevancKeywordInsights.xml <Reader Name="Mass Relevance Keyword Insights"> <Image>Resources/icons/MassRelevance.png</Image> <Request> <Url> /keyword_insights.json?start={start} {period} &resolution= {resolution} &topics= {topics} &version=2</url> <Parameters> <Parameter Internal="true"> <Name> {user} </Name> <Caption></Caption> <Type>textbox</Type> <Value>MyAccount</Value> </Parameter> <Parameter Mandatory="True"> <Name> {stream} </Name> <Caption>Stream</Caption> <Type>combobox</Type> <Value></Value> <Options SourceUri=" Root="streams/ stream" Caption="name" Value="name"/> </Parameter> Page 53

54 8.3 Never.No For Streams of Messages and Polls, replace the contents of the SourceUri with the customer s URI on each particular reader in the file: Socialize.Plugins.XML_JSON.NeverNo.xml <Group>Various</Group> <Image>Resources/icons/Never.no.png</Image> <Request> <Url> {ComboParameter}</Url> <Parameters> <Parameter Mandatory="True"> <Name>{ComboParameter} </Name> <Caption>Feed Source</Caption> <Type>combobox</Type> <Value></Value> <Options SourceUri=" Root="root/datasource[@subtype= social ]" Caption="@id" Value="@href"/> </Parameter> </Parameters> </Request> 8.4 Excitem Replace the contents of the Value field with the customer s token in both the Feedbacks and Polls reader in the following file: Socialize.Plugins.XML_JSON.Excitem.xml <Parameter> <Name> {token} </Name> <Caption></Caption> <Type>textbox</Type> </Parameter> 8.5 <Value>3dd6776d111cfe55e9bdfffff3c4c333</Value> CellJournalist Replace the contents of the Value field with the customer s partitionid in the following file: Socialize.Plugins.XML_JSON.CellJournalist.xml <Parameter> <Name>PartitionId</Name> <Caption></Caption> <Type>textbox</Type> </Parameter> Page 54 <Value>2ab12a12-4a4a-4567-abcd abcdef</Value>

55 8.6 Bloomberg News and Pictures Replace the contents of the Value field with the customer s customerid in the following file: Socialize.Plugins.XML_JSON.BloombergNewsPics.xml <Parameter> <Name>customerid</Name> <Caption></Caption> <Type>textbox</Type> </Parameter> 8.7 <Value>UcdaEMbOC6789l0G3vR</Value> Wochit Replace the contents of the Value field with the customer s partnerid in the following file: Socialize.Plugins.XML_JSON.Wochit.xml <Name> {partnerid} </Name> <Caption></Caption> <Type>textbox</Type> <Value>e12333dbfecb c3400db517ee48e281234f661f1234c </ Value> </Parameter> 8.8 Applicaster Replace the contents of the Value field with the customer s URL in the following file: Socialize.Plugins.XML_JSON.Applicaster.xml <Parameter> <Name> {url} </Name> <Caption>Feed Url</Caption> <Type>textbox</Type> <Value> ApplicasterPolls.xml</Value> </Paramter> Page 55

56 Page 56

57 9 Defining Custom Readers The world of social media is rapidly changing, with new services appearing on a regular basis. There are also many services that are popular only in certain countries or regions. The Feed Streamer therefore includes a generic plugin called Socialize.Plugins.XML_JSON that you can use create to custom feed readers that can consume any XML- or JSON-based feed. In order to create a reader for a particular service, you simply add information about the service and how you want to use it to an XML configuration file called Socialize.Plugins.XML_JSON.xml, or create it in a file with the name format Socialize.Plugins.XML_JSON.[Your Name].xml. If you make changes to Socialize.Plugins.XML_JSON.xml you need to make sure your changes are copied to all Feed Streamer and Social TV server installations. For details, see Configuring the Feed Streamer. In order to add reader definitions to Socialize.Plugins.XML_JSON.xml you need to be comfortable editing XML files. It also helps to have some basic understanding of XPath (see Socialize.Plugins.XML_JSON.xml has a root element called ReaderTypes, containing a sequence of Reader elements Each Reader element, contains configuration data for a different service. It specifies: How to request a feed from the service What to extract from the returned feed Note: You should be able to create feed readers for the vast majority of social media services using the Socialize.Plugins.XML_JSON plugin. For special cases where this is not possible, it is possible to create your own Feed Streamer plugins using the Social TV SDK. For more information about this, please contact your Vizrt representative. This section contains information on the following topics: How to Define a Custom Reader The Configuration File Format See Also Third Party Integrations 9.1 How to Define a Custom Reader The simplest method of creating a reader is to copy an existing Reader element and edit it. You do, however, need a basic understanding of how a Reader element is structured, and how it is used by the Feed Streamer. A Reader element always contains a Name and Icon element, that determine its appearance in the Feed Reader, but its most important child elements are: Request, which determines the URL that a source sends to request a feed, and Page 57

58 Response, that defines how the returned feed is interpreted and converted into a Feed Streamer item This section contains information on the following topics: Understanding Requests Understanding Responses Including Media Objects in Feed Streamer Atom Entries Including VDF payloads in Feed Streamer Atom Entries Reading JSON Feeds Template Switching Concatenating Selected Nodes Understanding Requests The URL sent by a Feed Streamer source is formed by combining a basic URL template (defined in the Url element) with various parameters specified by the Feed Streamer user when the source is defined. These parameters are defined in Parameter elements, and the Parameter element has a number of child elements that allow you to define the caption used to name it in the Feed Streamer dialog, a default value, a list of allowed values or options and so on. Request parameters can be combined with the URL template in two different ways: They can be appended to the end of the URL template as ordinary HTTP request parameters, or They can replace special placeholders in the URL A parameter that is to replace a placeholder must have a name that is enclosed in braces like this: <Parameter> <Name>{topic}</Name> <Caption>Topic</Caption>... </Parameter> When a source is created in the Feed Streamer, whatever the user specifies in the Topic field will replace all occurrences of {topic} in the URL template. If the Feed Streamer user specifies sport in the Topic field, then the template will be converted to the URL If the parameter name is not enclosed in braces then the template will be converted to the URL An Example Request Page 58

59 The following example shows a Request element that creates and submits a request to Instagram: <Request> <Url> <Parameters> <Parameter> <Name>{tagName}</Name> <Caption>Tag Name</Caption> <Type>textbox</Type> <Value></Value> </Parameter> </Parameters> </Request> The Url contains one placeholder, called {tagname}, and one corresponding parameter with the same name and the caption Tag Name. This parameter therefore appears in the Feed Streamer s Add New Source dialog like this: If the Feed Streamer user enters trees in the Tag Name field, then the URL actually submitted when this source is selected is: and Instagram will return a feed containing pictures tagged #trees Understanding Responses The Feed Streamer uses a similar templating mechanism for converting the response returned from a web service into a stream of Feed Streamer items. Feed Streamer s native format is Atom, an IETF standard syndication format (see html/rfc4287). Each Feed Streamer item is stored in the Data Hub as an Atom entry element. For example: <entry xmlns=" <id>entry </id> <title>what s up?</title> <summary>not much.</summary> <author> <name>my Social Service</name> Page 59

60 </author> </entry> One of a Response element s child elements, therefore is always an Atom entry template. Like the Url template in a Request element, an entry template can contain placeholders enclosed in braces: <entry xmlns=" <id>{guid}</id> <title>{title}</title> <summary>{description}</summary> <author> <name>my Social Service</name> </author> </entry> In this case, however, the values inside the braces are not parameter names, but XPath expressions. XPath (see is a language for selecting nodes from XML documents. So, for example, the id element in an entry template will usually contain an XPath expression that selects the content of some corresponding identifier element in the returned feed document. Simple XPath expressions look very much like file paths and work in much the same way: they describe the path from one node in an XML tree (the root node by default) to another node (or sequence of nodes). The XPath expressions that appear in entry templates don t describe the path all the way from the root of the feed document but from a local root or context set by the Response s Root element. The following example shows how it works. An Example Response Suppose that a service returns an RSS feed that looks something like this: <rss xmlns:media=" <channel>... <item>...</item> <item>...</item> <item>...</item> </channel> </rss> And each item looks something like this: <item> <title>aww</title> <link> <description>some text...</description> <pubdate>sun, 23 Jun :53: </pubDate> <guid>some-long-id</guid> <media:title>aww</media:title> <media:description>some text...</media:description> <media:content url=" width="612" type="image/jpeg" height="612"/> <media:thumbnail url=" width="150" height="150"/> <media:credit role="photographer">a. N. Other</media:credit> </item> Page 60

61 You can then convert the feed to Feed Streamer format with the following Response configuration: <Response> <NameSpaces xmlns:media=" <Root>/rss/channel/item</Root> <entry xmlns=" xmlns:media=" <id>{guid}</id> <title>{title}</title> <summary>{description}</summary> <author> photographer ]}</name> </author> <media:thumbnail <published>{pubdate}</published> </entry> </Response> The Root element contains an XPath expression (/rss/channel/item) that selects all the items in the feed. The entry template is then applied to each of these items, with the item itself providing a local root (or context) for all the XPath expressions in the template. The result is a sequence of valid Feed Streamer items that look like this: <entry xmlns=" xmlns:media=" <id>some-long-id</id> <title>aww</title> <summary>some text...</summary> <author> <name>a. N. Other</name> </author> <media:thumbnail url=" <published>sun, 23 Jun :53: </published> </entry> </Response> Note: As you can see from the entry template shown earlier, some XPath expressions are rather more complicated than simple file paths (such as media:credit[@role= photographer ], for example). There are lots of resources on the Internet for learning XPath: you could start here: xpath/ Including Media Objects in Feed Streamer Atom Entries Many of the feeds returned by social media services include media objects such as images and video clips. These can be selected and included in your Feed Streamer items as described below. Images You can include images using the thumbnail element, which belongs to the search.yahoo.com/mrss/ (Media RSS) namespace. You can see how this is used in An Example Response. In the example, a prefix (media) is declared for the namespace in Page 61

62 the entry element, and a media:thumbnail element is then included as a child of the entry element: <media:thumbnail url="{media:content/@url}"/> The thumbnail element s url attribute contains an XPath expression that selects a URL from an appropriate node in the source feed. Note: The images you reference in this way will be displayed in the Feed Streamer as thumbnails, but you don t necessarily have to pick thumbnail-sized images from the source feed. Whatever image you select is automatically scaled to the required size. Video Clips You can include video clips using an Atom link element. The link element must be included as a child of the entry element and have the following attributes set: rel: Must be set to enclosure type: Must be set to the correct MIME type for the video clip href: Must be set to the URL of the video clip For example: <link rel="enclosure" href="{media:group/media:content/@url}" type="{media:group/media:content/@type}"/> In this example, the href and type values are selected from the source feed using XPath in the usual way Including VDF payloads in Feed Streamer Atom Entries Viz Data Format (VDF) is a proprietary Vizrt data format used for transferring data between different Vizrt components and systems. A data set encoded in VDF is called a VDF payload (as opposed to a VDF model, which can be used to define the structure of the VDF payloads used in a particular application or context). You can find formal reference documentation for VDF on your Data Hub at: A Feed Streamer entry can include a VDF payload in its content element. You can use this payload to define a set of fields that will be used as input to a Viz Artist scene. The following example shows a content element that contains a VDF payload: <content type="application/vnd.vizrt.payload+xml"> <payload xmlns=" <field name="geolocation"> <value>{location/@latitude} {location/@longitude}</value> </field> </payload> </content> Page 62

63 This payload contains a single field called geolocation, but you can define payloads containing any number of fields. The payload is not made visible in any way in the Feed Streamer and will only be used if it is passed into a Viz Artist scene Reading JSON Feeds The Feed Streamer handles JSON feeds by converting them to XML so that they can be read using XPath in exactly the same way as XML feeds. There are a few small structural differences between JSON and XML that are corrected during the conversion if necessary. These differences and the corrections applied are described below. Multiple Root Nodes A JSON document can have more than one root node, whereas an XML file must always have only one root node. The Feed Reader, however, actually does allow the generated XML to have multiple root nodes. If the result of the conversion is a sequence of entry elements like this: <entry> <id>...</id> </entry> <entry> <id>...</id> </entry>... You can access them by setting your Root element as follows: <Root>/entry</Root> Arrays JSON, unlike XML, supports arrays of values. Therefore, when the Feed Reader encounters an array in the JSON data, it converts it to a sequence of elements, and assigns the name of the array to every element in the sequence. For example: { } "data": [ { "id": " _ ", }, { "id": " _ ", } ], gets converted to: <data> <id> _ </id> </data> Page 63

64 <data> <id> _ </id> </data> If the whole JSON feed is an array (that is, the array occurs at the root level), then the predefined string root is used to name the root level elements. The following JSON feed, for example: [ { }, { ] } "id": " _ ", "id": " _ ", would get converted to: <root> <id> _ </id> </root> <root> <id> _ </id> </root> Attributes and Namespaces JSON does not support attributes or namespaces. No correction is required here, it just means that the resulting XML never contains any attributes or namespaces. Example Facebook graph search returns JSON data. The following query: will return something like: { Page 64 "data": [ { "id": " _ ", }, { "id": " _ ", } ],

65 } The Feed Reader converts it to XML that looks like this: <data> <id> _ </id> </data> <data> <id> _ </id> </data> It can therefore be converted to a sequence of Feed Streamer entries with a Response element like this: <Response> <Root>/data</Root> <entry xmlns=" xmlns:media=" <id>{id}</id> </entry> </Response> Template Switching You can define Readers that contain multiple Entry templates, and switch between them depending on the content of the items in the feed. This can be useful for handling feeds that contain entries with variable structures. There are, for example, aggregation services that will monitor multiple social networks for you and generate an aggregated feed. The items in such feeds are not always converted to the same form, so you get a feed that contains differently formatted items. In this case the Feed Reader can test an identifying element or attribute in each item and then select the appropriate template to process it. The following example shows a feed containing a sequence of message elements that have slightly different internal structures and therefore need to be handled differently: <feed> <message type="post"> <id>1234</id> <description>my Post</description> <details>some details</details> <date> t15:30: z</date> </message> <message type="image"> <id>9876</id> <description>a nice image</description> <url> <date> t12:35: z</date> </message> </feed> Each message element has a type attribute that can be used to identify the different message structures. Page 65

66 The following Response contains a corresponding sequence of alternative Template elements for handling the different message types. Each Template element in the sequence has a pair of attributes called NodePath and NodeValue, and a template is only applied to an item if the node selected by NodePath matches the value specified in NodeValue. In this case, if a message element s type attribute contains the value post, then the first of the entry templates shown below is used to process it. If it contains image, then the second entry template is used, and so on. <Response> <Root>/feed/message</Root> <Templates> <Template NodePath="@type" NodeValue="image"> <entry xmlns=" xmlns:media=" <id>{id}</id> <title>{description}</title> <summary/> <author> <name>facebook Image</name> </author> <published>{date}</published> <media:thumbnail url="{url}"/> </entry> </Template> <Template NodePath="@type" NodeValue="post"> <entry xmlns=" xmlns:media=" <id>{id}</id> <title>{description}</title> <summary>{details}</summary> <author> <name>facebook Post</name> </author> <published>{date}</published> </entry> </Template> </Templates> </Response> Concatenating Selected Nodes In general, you want the Xpath expressions in your Entry templates to select single nodes in the source feed items. The Feed Streamer therefore ensures that this is the case by default. If an expression in an entry template returns a sequence of nodes, then the Feed Streamer will only keep the first node in the sequence and discard the rest. Assume, for example, that an incoming feed contains entries with the following structure: <messages> <message> <id>123</id> <date> t15:30: z</date> <infos> <info>aaa</info> <info>bbb</info> Page 66

67 <info>ccc</info> </infos>... </message>... </messages> In this case, the XPath expression in the summary field of the entry template below <Response> <Root>/messages/message</Root> <entry>... <summary>{infos/info}</summary>... </entry> </Response> returns aaabbbccc. The Feed Streamer, however, only keeps the first of the three returned nodes, so the resulting summary element will only contain aaa. If you specifically want to select the content of one of the other info elements, you can do so by specifying the position of the required node using standard XPath syntax (infos/info[2] or infos/info[last()], for example). Occasionally, however, you might actually want to keep the content of all the returned nodes. To do this, enter a single asterisk before the XPath expression. For example: <summary>{*infos/info}</summary> If you do this, then the Feed Streamer will keep all the returned nodes and concatenate them, inserting a pipe character as separator between each node: <summary>aaa bbb ccc</summary> Note: * is also used as a wild card character in XPath. If you need to use an XPath expression in which * is the first character, then you must escape it with a backslash (\) in order to prevent Feed Streamer from treating it as a concatenation instruction. The expression: {*[local-name()="thumbnail" or local-name()="enclosure"]/@url}, for example, must actually be written as {\*[local-name()="thumbnail" or local-name()="enclosure"]/@url} in order to be interpreted correctly. 9.2 The Configuration File Format This section contains a reference description of the Socialize.Plugins.XML_JSON.xml file format. The elements that may appear in the file are described in alphabetical order. The description of each element contains information about: The purpose of the element The element s attributes The element s content model (what other elements and values it may contain) This section contains information on the following topics: Overview Page 67

68 Caption DateFormat Entry Image Name NameSpaces Option Options Parameter Parameters Reader ReaderTypes Request Response Root Template Templates Type Url Value Overview In general, the order of elements is not significant. The following content model diagram, for example: <Request> <Url>...</Url> <Value>...</Parameters> </Request> specifies that a Request element must contain a Url element and a Parameters element. However, these elements do not have to appear in the order shown. The following conventions are used in the content model diagrams: Content Model Conventions Page Represents omitted content? Preceding element(s) or attribute(s) are optional and may appear 0 or 1 time * Preceding element(s) or attribute(s) may appear 0 or more times + Preceding element(s) or attribute(s) may appear 1or more times [] Encloses alternatives Separates alternatives

69 text Text content You will notice that some of the element names in the content model diagrams are links. This is just a convenience to simplify navigation between the diagrams. The descriptions assume that you are familiar with XML syntax rules and terminology. The root element of the Socialize.Plugins.XML_JSON.xml file must be a Caption element Caption This element may appear either as the child of a Reader element or as the child of a Parameter element: As the child of a Parameter element, it specifies the caption to be used when the parameter is displayed in a user interface component. If the Caption element is not specified, then the parameter is not displayed. As the child of an Option element, it specifies the caption to be used when the option is displayed in a user interface component. If the Caption element is not specified, then the option s value is displayed as a caption. Content Model <Caption>text</Caption> DateFormat This element contains a date format specification that the Feed Streamer uses to parse dates in the source feed. If your Entry template contains a published element, for example, and you want to get the content from some date element in the source feed, then you need to: 1. Examine the format of the dates in the source feed 2. Include a DateFormat element containing a format specification that correctly describes the dates The date format specification can either be: The string unix if the dates are standard Unix-style dates in seconds since epoch The string unix_msecs if the dates are standard Unix-style dates in milliseconds since epoch A.NET custom date/time format string as described in en-us/library/8kb3ddd4.aspx Content Model <DateFormat>text</DateFormat> Entry This element is actually a template for generating Atom entry elements. Atom is the format used to represent feed items in the Feed Streamer. The template must therefore be a valid Atom entry element containing Xpath expressions that select data from the Page 69

70 elements in the nodeset selected by the Root element. The XPath expressions must be enclosed in braces ({ and }). When a source is opened in the Feed Streamer, the XML or JSON document specified by the Name element is retrieved. An Atom entry based on this template is then generated for every node that the Root element selects from the retrieved document. The following example shows a very simple entry template that selects data from RSS feed items: <entry xmlns=" <id>{title}</id> <title>{title}</title> <summary>{description}</summary> <author> <name>my RSS Feed</name> </author> </entry> In this example, both the id and title element values are copied from the RSS items title elements, while the summary element values are copied from the RSS items description elements. The author names are all hard-coded to My RSS Feed. Content Model See the Atom specification at Note, however, that the Feed Streamer does not make use of all the elements in an Atom entry. These are the elements that are used if present: author/name contributor/name id title summary content link published The Feed Reader will also make use of a thumbnail element belonging to the Media RSS extension (see if one is included in an entry. If you use this element then you must declare its namespace as well. For an example of how to use it, see Including Media Objects in Feed Streamer Atom Entries. Any other valid Atom elements in the entry will not be rejected, but will not be used by the Feed Streamer either Image The URL of an image to be used as an icon. The image is used in the Feed Streamer to represent the reader and any sources that are based on it. You can either specify a relative URL referencing a local copy of the icon you want (Resources/icons/RSS-icon.png, for example) or an absolute URL referencing an image somewhere on the internet ( thumb/4/43/feed-icon.svg/128px-feed-icon.svg.png, for example). If you specify a relative URL then it is resolved relative to your Feed Streamer installation folder (usually C:\Program Files (x86)\vizrt\viz Feed Streamer). Page 70

71 Content Model <Image>text</Image> Name This element may appear either as the child of a Request element or as the child of a Reader element: As the child of a Reader element, it defines the name of the Reader - for example Flickr or MyCompany Blog. This is the name that appears in the Feed Streamer s source editing dialogs. As the child of a Parameter element, it defines the name of the parameter - for example {keyword} or lang. The parameter it names is used differently depending on whether or not the name is enclosed in braces ({ and }) or not: If the name is enclosed in braces then the parameter s value is used to replace any references to the parameter that appear in the request URL (as, for example, in If the name is not enclosed in braces, then the parameter is simply appended to the request URL ( lang=en_us, for example) Content Model <Name>text</Name> NameSpaces Declares namespace prefixes for use in XPath expressions. If you need to refer to foreign elements in either the Root XPath expression or in any of the XPath expressions in the Entry template, then you must: Declare prefixes for the foreign namespaces in the NameSpaces element Use the prefixes you have declared as necessary in your XPath expressions When writing an entry template, it is important to distinguish between the namespace prefixes used for foreign elements in the entry itself, and the namespace prefixes appearing in XPath expressions, which identify foreign elements in the source feed. For example: <Response> <NameSpaces xmlns:media=" <Root>/rss/channel/item</Root> <entry xmlns=" xmlns:media=" <id>{guid}</id> <title>{title}</title> <summary>{description}</summary> <author> <name>{media:credit[@role= photographer ]}</name> </author> <media:thumbnail url="{media:content/@url}"/> <published>{pubdate}</published> </entry> Page 71

72 </Response> Here the namespace declaration is made twice: once in the entry element, because the entry contains a media:thumbnail element, and once in a NameSpaces element. This declaration is needed because the source feed contains elements from the same namespace and because we need to refer to one of them (media:content) in one of the template s XPath expressions. Content Model <NameSpaces xmlns:text= text + /> Attributes xmlns:text: The text following the colon is the namespace prefix you want to use to reference the namespace, the value of the attribute is the full namespace identifier. You can repeat this attribute to declare several namespaces in one NameSpaces element Option Defines one of a set of allowed opt ions for a parameter. An option consists of a value (the actual parameter value) and a caption (the string used to represent the value in user interface components). Content Model <Option> <Value>...</Value> <Caption>...</Caption>? </Option> Options Specifies a list of options (allowed values) for a parameter. The options are either specified in a sequence of child Option elements or by reference to an XML resource containing the allowed values. Content Model <Options SourceUri="text" Root="text" Caption="text" Value="text"? > <Option>...</Option>* </Options> Attributes The following attributes together define a method of extracting options from an XML document. SourceUri: The URI of an XML document containing the values to be used as options. If you specify a relative URI then it is resolved relative to your Feed Streamer installation folder (usually C:\Program Files (x86)\vizrt\viz Feed Streamer). Page 72

73 Root: An XPath expression selecting a nodeset in the document identified by SourceUri that is to provide the context for the expressions used in Caption and Value. The expression /datasources/datasource, for example, might return a set of datasource elements from which option values and captions can be selected. Value:An XPath expression that selects a value from each node in the nodeset returned by the Root XPath expression. The for example, would selected the url attribute of each node. The selected values are used as option values. Caption:An XPath expression that selects a value from each node in the nodeset returned by the Root XPath expression. The for example, would selected the name attribute of each node. The selected values are used as option captions Parameter Defines a parameter to be included in a request URL. The parameter definition can include the information needed to display it in the Feed Streamer s source editing dialogs. Content Model <Parameter Visible= [true false]? Mandatory= [true false]? Internal= [true false]? > <Name>...</Name> <Caption>...</Caption>? <Type>...</Type>? <Value>...</Value>? </Parameter> Attributes Visible: Specifies whether or not the parameter is to be displayed in the Feed Streamer s source editing dialogs. The default is true. Mandatory: Specifies whether or not the parameter is required. If you specify true, then the Feed Streamer will not allow users to Add a source without specifying a value for the parameter. The default is false. Internal: If set to true then the value of the parameter will not be included in the request URL. The default is false Parameters Contains a sequence of Parameter elements, each of which defines a request parameter. Content Model <Parameters> <Parameter>...</Parameter>* </Parameters> Page 73

74 Reader Contains all the information the Feed Streamer needs to: Request a feed from a particular online service Generate the user interface components that will appear in the Feed Streamer s source editing dialogs for sources based on this reader Locate and extract the required information from the returned feed Convert the extracted information into a sequence of standard Feed Streamer items Content Model <Reader Enabled= [true false]? > <Name>...</Name> <Image>...</Image> <Request>...</Request> <Response>...</Response> </Reader> Attributes Enabled: Specifies whether or not the feed reader is to be enabled. If this attribute is set to false then the reader will not appear in the Feed Streamer s source editing dialogs. The default is true ReaderTypes This is the root element of the Socialize.Plugins.XML_JSON.xml file. It contains a sequence of Reader elements, each of which defines a custom feed reader. Content Model <ReaderTypes> <Reader>...</Reader>* </ReaderTypes> Request Contains all the information the Feed Streamer needs to: Request a feed from a particular online service Generate the user interface components that will appear in the Feed Streamer s source editing dialogs for sources based on this reader Content Model <Request> <Url>...</Url> <Parameters>...</Parameters> </Request> Page 74

75 Response Contains all the information the Feed Streamer needs to extract the required information from a returned feed and convert it to an Atom feed, which is the Feed Streamer s native format. Content Model <Response> <Root>...</Root> <NameSpaces/>? <DateFormat>...</DateFormat>? [ <Entry xmlns=" <Templates>...</Templates> ] </Response> Root An XPath expression that selects a nodeset in the XML or JSON document returned by a Feed Streamer source. The returned nodeset provides the context for all XPath expressions in a Options s entry template. If, for example, the returned document is an RSS feed, you might specify /rss/channel/item to select all the items in the feed. If you need to reference namespaces in your XPath expression, use the Image element to declare prefixes for them. Content Model <Root>text</Root> Template One of a series of Template elements in a Response. Each of the Template element contains a different Entry template. The Feed Reader uses the values specified in the Template elements attributes as conditions for determining which entry template to use for each item in the source feed. For an example of how to use this element, see Template Switching. Content Model <Template NodePath="text" NodeValue="text" > <Entry xmlns=" </Template> Attributes NodePath and NodeValue: If the value returned by the XPath expression in NodePath is equal to NodeValue then this Template s Entry will be used. Page 75

76 Templates Contains a series of Template elements as an alternative to a single Entry template in a Response. For an example of how to use this element, see Template Switching. Content Model <Templates> <Template>...</Template>+ </Templates> Type The type of user interface component to be used to present the parameter in the Feed Streamer s source editing dialogs. The following values are allowed: textbox: A simple text box. combobox: A drop-down combobox offering a list of options. If you specify this value then the parent Reader element should also include an Options element. Content Model <Type>textbox combobox uri checkcombobox checkbox</type> Attributes uri: URI which is escaped to UNC if pointing to a file on a mapped drive. checkcombobox: combo box where each item has a check box next to it. Selected items values will be concatenated, separated by comma. checkbox: check-box control resulting True or False Url The URL used to request a feed from an online service. The URL may include parameter-references enclosed in braces ({ and }). A parameter reference is replaced by the value of the referenced parameter when a source is created in the Feed Streamer. In the URL for example, {keyword} will be replaced by the value of the parameter called {keyword}. The parameters available for use in a Request s Url are defined in a the Request s Parameters element. Content Model <Url>text</Url> Value This element may appear either as the child of a Reader element or as the child of a Parameter element: As the child of a Parameter element, it defines the default value of a parameter. If this element is omitted, then the default value is null. If the parent Parameter Page 76

77 element s Visible attribute is false then any value specified here is effectively a fixed value. As the child of an Option element, it defines the value of the parameter. Content Model <Value>text</Value> Page 77

78 Page 78

79 10 Social TV API This section describes the Social TV solution s API which gives access to the Data Hub. It describes a specific usage of the Data Hub API and is an add-on to the API documentation which is available at <DataHubHost>:8089/doc. Notes: For readability, some parts of server responses are replaced with... POST request examples contain the minimal required information; Optional data might also be applicable. This section contains information on the following topics: Groups Sources Messages Search (temporary API) 10.1 Groups The Social TV API gives access to the Groups data on the Data Hub by providing the following request options: List Create Read Update Delete List Request GET /directory/title/socialize/groups/feed Response <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <id> urn:uuid:5a6266cb-0ac8-4ea7-9efa-e3dc4e817bcc/feed</id> <title>groups</title> <link rel="self" type="application/atom+xml;type=feed" href=" localhost:8089/directory/id/urn:uuid:5a6266cb-0ac8-4ea7-9efae3dc4e817bcc/feed" /> <accept xmlns=" vnd.vizrt.payload+xml</accept> <updated> t11:17: z</updated>... Page 79

80 <entry> <id>urn:uuid:5241f173-af6a-4310-a7f6-0c9d96e5a3e9</id> <title type="text">morning Sports</title> <updated> t13:24:11+02:00</updated>... </entry> <entry> <id>urn:uuid:041133ee-7f79-4fd0-a488-eae9d180cc8a</id> <title type="text">late Night News</title> <updated> t13:24:01+02:00</updated>... </entry>... </feed> Create Request POST /directory/title/socialize/groups/feed Content-Type: application/atom+xml;type=entry <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <title>my Group</title> </entry> Response <entry> <id>urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f</id> <title type="text">my Group</title> <updated> t15:58:23+02:00</updated> <link rel="self" type="application/atom+xml;type=entry" href= " urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f" />... </entry> Read Request GET /directory/id/urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f or GET /directory/title/socialize/groups/my Group Response <entry> <id>urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f</id> <title type="text">my Group</title> <updated> t15:58:23+02:00</updated> Page 80

81 <link rel="self" type="application/atom+xml;type=entry" href= " urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f" /> <content type="application/vnd.vizrt.payload +xml" src=" urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f/media"/>... </entry> Update Request PUT /directory/id/urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f or PUT /directory/title/socialize/groups/my Group Content-Type: application/atom+xml;type=entry <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f</id> <title type="text">my New Group</title> <content type="application/vnd.vizrt.payload +xml" src=" urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f/media" /> </entry> Response <entry> <id>urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f</id> <title type="text">my New Group</title> <updated> t15:58:23+02:00</updated> <link rel="self" type="application/atom+xml;type=entry" href= " urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f" /> <content type="application/vnd.vizrt.payload +xml" src=" urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f/media"/>... </entry> Delete Request DELETE /directory/id/urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f or DELETE /directory/title/socialize/groups/my Group Response No response. Page 81

82 10.2 Sources The Social TV API gives access to the Sources data on the Data Hub by providing the following request options: List Create Read Delete List Request GET /directory/title/socialize/sources/feed Response <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <id> <title>sources</title> <link rel="self" type="application/atom+xml;type=feed" href=" /> <accept xmlns=" +xml;type=feed</accept> <updated> t11:17: z</updated>... <entry> <id>urn:uuid:a2bc050c-bf bfb b1</id> <title Twitter (Json)</title> <updated> t13:17:36+02:00</updated> <author> <name>socialize.plugins.xml_json.twitter (Json)</name> </author> <link rel="via" href=" rpp=100&q=vizrt" /> <link rel="image" href="resources/icons/social-twitter-box-blueicon.png" /> <link rel="self" type="application/atom+xml;type=entry" href=" /> <link rel="down" type="application/atom+xml;type=feed" href=" /> <accept xmlns=" vnd.vizrt.payload+xml</accept> </entry> <entry> <id>urn:uuid:f5661f33-fbe5-457c-8d92-4ba5c6dd45c4</id> <title YouTube</title> <updated> t13:17:36+02:00</updated> Page 82

83 <author> <name>socialize.plugins.rss.youtube</name> </author> <link rel="via" href=" q=vizrt&orderby=relevance&max-results=50" /> <link rel="image" href="resources/icons/google_youtube.png" /> <link rel="self" type="application/atom+xml;type=entry" href=" /> <link rel="down" type="application/atom+xml;type=feed" href=" /> <accept xmlns=" vnd.vizrt.payload+xml</accept> </entry>... </feed> Create When creating a Source, the author field is important, especially if a plugin will be used to read the messages. The author field should be the assembly name of the plugin plus the specific configuration of the plugin that will be used. For more information about configuring plugins see Social TV Plugins. Notes In the following example we use a Socialize.Plugins.RSS plugin with a configuration named Example that tells the system how to read the external source response and translate it into our format. Note that the Accept field must be provided as shown below. Request POST /directory/title/socialize/sources/feed Content-Type: application/atom+xml;type=feed <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <title>my Source</title> <accept xmlns=" <author> <name>socialize.plugins.rss.example</name> </author> <link rel="via" href=" /> </feed> Page 83

84 Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb</id> <title type="text">youtube - Vizrt</title> <updated> t17:03:57+02:00</updated> <author> <name>socialize.plugins.rss.example</name> </author> <link rel="down" type="application/atom+xml;type=feed" href=" urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/feed" /> <link rel="via" href=" /> <content type="application/atom+xml;type=feed" src=" urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/media" /> <accept xmlns=" vnd.vizrt.payload+xml</accept>... </entry> A payload with specific plugin parameter values can be written into the URI of the described-by link of the newly created source, for example: atom:link[@rel=described-by]/@href) This URI format will be such that the base URI is the same as the source URI plus a / meta suffix Read Request GET /directory/id/urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb or GET /directory/title/socialize/sources/my Source Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb</id> <title type="text">my Source</title> <updated> t17:03:57+02:00</updated> <author> <name>socialize.plugins.rss.example</name> </author> <link rel="down" type="application/atom+xml;type=feed" href=" urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/feed" /> <link rel="via" href=" /> <content type="application/atom+xml;type=feed" src=" urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/media" /> Page 84

85 <accept xmlns=" vnd.vizrt.payload+xml</accept>... </entry> Delete Request DELETE /directory/id/urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb or DELETE /directory/title/socialize/sources/youtube - Vizrt Response No response Messages Messages are nested under their source collection. They are created and retrieved through the source entry s down link, which is the URI of the source with the /feed suffix. The Social TV API gives access to individual message data on the Data Hub by providing the following request options: List Create Read Update Delete Group Association (temporary API) List Request GET /directory/id/urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/feed or GET /directory/title/socialize/sources/youtube- Vizrt/feed Response <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <id> Twitter (Json)</title> <link rel="self" type="application/atom+xml;type=feed" href=" localhost:8089/directory/id/urn:uuid:a2bc050c-bf bfb b1/feed" /> Page 85

86 <link rel="via" href=" /> <accept xmlns=" vnd.vizrt.payload+xml</accept> <updated> t11:17: z</updated>... <entry> <id>a568b59c0d9101b00c338d35be65c36c</id> <title type="text">i just uploaded "Showreel (VIZRT) 2012" to Vimeo: <summary type="text"> </summary> <updated> t15:44:29+02:00</updated> <author> <name>arshan khan id:(half_render)</name> </author> <link rel="self" type="application/atom +xml;type=entry" href=" a568b59c0d9101b00c338d35be65c36c" /> <link rel="describedby" type="application/ vnd.vizrt.payload+xml" href=" a568b59c0d9101b00c338d35be65c36c/meta" /> <thumbnail url=" ov6f2ahrrqjr9u5h97hm_normal.jpeg" xmlns=" / > </entry>... </feed> Create Request POST /directory/id/urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/feed or POST /directory/title/socialize/sources/youtube- Vizrt/feed Content-Type: application/atom+xml;type=entry <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <title>my Message</title> <summary>this is a sample message</summary> <author><name>vizrt</name></author> </entry> Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>urn:uuid:e04578a5-cc2f-46a3-92e8-f395e76365d6</id> <title type="text">my Message</title> <summary type="text">this is a sample message</summary> <updated> t17:53:30+02:00</updated> <author> <name>vizrt</name> </author> Page 86

87 <content type="application/vnd.vizrt.payload+xml" src=" localhost:8089/directory/id/urn:uuid:e04578a5-cc2f-46a3-92e8f395e76365d6/media" />... </entry> Request (specifying message id) It is possible to dictate the message id by specifying a Slug http header. Note, however, that the request will fail if that id already exists in the system. POST /directory/id/urn:uuid:1bdebb0e-5b46-4bb5-84ad a26afb/feed or POST /directory/title/socialize/sources/youtube- Vizrt Content-Type: application/atom+xml;type=entry Slug: <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <title>my Message</title> <summary>this is a sample message</summary> <author><name>vizrt</name></author> </entry> Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>12345</id> <title type="text">my Message</title> <summary type="text">this is a sample message</summary> <updated> t17:53:30+02:00</updated> <author> <name>vizrt</name> </author> <content type="application/vnd.vizrt.payload+xml" src=" localhost:8089/directory/id/12345/media" />... </entry> Read Request GET /directory/id/12345 Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>12345</id> <title type="text">my Message</title> <summary type="text">this is a sample message</summary> <updated> t17:53:30+02:00</updated> <author> <name>vizrt</name> Page 87

88 </author> <content type="application/vnd.vizrt.payload+xml" src=" localhost:8089/directory/id/12345/media" />... </entry> Update Request PUT /directory/id/12345 Content-Type: application/atom+xml;type=entry Slug: <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <title>my Updated Message</title> <summary>this is a sample message</summary> <author><name>vizrt</name></author> </entry> Response <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <id>12345</id> <title type="text">my Updated Message</title> <summary type="text">this is a sample message</summary> <updated> t17:53:30+02:00</updated> <author> <name>vizrt</name> </author> <content type="application/vnd.vizrt.payload+xml" src=" localhost:8089/directory/id/12345/media" />... </entry> Delete Request DELETE /directory/id/12345 Response No response Group Association (temporary API) To associate messages with a group, use a category whose term is the atom:id of an existing group. To associate a message with a group, send an update to the message and include the desired category. Page 88

89 To remove the association, update the message, but exclude the category of the group whose association is to be removed. IMPORTANT! The client must include all existing categories in the PUT request in order to maintain all of the associations. Request PUT /directory/id/12345 Content-Type: application/atom+xml;type=entry Slug: <?xml version="1.0" encoding="utf-8"?> <entry xmlns=" <title>my Updated Message</title> <summary>this is a sample message</summary> <author><name>vizrt</name></author> <category term= urn:uuid:f8fb208f-9f1f-462a-95f8-906a105f306f /> </entry> 10.4 Search (temporary API) To index and serve search requests the system uses a Lucene based search engine. The search term syntax (q=...) is that supported by Lucene default query syntax. Indexed Fields The following atom fields are indexed: Title Summary Author Contributor: This normally holds the source type (e.g. Twitter) and allows retrieval of all messages of a given source type. Updated Content Category: Use categories to maintain Group Association (temporary API), thus the category field can be used to retrieve messages of a specific group. Directory: This holds the source of a message. The value is the self link of the source excluding the prefix (e.g. /directory/id/xyz). Formats Data Hub follows the OpenSearch format and a link to the OpenSearch Description Document is available in the service document: /app:workspace/app:service/atom:link[@rel= search] The search template URI is of the format: Page 89

90 q={searchterms}&start={startindex?}&limit={count?}&sort={ commaseparatedfieldsprefixedw Parameters The default field is made from title/summary/author, so the client can search among these by omitting the field prefix. The sort parameter is optional and can contain a comma separated list of any of the indexed fields. Adding a backslash before the field name will tell the server to reverse the order of the field. The start parameter is used for paging and tells the server which result will be the first in the response The limit parameter is the number of results per page. Examples - Get 1. Get all messages that are associated with My Group and sort them by descending updated date: My Group &sort=\updated 2. Get all message with title/summary/author containing vizrt (use default field): 3. Get all messages coming from YouTube: 4. Get all messages associated with My Group or Your Group : category: My Group OR category: Your Group 5. Get all messages of source with self link and that are associated with group Sports : directory: directory/id/xyz AND category: Sports 6. Get all messages, and sort them by category (group) and descending updated date. Note: AND/OR are case sensitive and must be in upper case. Double quotes are required when the value contains space or slash Examples - Response Note: The Server response may contain pagination links if all results do not fit on one page: <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" <title>open Search</title> <id> q=title:news&limit=1&start=2</id> Page 90

91 <updated> t09:45: z</updated> <author> <name>vizrt DataHub</name> </author> <link rel="search" href=" type="application/opensearchdescription+xml" /> <link rel="self" href=" q=title:news&limit=1&start=2" type="application/atom +xml;type=feed" /> <totalresults xmlns=" totalresults> <itemsperpage xmlns=" itemsperpage> <startindex xmlns=" startindex> <Query role="request" searchterms="title:news" startindex="2" count="1" xmlns=" /> <link rel="first" href=" q=title:news&limit=1&include_docs=true&start=1" type="application/atom+xml;type=feed" /> <link rel="last" href=" q=title:news&limit=1&include_docs=true&start=24" type="application/atom+xml;type=feed" /> <link rel="next" href=" q=title:news&limit=1&include_docs=true&start=3" type="application/atom+xml;type=feed" /> <link rel="previous" href=" q=title:news&limit=1&include_docs=true&start=1" type="application/atom+xml;type=feed" /> <entry> <id>7d81fe91cff680eca aa066cd2</id> <title type="text">2008 TTV EVENING NEWS OPENING-by VIZRT</title> <published> t13:57:49+03:00</published> <updated> t13:18:23+02:00</updated> <author> <name>whitebear68</name> </author> <link rel="up" type="application/atom+xml;type=feed" href=" /> <link rel="self" type="application/atom +xml;type=entry" href=" id/7d81fe91cff680eca aa066cd2" />... </entry> </feed> Page 91

92 Page 92

93 11 Scene Design Scene design for Social TV is very similar to standard scene design for Viz Trio, where control plugins are used to manage the transfer of data, and items of data are identified by field identifiers. This section contains information about scene design issues that are specific to Social TV: Standard Field Identifiers Scene Design for Trio Scene Design for Ticker3D Social TV Plugins Control Plugins Scene Design Examples 11.1 Standard Field Identifiers Most of the content of the messages in a Social TV feed can be accessed from the scene designs using the following standard field identifiers: author: The name of the message author: for example, the username of the person who posted the original message in Twitter, Facebook etc. thumbnail: An image associated with the message. Depending on the source of the message, it may either contain a picture of the author or a picture related to the subject of the message. You need to put an image in the container and also set the image location prefix in the image control plugin. title: The message content. summary: Some messages may include additional content in this field. Some RSS and Facebook items, for example, may include content in this field. contributor: The name of the message s source service/network. For example Facebook, Twitter or RSS. image_url: The URL or path to image files that are part of the message. video_url: The URL or path to video files that are part of the message. audio_url: The URL or path to audio files that are part of the message. media_type: The media item (e.g. video or image) if a message contains media. enclosure: This field can contain a URL to an external website, or the URL or path to files that are part of the message but which are NOT image, video or audio files. content: Some messages may contain extra non-standard information in this field, packed into a VDF payload document. For more about this, see Accessing VDF Payload Data. Tip: In general, designers should have a basic knowledge of the feed type they are designing scenes for, in order to decide which are the relevant fields for the desired scene. Page 93

94 11.2 Scene Design for Trio This section contains information about scene design issues that are specific to scene design for Trio: Scene Presenting a Single Message Scene Presenting Multiple Messages Accessing VDF Payload Data Scene Presenting a Single Message A scene presenting a single message can be achieved by using the Standard Field Identifiers. The following shows a scene tree in which the Standard Field Identifiers are used to control the message: The resulting scene looks like this: Scene Presenting Multiple Messages Scenes presenting multiple messages, are managed by adding the ControlListplugin to a parent container, and then inserting a series of subcontainers for the maximum number of actual items that will need to be displayed. You can optionally include a ControlHideonEmpty plugin in each of these subcontainers so that they will only be displayed if they contain data. For detailed information about the Control List and Control Hide On Empty plugins, see the Viz Artist User s Guide. Page 94

95 The following shows a scene tree in which the ControlList plugin is used to control multiple messages: The resulting scene looks like this: Accessing VDF Payload Data Some Social TV items contain non-standard data that does not fit into the standard fields described in Standard Field Identifiers. In such cases, the data is delivered in the content field, packaged inside a VDF payload document. VDF (Viz Data Format) is a proprietary Vizrt data format used for transferring data between different Vizrt components and systems. A data set encoded in VDF is called a VDF payload (as opposed to a VDF model, which can be used to define the structure of the VDF payloads used in a particular application or context). You can find formal reference documentation for VDF on your Data Hub at: In order to access the data in a VDF payload document you need to use a ControlPayload plugin. The ControlPayload plugin unpacks the content of the payload document and makes it available as a normal set of fields to all the children of its container. The field names found in the VDF payload are used as field identifiers. Poll Graphics A typical situation in which you might need to unpack payload data is the design of poll graphics based on data harvested from social media via Social TV. Polls usually consist of questions with multiple choice answers and are usually visualized as pie charts or bar charts. It is therefore desirable to have the data made available in a form that is compatible with the visual data tool plugins. Page 95

96 Poll data might typically arrive in a message s content field, packed in a VDF payload document that looks something like this: <payload xmlns=" <field name="topic"> <value>it s Valentine s Day, how you doin? </value> </field> <field name="option"> <value>hate it! Worst holiday ever Love it! Wish it were every day Thanks for the reminder, need to buy roses</value> </field> <field name="count"> <value> </value> </field> </payload> The payload document contains three fields: topic: the poll s question option: the multiple-choice answers count: the number of results for each answer The scene tree shown below contains a ControlPayload plugin in which the Field Identifier property is set to content. The ControlPayload plugin is therefore able to access the payload document and make the three fields available to the controls in all its subcontainers. Page 96

97 The resulting scene looks like this: 11.3 Scene Design for Ticker3D Social TV scenes for Ticker3D use the same Standard Field Identifiers as Trio. General information about how to design ticker scenes is provided in the Viz Ticker3D User s Guide (see Section 7 - Design Conventions) Social TV Plugins A set of Viz plugins are included with Social TV. These plugins are needed for integration with Viz Multichannel, as it is not yet directly integrated with Social TV. The plugins are not required for integration with Viz Trio, Viz Ticker3D or Viz Content Pilot. Once installed, the plugins appear in Viz Artist in the Container Plugins tab, in a Social TV folder. The Social TV Plugins are designed to work together with the Datapool plugins. The Social TV plugins share some Common Properties, and the unique details for each plugin are described in the subsequent sections: Common Properties STV_GroupsReader STV_HttpRecognizer STV_MessagesReader STV_PlaylistsReader STV_ReportsReader STV_SourcesReader STV_SplitAuthor STV_TextHighlight STV_WordCloud Common Properties Some properties are common to several plugins, so are described in this section. The following plugins are all intended to retrieve various kinds of data from the Data Hub and forward it to the DataPool: Page 97

98 STV_GroupsReader STV_MessagesReader STV_PlaylistsReader STV_SourcesReader These plugins therefore all share the following common properties: Data Hub Host: Host name of your Social TV Data Hub Data Hub Port: Port number on which the Data Hub is listening. This is 8089 by default. DP Field Name: Name of the DataPool field to which retrieved data will be sent. Number of Records Field: The plugin keeps count of the number of records it retrieves from the Data Hub and sends the number to the DataPool along with the records. This property specifies the name of the DataPool variable to which the number of records is written. Post Update Action: An optional sequence of Viz and/or DataPool commands to be executed after the data has been retrieved. If you want to specify more than one command, then you must separate the commands with semicolons (;). In order to distinguish between Viz Commands and DataPool commands you must prefix Viz Commands by 0. For example 0 RENDERER*STAGE START; STV_GroupsReader STV_GroupsReader retrieves all the groups defined in the Feed Streamer and forwards them to a DataPool field array. Properties The STV_GroupsReader plugin has the common properties described in Common Properties plus the following additional properties that allow you to filter the groups by name: Filter by Name: switches filtering on/off Include/Exclude Expression: specifies whether the groups specified in Filter Expression are to be included in the selection or excluded from it. Filter Expression: specifies one or more group names. If more than one group name is specified in this field, they must be separated with commas (,). Page 98

99 Example Here are some groups defined in the Feed Streamer: In order to create a scene that looks like this: The following scene tree must be created in Viz Artist: Page 99

100 STV_HttpRecognizer STV_HTTPRecognizer recognizes and deals with HTTP links in text geometry. Messages from social media networks such as Twitter and Facebook may often contain links to other sites and resources. In many cases such links are not meaningful in a broadcast context. This plugin recognizes such links and can hide them if required. It can also store the link URL in a Data Pool or shared memory variable. Properties The STV_HTTPRecognizer plugin has the following properties: Hide Links: Specifies whether or not discovered links are to be hidden. Variable: The name of the variable in which the URLs of discovered links are to be stored. Example STV_MessagesReader STV_MessagesReader retrieves all the messages defined in the Feed Streamer and forwards them to a DataPool field array. This structure is defined along with a number of other Social TV-related field structures in the configuration file C:\Program Files (x86)\vizrt\viz3\config-socialtv.dp Page 100

101 Each message in the array has the following structure: STV_Message = { string thumbnail; string author; string title; string category; string summary; string href; string contributor; string url; string image_url; string video_url; string audio_url; (??) string media_type; string geolocation; }; Properties The STV_MessagesReader plugin has the common properties described in Common Properties plus the following additional properties: Load Automatically: If On, then messages are automatically retrieved at fixed intervals. An additional property field is displayed in which you can specify the interval (in seconds). If Off, then messages are only retrieved when you click the Load button. Group Name, Source Name, Provider Name: You can limit the selection to messages that: belong to specified groups, or come from specified sources or providers by entering strings in these fields. You can enter several values in each field if required, separated by commas. Free Text Search: You can write a text search string in this field: the plugin will then only retrieve messages that match the string you enter. You can create complex search expressions by combining search strings using AND and OR operators. Page 101

102 Custom Sort: By default, retrieved messages are sorted by publishing date, in reverse order (that is, starting with the most recently published) in this parameter you can change the sort by something else. Messages: All: will bring all the messages Approved: will bring the Approved Messages Rejected: will bring the Reject Messages Favorites: Retrieves only messages belonging to the Favorites group. Show only geolocated messages: Retrieves only messages containing geolocation data. From Message: The message item at which you want to start retrieving messages. Number of Messages: The number of messages to retrieve. Automatic Paging: If set to Off, then the plugin will retrieve messages from the same positions every time. If, for example, From Message is set to 1 and Number of Messages is set to 4, then messages 1-4 will be retrieved every time. If, however, Automatic Paging is set to 1, then the plugin will move on through the messages on each retrieval, selecting 1-4, then 5-8, then 9-12 and so on. Paging Loop: When Automatic Paging is in use, this property determines what happens when all available messages have been retrieved. If it is set to Off, then no more messages are retrieved. If it is set to On, then the plugin returns to the beginning. Show Image Download Parameters: If you set this to On then you can define a default image to be displayed with messages that do not include a thumbnail image. Images Folder: The folder location that images will be downloaded to Read Content, Content Field Name: Set Read Content to On if you want the plugin to read content from a VDF payload embedded in the message. You must then specify the name of the DataPool field to which the payload content is to be written. In order for the plugin to be able to read the payload you must have created a config DP defining the fields required to hold the payload content. Use Proxy: Set to On if you need to use a proxy to download additional images that are not downloaded with the messages. Additional properties are then displayed in which you can set the proxy details. Example In order to create a scene that looks like this: Page 102

103 The following scene tree must be created in Viz Artist: Example with VDF Payload In order to create a scene that makes use of poll data embedded in VDF payloads, like this one: Page 103

104 the following scene tree must be created in Viz Artist: STV_PlaylistsReader STV_PlaylistsReader retrieves the list of pages in a Viz Trio or Viz Content Pilot/MOS playlist and forwards them to a DataPool field array. It is intended for use in interactive applications. This structure is defined along with a number of other Social TV-related field structures in the configuration file C:\Program Files (x86)\vizrt\viz3\config-socialtv.dp The config file includes a base type of STV_MSE_Page. Each page in the array has the following structure: STV_MSE_Page = { string Name; string Description; string Template; string Path; }; The fields contain the following information: Page 104

105 Name: The page name Description: The description in the playlist (the description is defined in the ControlObjectPlugin at the top of the scene template). Template: The description in the template Properties The STV_PlaylistsReader plugin has the following properties: MSE Host: The Media Sequencer host from which playlists are to be retrieved DP Field Name: The name of the DataPool field to which retrieved playlists are to be forwarded Show Name: The name of a Viz Trio show from which the playlist is to be retrieved. If no name is specified then a Content Pilot/MOS playlist is retrieved Page to Take: The index of the page to which a control button action is to be applied (see Control buttons below). Pages are numbered from 0 Playlist: The name of the playlist to retrieve Group Name: The name of the group of pages to retrieve Profile: The name of the profile to use. The profile you specify must have been defined in the Media Sequencer Control Buttons The following control buttons are displayed at the bottom of the properties form: Read Playlist: Reads the playlist Take, Take Out, Continue: Applies the specified action to the page specified with the Page to Take property Example Page 105

106 By creating the following scene tree in Viz Artist: Page 106

107 Then using a Viz Trio playlist as follows: You can produce the following scene: STV_ReportsReader Page 107

108 The STV_ReportsReader plugin retrieves information gathered by the Data Analytics application (see Working with Data Analytics). It forwards the retrieved data to a DataPool object called STV_Report. An STV_Report object contains an array of STV_Project objects. An STV_Project object contains arrays of STV_Category and STV_GeoLocation objects. An STV_Category object contains an array of STV_Parameter objects. DataPool Object Definitions STV_Report, STV_Project, STV_Category, STV_GeoLocation and STV_Parameter are defined along with a number of other Social TV-related field structures in the configuration file C:\Program Files (x86)\vizrt\viz3\config-socialtv.dp The definitions are as follows: STV_Report STV_Report = { string Title; string StartTime; string EndTime; string NumValues; STV_Project Totals; string Timeline; // t1 t2 t3... string NumProjects; string MinValue; string MaxValue; string LocsMinValue; string LocsMaxValue; STV_Project Projects[30]; string #T1_YEAR; string #T1_MONTH; string #T1_MONTHNAME; string #T1_DAY; string #T1_WEEKDAY; string #T1_DAYNAME; string #T1_HOUR; string #T1_HOUR_SHORT; string #T1_FHOUR; string #T1_HOURNAME; string #T1_AMPM; string #T2_YEAR; string #T2_MONTH; string #T2_MONTHNAME; string #T2_DAY; string #T2_WEEKDAY; string #T2_DAYNAME; string #T2_HOUR; string #T2_HOUR_SHORT; string #T2_FHOUR; string #T2_HOURNAME; string #T2_AMPM; string #T3_YEAR; string #T3_MONTH; Page 108

109 }; string string string string string string string string string #T3_MONTHNAME; #T3_DAY; #T3_WEEKDAY; #T3_DAYNAME; #T3_HOUR; #T3_HOUR_SHORT; #T3_FHOUR; #T3_HOURNAME; #T3_AMPM; STV_Project STV_Project = { string Title; string Total; string Percentage; string NumValues; string MinValue; string MaxValue; string Values; string NumCategories; STV_Category Categories[10]; string NumLocations; string LocsMinValue; string LocsMaxValue; STV_GeoLocation Locations[30]; }; STV_Category STV_Category = { string Title; // Source, Sentiment, Gender,... string Total; string Percentage; string NumParams; STV_Parameter Parameters[10]; }; STV_GeoLocation STV_GeoLocation = { string Title; string Total; string Percentage; string Long; string Lat; string DMACode; string NumValues; string Values; string #misc_1; }; STV_Parameter STV_Parameter = { string Title; string Total; Page 109

110 }; string string string string string Percentage; NumValues; MinValue; MaxValue; Values; // val1 val2 val3... Properties The STV_ReportsReader plugin has the common properties described in Common Properties plus a variable number of additional properties. The Mode property determines exactly what information is retrieved from the Data Analytics application, and which additional properties are displayed. If Mode is set to List of Reports as in the above, then STV_ReportsReader retrieves all the reports gathered by the Data Analytics application and forwards them to an array of STV_Report DataPool objects. No additional properties are displayed. If Mode is set to Detailed Report then STV_ReportsReader retrieves a single report. The following additional property is displayed: Report Name: The name of the report to retrieve. If Mode is set to Detailed Project then STV_ReportsReader retrieves a single project. The following additional properties are displayed: Report Name: The name of the report containing the required project. Project Name: The name of the project to retrieve. If Mode is set to Category then STV_ReportsReader retrieves one category of information from a single project. The following additional properties are shown: Report Name: The name of the report containing the required project. Project Name: The name of the project from which information is to be retrieved. Category Name: The name of the information category to be retrieved - one of Gender, Sentiment or Sources. If Mode is set to Location then STV_ReportsReader retrieves information associated with a specific location from a single project. The following additional properties are displayed: Report Name: The name of the report containing the required project. Project Name: The name of the project from which information is to be retrieved. Page 110

111 Location Code: In the US, A Designated Market Area (DMA) code. A DMA code is a 3-digit number that represents a group of counties covered by a specific group of television broadcasters. The code 501, for example, represents New York. Example (Single Project) The following diagram shows the scene tree required in Viz Artist to generate a scene from a single project. The resulting scene is as follows: Example (Single report) The following image shows a scene generated from a single report. It shows data from two projects and a set of totals based on one of those projects: Page 111

112 Such a scene can be generated from the following scene tree in Viz Artist: Example (Single Category) The following image shows the scene tree required in Viz Artist to generate a scene from a single category in a project. The image includes a preview of the resulting scene. Page 112

113 The resulting scene is as follows: Example (All categories from single project) The following image shows a scene generated from a single project. It shows data from all of the categories in the project: Page 113

114 Such a scene can be generated from the following scene tree in Viz Artist: Example (All categories from all projects) Page 114

115 The following image shows a scene generated from all the projects in a report. It shows data from all of the categories in all of the projects: Such a scene can be generated from the following scene tree in Viz Artist: STV_SourcesReader STV_SourcesReader retrieves all the sources defined in the Feed Streamer and forwards them to a DataPool field array. Page 115

116 Properties The STV_SourcesReader plugin has the common properties described in Common Properties plus the following additional properties: Filter by lets you choose the kind of filtering you require: Title: Filter by the name given to the source when it was created in the Feed Streamer Provider: Filter by the name of the source type on which the source is based, such as Facebook or Flickr Include/Exclude Expression specifies whether sources that match a search string are to be included in the selection or excluded from it. Filter Expression specifies one or more text strings to use as filters. If more than one string is specified in this field, they must be separated with commas (,). Example Here are some sources defined in the Feed Streamer: In order to create a scene that looks like this: Page 116

117 The following scene tree must be created in Viz Artist: STV_SplitAuthor When STV_SplitAuthor is placed on a text container, the plugin recognizes character from the text and lets you hide either the user ID or User Name of the author. Note: You must send text to the author property of this plugin using the ControlParameter. An example Viz Artist scene is shown below: Page 117

118 The resulting scene, with user details hidden, is as follows: STV_TextHighlight When STV_TextHighlight is placed on a text container, the plugin recognizes certain characters and lets you change the color of any word containing that character (for example: Note: You must send text to the text property of this plugin using the ControlParameter. An example Viz Artist scene is shown below: The resulting scene, with important information highlighted, is as follows: STV_WordCloud STV_WordCloud reads an xml file and lets you create word cloud visualizations. The plugin is compatible with Never.no s XML format but it can read any xml in the following structure: Page 118

119 <datasource> <entry> <field name="text">angela merkel</field> <field name="count">967</field> </entry>... </datasource> An example xml is provided when installing Social TV Plugins and can be found in C: \Program Files (x86)\vizrt\common\socialtv Control Plugins For general information about how to use control plugins in scene designs, see Adding Control Plugins in the Viz Trio User s Guide. You can also refer to the descriptions and examples of creating scene designs for Social TV Plugins in the Viz Artist User s Guide Scene Design Examples An archive of scene design examples is provided when installing the Social TV Plugins, and can be found in C:\Program Files (x86)\vizrt\common\socialtv. Page 119

120 Page 120

121 12 Troubleshooting This section contains typical troubleshooting questions and answers that may arise while installing, configuring or using the Social TV solution. If you do not find answers to your issues, please contact your local Vizrt representative and submit a Customer Support Request. This section contains information on the following topics: Troubleshooting Tips Known Limitations 12.1 Troubleshooting Tips Data Hub installation freezes for a long time Cannot connect to Data Hub, or can t see data in Feed Streamer Feed Streamer is slow or unsuccessful when fetching images New messages stop arriving No messages ever arrived When using STV_MessagesReader plugin, I cannot see the thumbnails Feed Streamer and Data Hub run, and can define sources, but no messages arrive. I modified my plugin config file and cannot get new messages or add sources Search on Moderation Panel using special characters doesn t return expected results Cannot create Trio pages Data Hub service crashed and no space left on C drive Database file getting large and filling hard drive space Cannot add Twitter account (the IE window doesn t appear) Data Hub installation freezes for a long time It is a known issue that the installation of Data Hub freezes (see image below). Please be patient and it should eventually complete (after about 10 minutes). Cannot connect to Data Hub, or can t see data in Feed Streamer 1. Verify that the Data Hub host name or IP is properly configured in the applications. 2. In your web browser try to access the page: search?q=socialize Page 121