Skip to content

Widget 2.0 Context

The new widgets have an entirely new system for context that is rebuilt from the ground-up. The new system is built around "context busses", which are labelled groups of context that any widget can read and modify at-will. When a context bus updates, any of the widgets subscribed to that bus will immediately adjust to the new context. Similarly, a widget that can modify the context will usually modify the one it is subscribed to by default (although this is not a hard rule).

Context Types

The contexts are broken into several distinct types, and a widget may utilize whichever ones it needs to display data.

Although several contexts can be applied to the same bus, a widget does not necessarily utilize all of them. For example, there is an "articles" context that most widgets do not support. If a context is loaded with options that a widget does not support, the widget will simply ignore them.

Currently, the way to tell which contexts a widget utilizes is to inspect the "context bar" on the widget:

  • A widget that utilizes the "channel context" will show active filters, and include a language picker globe and "+" to toggle the entity searcher.
  • A widget that utilizes the "date context" will include a date-picker.
  • A widget that utilizes the "articles" context will show the active article name.

Preloading Context

Many of the new widget pages can also have their context preloaded via the URL, similar to how the old widgets can accept parameters from the URL via widget parameters. The system for preloading context should behave identically regardless of whether there are one or many widgets on a page. Every page that supports preloading does so by reading context fields from the URL parameters.

You might see URL parameters referred to as search parameters, query strings, or just URL parameters. You can read more about them in-general here.

The context parameter

Each context is a JavaScript Object Notation (JSON) object with multiple fields.

The only required field is bus, which specifies which bus will be loaded for that particular context parameter. For example, the following is used to adjust the "red" bus:

https://apollo.fintechstudios.com/widget/news?context={"bus":"red"}
  • Whitespace will be ignored, so ?context={"bus":"red"} is identical to ?context={ "bus": "red" }.
  • The bus must currently be one of the following: red, orange, yellow, green, blue, indigo, violet. This cannot yet be changed.
  • The default bus a widget subscribes to is currently "red". This also cannot yet be changed.

Channel Context

Several fields are available to preload a channel context. Each of them is optional. All parameters that are provided will be joined together with a boolean "AND".

Be default, the provided channel context will be joined with the user's language preferences with a boolean "AND". This currently cannot be overridden.

They are as follows:

  • channelIds: A JSON-list of channel IDs
    • e.g. for "Market Newsletter + Virtual Reality" ?context={ "bus": "red", "channelIds": [43495, 3584] }
  • entityIds: A JSON-list of entity IDs
    • e.g. for "Apple + Google": ?context={ "bus": "red", "entityIds": [245, 246] }
  • stages: A JSON-list of channel stage objects
    • e.g. for "NOT twitter or microsoft": ?context={ "bus": "red", "stages": [{ "not": true, "entities" :[{ "type": "entity", "value": 244, "options": { "relevance": "low" } }, { "type": "entity", "value": 14832 }] }] }
    • This one has the worst UX, and will just show as "Stage" in the context bar

Date Context

A date-range can be preloaded in the date context using the startDate and endDate parameters. Both fields are optional. When not provided, a default will be provided by the widget, which will vary widget-by-widget.

Each parameter can be passed a number, which will be interpreted as a Unix epoch timestamp.

  • This is the preferred way, as it will provide the most consistent results.
  • A convenient tool to getting a timestamp is available at unixtime.org.
  • Keep in mind that all timestamps operate on the Coordinated Universal Time (UTC) timezone.
  • For example, for 10 AM EST 1/19/22 to 10 AM EST 1/20/22, one would provide ?context={ "bus": "red", "startDate": 1642604400000, "endDate": 1642690800000 }

Alternatively, each parameter can also be passed a string, and it will be interpreted by the JavaScript Date.parse() method.

  • This should be avoided, as it can produce inconsistent results based on browser + timezone of the user (particularly if an ambiguous string is provided).
  • The most consistent approach uses simplified ISO 8601 formatted dates
  • For example, for 10 AM EST 1/19/22 to 10 AM EST 1/20/22, one would provide ?context={ "bus": "red", "startDate": "2022-01-19T15:00:00.000Z", "endDate": "2022-01-20T15:00:00.000Z" }

Article Context

Articles can be preloaded into the article context using the articleIds field. It accepts a JSON-list of article IDs. For example, ?context={ "bus": "red", "articleIds": [1321611704] }

NOTE: This context is currently sparingly-used.

Preloading Multiple Context Busses

Multiple context busses can be preloaded by adding multiple context parameters to the URL. For example, the following preloads the red AND blue bus:

https://apollo.fintechstudios.com/widget/news?context={ "bus": "red", "channelIds": [43495, 3584] }&context={ "bus": "blue", "entityIds": [245, 246] }

Home PowerIntell.AI™ Apollo Pro® RegLens®

Last update: March 9, 2022
Back to top