Skip to content

URL Context

URL Context is a way to pass specific context elements to a dashboard or a widget as part of the link to that dashboard or widget. Context is built around "context buses", which are labeled groups of context that can be . 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.

Context Types

There are different context types that can be used by specific widgets in a dashboard. Each widget will take the context that it can handle from the overall context being set.

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

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.
  • 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={"type":"CHANNEL","id":"red","input":{"filters":[{"type":"channel","channelId":43495},{"type":"channel","channelId":3584}]}}
  • entityIds: A JSON-list of entity IDs
    • e.g. for "Apple + Google": context={"type":"CHANNEL","input":{"filters":[{"type":"stageItem","stageItem":{"type":"entity","value":246,"options":{"relevance":"high"}}}]},"id":"red","mergeType":"replace"}&context={"type": "CHANNEL","input": {"filters": {"type":"stageItem","stageItem": {"type": "entity","value": 245,"options": {"relevance": "high"}}}]}
  • stages: A JSON-list of channel stage objects
    • e.g. for "NOT twitter or microsoft": ?context={"type":"CHANNEL","id":"red","input":{"filters":[{"type":"stageItem","stageItem":{"type":"entity","value":244,"options":{"relevance":"low"}},"excluded":true}]}}
    • 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 start and end 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={"type":"DATE","id":"red","input":{"start":1642604400000,"end":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={"type":"DATE","id":"red","input":{"start":"2022-01-19T15:00:00.000Z","end":"2022-01-20T15:00:00.000Z"}}

Relative Date Context can be used when you would like to set the date based on today and 'x' number of days in the past. The potential date ranges are:

Parameter Relative Time Span
day last 24 hours
three_days last three days
week last seven days
month last 30 days
quarter last 90 days
number last number of milliseconds

Set the context using the relativeSpan parameter using the DATE type as follows: ?context={"type":"DATE","id":"red","mergeType":"replace","input":{"relativeSpan":"three_days"}}

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={"type":"ARTICLE","id":"red","input":{"articleIds":[1947253443]}}

NOTE: This context is currently sparingly-used.

Keyword Context

You can use a Keyword or phrase as a context object as follows: ?context={"type":"CHANNEL","input":{"filters":[{"type":"stageItem","stageItem":{"type":"keyword","value":"\"Apple Computer\""}}]},"id":"red","mergeType":"replace"}

This will look up the phrase Apple Computer. Not the use of the escape character \ in order to include the quotes around the phrase.

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:

(old context version)

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: September 11, 2024
Back to top