Liveblog Reference

embedLiveblog

Signature:

Tickaroo.embedLiveblog(options)

Values for the options object:

  • options.clientId (ObjectID) The Client ID provided by Tickaroo

  • options.container (String or Element) The element to use as a container (css selector or element) (required)

  • options.id (ObjectId) ID of the ticker to load (required)

  • options.eventId (String) if you want to focus on an important event in this ticker, add the event id here and the ticker will navigate to this event on load. (optional)

  • options.showHighlights (Boolean) Will display a list of game highlights underneath the scoreboard, (eg.: a goal scorer list in a soccer game) (default: true)

  • options.reverseEvents (Boolean) Will reverse the order of the events (oldest on the top of the livecast) (default: false)

  • options.limit (Integer) The number of items to fetch on initial load (default: 15, range: 2-1000)

  • options.loadMoreLimit (Integer) The number of items to fetch on load more (default: value of limit, range: 2-1000)

  • options.handleScoreboard (‘auto’ or ‘off’) determines if the display of a scoreboard should be handled automatically (default: ‘auto’)

  • options.handleMedia (‘auto’, ‘rooverlay’, ‘inline’, ‘shadowbox’ or ‘off’) determines how media objects should be handled. If set to ‘rooverlay’ Tickaroo’s own slideshow gallery will be used. If set to inline, will not open a slideshow and play videos inline. If set to shadowbox, assumes shadowbox slideshow library has been loaded and initialized. If set to ‘auto’, ‘rooverlay’ will be used, but might change non-breaking in the future. (default: ‘auto’)

  • options.refreshInterval (Number) the time (in milliseconds) interval to refresh and update the ticker (default: 20000)

  • options.handleRefresh (‘auto’, ‘notify’ or ‘off’) automatically refresh the content of the ticker. If set to “notify”, updates are fetched and sent to the trackingCallback but are not rendered automatically. You have to call “updateWithPendingItems” to apply the updates. (default: ‘auto’)

  • options.showEventMeta (‘reporter’ or ‘off’) enables reporter or ticker info in event (default: ‘reporter’)

  • options.coalesceRepeatedMeta (Boolean) decides wether to show or hide the reporter’s information in successive messages for a grouping effect. (default: true) (‘showEventMeta’ must be set to either ‘reporter’ for this setting to have any effect) (hidden elements take this css class ‘ticker-event-item-meta-reporter-hidden’)

  • options.showEventSharing (Boolean) enables ticker events to have sharing buttons that will be visible on mouseover (default:false)

  • options.showLineup (Boolean) will display line up below the event rows (default: true)

  • options.trackingCallback (function(id, reason, type, foundContent)) will be triggered whenever the ticker made a request for content.

  • options.customAdCallback (function(id, callback(html, usePostscribe))) will be called to fill custom ad spots (default: undefined) This feature must be Enabled by Tickaroo

  • options.showWebEmbeds (‘show’, ‘off’, ‘consent_handling’, ‘custom_consent_handling’) enables web embeds in ticker events (default: ‘show’)

  • options.webEmbedConsentCallback (function(platform)) will be triggered whenever the ticker wants to render an embeded content. Can be used to control the embed rendering.

  • options.webEmbedConsentUpdateCallback (function(platform, consent)) will be triggered whenever the user clicks the embed consent element. Can be used to control the embed rendering.

  • options.itemDOMPostProcessor (function(domItem)) will be triggered once for every feed item. Can be used to manipulate the HTML before it is inserted.

  • options.imageWidth (Number) image width (px) in events (default: 480)

  • options.locale (String or undefined) force-set the embed language and skip language detection. Unless a value is set, a language will be detected from the browser settings. Currently, we support ‘en’, ‘en-GB’ and ‘de’ for English (US), English (GB) and German. (default: undefined)

  • options.rooverlay (Object) Will provide the options object to the Rooverlay slideshow library, read more about the library options here.

  • options.showTeamIcons (Boolean) Will display team icons in the scoreboard if provided (team-image) (default: false)

  • options.showNavigation (‘off’ or ‘event_tag_filter’) Will display the specified navigation (default: ‘off’)

  • options.whitelistedScoreboardAffiliations (Array or String) Hides the scoreboard meta information above the team names and shows only the mentioned types of affiliations. E.g.: ["Tik::ApiModel::LiveRef"] will only show the sportstype of the ticker “Basketball”. (default: undefined)

  • options.blacklistedScoreboardAffiliations (Array or String) Same as whitelistedScoreboardAffiliations but reverse. If whitelistedScoreboardAffiliations is set, blacklistedScoreboardAffiliations option is ignored. (default: undefined)

Return Value: EmbeddedTicker Object

The Tracking Callback

The tracking callback will be triggered whenever the ticker made a request for content. It has the following signature:

function trackingCallback(id, reason, type, foundContent)
  • id String The ID of the ticker
  • reason (one of [‘init’, ‘auto’, ‘user’]): Indicates why the request was made.
  • type (one of [‘init’, ‘refresh’, ‘more’, ‘update-pending’, ‘slideshow’]): Indicates what kind of content the request was for
  • foundContent (Integer): Number of items loaded

You can use this information to do analytics tracking or update the user interface if you decide to manage things yourself. Both reason and type will be set to init on startup as the ticker will load initial entries.

The Custom Ad Callback

This feature must be Enabled by Tickaroo

The custom ad callback will be triggered whenever the ticker wants to render an Ad that can be filled by the customer. It has the following signature:

function customAdCallback(id, callback);
  • id (String): The ID of the ticker
  • callback (function): A callback to call with the ad information

Tickaroo recognizes, that some ad frameworks need asynchronous processing to fill an add, therefore the function gets a callback that can be called asynchronously. It’s signature is:

function callback(html, usePostscribe)
  • html (String): The HTML to render in the ad spot
  • usePostscribe (Boolean): Wheather to use postscribe to insert the HTML (set to true if you use a legacy framework that needs document.write)

The showWebEmbeds Option

To comply with data protection restrictions you can set showWebEmbeds to consent_handling or custom_consent_handling and web embeds are rendered with a preview unless the user gives consent. You have this options:

  • show: each web embed is rendered
  • off: no web embed is rendered
  • consent_handling: the user has to give consent if web embeds are going to be rendered or just a preview, the user decision is stored in local storage
  • custom_consent_handling: web embeds are rendered depending on the callback result of ‘webEmbedConsentCallback’

You can find some examples in the FAQ.

This only works if showWebEmbeds is set to custom_consent_handling.

The emded consent callback will be triggered whenever an web embed content is getting rendered. It has the following signature:

function webEmbedConsentCallback(platform)
  • platform (one of [‘Facebook’, ‘Twitter’, ‘Gfycat’, ‘Opta’]): Indicates the embed provider.

You can control if the custom embed is rendered or a preview that has no data protection impacts.

Example:

function (platform) {
  if(platform == 'Twitter') {
    return true;
  }
  else {
    return false;
  }
}

This only works if showWebEmbeds is set to custom_consent_handling.

If this callback is set a custom element is rendered under each web embed, to give the user the option to give or deny consent. When this element is clicked by the user the callback gets triggered. After that all web embeds are rerendered. It has the following signature:

function webEmbedConsentCallback(platform, consent)
  • platform (one of [‘Facebook’, ‘Twitter’, ‘Gfycat’, ‘Opta’]): Indicates the embed provider.
  • consent: true or false

Example:

function (platform, consent) {
  // store the consent for platform
}

The EmbeddedTicker Object

This object allows you can manually control some behavior of the ticker. It provides the following methods:

  • refresh(): Checks for new content and updates the ticker. Will only check and not update if handleRefresh=’notify’. The tracking callback will be called with reason=user, type=refresh.
  • pendingItemsCount: Number of items loaded but not shown in the ticker right now. (Only valid with handleRefresh=’notify’)
  • updateWithPendingItems(): Updates the ticker with all pending items. (Only valid with handleRefresh=’notify’). Will call the tracking callback with reason=user, type=update-pending, foundContent=Number of updated items
  • destroy(): Removes the content from the DOM and does some cleanup. The ticker is unusable afterwards.
  • overrideOptions(options): will destroy the current liveblog, then immediately create a similar one with the same options plus any passed options in the options param. returns the new ticker object
_tik(function() {
  window.myticker = Tickaroo.embedLiveblog({
    container: "#tickaroo-liveblog",
    id: '58171cb9af5f1e8cb50a693a',
    reverseEvents: false
  });
});
    
/*
somewhere else in your code (like a button click event)
IMPORTANT: please make sure to override any global variables 
containing the old ticker to avoid having 2 or more tickers in memory!
*/
window.myticker = window.myticker.overrideOptions({
  refreshInterval: 1000, // make the ticker updates faster
  reverseEvents: true    // and reverse it
});