Bolt bridge reference

Updated at November 13th, 2024

+ More

Table of Contents

Active bridges addToCalendar authorisationStatus cancelEditionDownload clearForwardTouchesWithin deleteEdition forwardTouchesWithin issueAuthorisationStatus getConsentData getConsentStatus localizableDateTimeString localizableQuantityString localizableRelativeTimeString localizableString localizableStringWithPriceSubstitutions logInfo openAudioPlayer openImageGallery openEdition openBrowser paywallState playAudio pushUserIdentifier readStories rewriteURLUsingExternalDomainSettings savedStories setSaved shareStory shouldViewWidget startEditionDownload storeGet storeSet stories timelineIsReady timeline timelines timelineInfo timelinesInfo trackAnalyticsEvent updateTime viewArticle webviewInfo Deprecated bridges baseUrl localeInfo

Bolt web content can interact with the native app using a well-defined javascript bridge. For an overview of how this works, see the Pugpig HTML Bridge Overview. This document is a reference for the available bridge calls.

The bridge calls may refer to issues, timelines or editions. They're all the same thing. For example, issueAuthorisationStatus, timelineInfo and cancelEditionDownload are all acting on a collection of stories (sometimes called “articles”).

Some calls can only be made in a certain context, as defined by the availability field in the bridge description. This is usually because the call only makes sense in that context. The possible contexts are:

within a timeline (a view that shows a list of stories/articles)
within a storefront (a view that shows a list of editions/issues/timelines)
within article content
within an arbitrary web view (e.g. a web view launched from settings)

For example, the stories bridge only makes sense within a timeline because it's listing the stories within that timeline.

Active bridges

addToCalendar

Add a story to the device calendar. The story must be a calendar event (i.e. at a minimum have a “startDate” and "endDate")

Parameter(s)	Story
Availability	iOS timeline only, Android all bridge-enabled views
Updates	n/a
Result	n/a

authorisationStatus

Active user authorisation state.

Parameter(s)	n/a
Availability	all bridge-enabled views
Updates	on feed access changes
Result	{ "state" : "inactive" \| "active", "message": "last subscription response message", "eligibleForStorePurchase", true \| false, "eligibleForSubscriptionUpgrade", true \| false, "store": "googleplay" \| "amazon" \| "itunes", "userInfo" : { userInfo response key-value pairs } }

cancelEditionDownload

Cancel in-progress download of an edition.

Parameter(s)	{ "editionId" : String }
Availability	all bridge-enabled views except timeline
Updates	n/a
Result	n/a

clearForwardTouchesWithin

Remove all touch-intercept areas. See forwardTouchesWithin.

Parameter(s)	n/a
Availability	Android timeline and content only
Updates	n/a
Result	n/a

deleteEdition

Delete an edition.

Parameter(s)	{ "editionId" : String }
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

forwardTouchesWithin

Intercept any touches within a given area, and forward them to the web view. This is an Android-only interface, and it is required because unlike iOS. Android touches are natively consumed before the web view can process them. Use this to implement areas within an Android web view that can respond to advanced touch events (like a carousel, or puzzles).

Parameter(s)	[ {"x" : Integer, "y": Integer, "w": Integer, "h": Integer} ] You can have as many areas in a single call as you need. Calling forwardTouchesWithin adds the areas to the existing areas. Clear all areas with the clearForwardTouchesWithin bridge.
Availability	Android timeline and content only
Updates	n/a
Result	n/a

issueAuthorisationStatus

Check if issues are authorised for active user.

Parameter(s)	JSON string array of feed identifiers
Availability	all bridge-enabled views
Updates	on feed access changes
Result	{ "feedId1" : true \| false, "feedId2": true \| false, … }

getConsentData

Consent information for a consent key. The available keys are consent-provider defined and opaque to the app. So far (for OneTrust and Google UMP) they are the values allowed by the TCF v2.2 spec.

Parameter(s)	key: String
Availability	all bridge-enabled views
Updates	n/a
Result	Consent value for given key, may be blank.

getConsentStatus

Current user consent status. This only determines if the user has been asked for consent or not. It is not related to any actual consents selected. So “obtained” does not mean the user has given consent to any particular activity, it just means the user has been asked. Use the getConsentData bridge to determine what consents have been allowed.

Parameter(s)	n/a
Availability	all bridge-enabled views
Updates	n/a
Result	"no_provider" \| "unknown" \| "not_required" \| "required" \| "obtained"

localizableDateTimeString

Retrieve localised date/time string

Parameter(s)	{ "stringId": String, "datetime" : String} datetime must be an ISO-8601 format string
Availability	all bridge-enabled views
Updates	n/a
Result	Date or time string with given id using the specified ISO-8601 format. The string can contain {{date}}, {{time}} or {{datetime}} and the appropriate format will be substituted.

localizableQuantityString

Retrieve localised quantity string

Parameter(s)	{ "stringId": String, "quantity" : Integer, "params" : [ String ] } params is optional
Availability	all bridge-enabled views
Updates	n/a
Result	string with given id, parameters substituted as appropriate. Quantity will be substituted according to cardinality rules.

localizableRelativeTimeString

Retrieve localised relative time string

Parameter(s)	{ "stringId": String, "datetime" : String, "params" : [ String ] } params is optional datetime must be an ISO-8601 format string
Availability	all bridge-enabled views
Updates	n/a
Result	Relative time string with given id using the specified ISO-8601 format, parameters substituted as appropriate. If the time is within 60 seconds, it uses the string key relative_date_now for the value. If the time is within 7 days, it's a relatively formatted value. If it's within the current year, it's a short day month string. Otherwise. it's a full absolute date.

localizableString

Retrieve localised string

Parameter(s)	{ "stringId": String, "params" : [ String ] } params is optional
Availability	all bridge-enabled views
Updates	n/a
Result	string with given id, with parameters substituted as appropriate

localizableStringWithPriceSubstitutions

Retrieve localised string with price substitution.

Parameter(s)	{ "stringId": String }
Availability	all bridge-enabled views
Updates	n/a
Result	String with given id with price values substituted. TODO: more detail

logInfo

Write an informational message to app log file

Parameter(s)	message: String
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

openAudioPlayer

Get persisted string value by key.

Parameter(s)	key: String
Availability	all bridge-enabled views
Updates	n/a
Result	stored string value associated with the key, or null if key does not exist

openImageGallery

Open an image gallery.

Parameter(s)	{ "initialImage" : Integer, "images" : [ { "src": "relative-src-url", "caption" : "caption-message", "copyright": "copyright-message" } ] } initialImage is the index to display first. You can have as many images as you like. All text fields must be defined, but can be blank.
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

openEdition

Open an edition.

Parameter(s)	{ "editionId" : String, "partition" : String, "autoDownload" : Bool, "skipTimeline": Bool } partition is optional autoDownload is optional and defaults to true. skipTimeline is optional and defaults to false.
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

openBrowser

Open a link in the internal app browser. This is intended to be used if you know that a link that would normally be processed by the app should directly open a browser. Usually this would be a link on an alias domain that you want to go directly to your website. Standard parameter injection will be applied to the opened URL.

Do not use this for internal URLs, like commands. This is unsupported, and the behaviour is undefined.

Parameter(s)	url: String. MUST be fully qualified.
Availability	all bridge-enabled views, Bolt 4.3 or later.
Updates	n/a
Result	n/a

paywallState

Retrieve paywall state for currently viewed content.

Parameter(s)	n/a
Availability	content only
Updates	authorisation changes
Result	{ "paywall": "standard" \| "metered" \| "none" }

playAudio

Play (or perform an action) on an audio track.

Parameter(s)	{ "url" : String, "story" : Story, "action" : String, "metadata": Dictionary } action can be “openActions”, “playNow”, “playNext”, “addToQueue” the metadata dictionary can contain an “image” field
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

pushUserIdentifier

Get push provider-specific identifier. This is generally used for API calls to the push provider.

Parameter(s)	n/a
Availability	all bridge-enabled views
Updates	n/a
Result	push provider's unique user identifier, or a blank string if unavailable

readStories

Retrieve all read stories. The app automatically marks a story as read based on platform-specific rules.

Parameter(s)	n/a
Availability	all bridge-enabled views (except iOS timeline prior to Bolt 4.1.x)
Updates	read stories updated
Result	{ "readStories" : [ [ feed-id, story-id ], [ feed-id, story-id ], … ] }

rewriteURLUsingExternalDomainSettings

Rewrite a given URL to include any required external query parameters

Parameter(s)	url: String
Availability	all bridge-enabled views
Updates	n/a
Result	rewritten url string

savedStories

Retrieve all saved stories.

Parameter(s)	n/a
Availability	all bridge-enabled views (except iOS timeline prior to Bolt 4.1.x)
Updates	saved stories updated
Result	{ "savedStories" : [ [feed-id, story-id], [feed-id, story-id], … ] }

setSaved

Save or remove a story to or from saved stories.

Parameter(s)	{ "story": Story, "saved" : Bool } iOS saves the story is “saved” is true and removes it if “saved” is false. Android removes the story if it is already saved, otherwise adds it.
Availability	all bridge-enabled views (except iOS timeline prior to Bolt 4.1.x)
Updates	n/a
Result	n/a

Share a story using native share sheet.

Parameter(s)	Story
Availability	iOS timeline only, Android all bridge-enabled views
Updates	n/a
Result	n/a

shouldViewWidget

Determine is a widget is currently authorised to display or activate. If it is not, present any configured paywall. With a metered paywall a locked widget can show if the meter is not exhausted. With a standard paywall, a locked widget should not show.

Parameter(s)	Story
Availability	timeline only
Updates	n/a
Result	true if widget should be shown/activated

startEditionDownload

Start download of an edition.

Parameter(s)	{ "editionId" : String }
Availability	all bridge-enabled views (except iOS timeline prior to Bolt 4.1.x)
Updates	n/a
Result	n/a

storeGet

Get persisted string value by key. The storeGet / storeSet bridges are an alternative to using local storage. Although they are less powerful than local storage they store data in a way will be included in a device backup.

Parameter(s)	key: String
Availability	all bridge-enabled views
Updates	n/a
Result	stored string value associated with the key, or null if key does not exist

storeSet

Persist a string value with a given key. The storeGet / storeSet bridges are an alternative to using local storage. Although they are less powerful than local storage they store data in a way will be included in a device backup.

Parameter(s)	{ "key": String, "value": String } Specify null as the value to delete the string associated with the key.
Availability	all bridge-enabled views
Updates	on feed access changes
Result	n/a

stories

Retrieve all stories for the timeline view making the call.

Parameter(s)	n/a
Availability	timeline only
Updates	timeline changed
Result	{ "stories" : [ JSON-Array of stories ] }

timelineIsReady

Timeline views must call this when they are ready to display a timeline; a loading mask is displayed until then.

Parameter(s)	{ "version" : "current-timeline-version" }
Availability	timeline only
Updates	n/a
Result	n/a

timeline

Status of a specific timeline.

Parameter(s)	{ "editionId": String }
Availability	iOS all bridge-enabled views except timeline, Android all bridge-enabled views
Updates	timeline changed (including download progress updates)
Result	{ "ref": { feed-entry }, "progress" : 0-1, "state": "downloading" \| "idle", "downloadError": "current-download-error" } downloadError is optional (there may be no error)

timelines

Get all visible timelines, applying an optional filter.

Parameter(s)	{ [String:String] } The dictionary filters the list of timelines. A filter matches an entry if, for every pair in the filter: the key exists in the entry the string values match, or if the value for that key is a string array, one of those string values match The timelines automatically filter out any entry that should not be visible for a given authorisation state (e.g. "private" timelines are filtered if you are not signed in).
Availability	storefront only
Updates	n/a
Result	JSON array of timeline entries

timelineInfo

Timeline information for timeline view calling the bridge.

Parameter(s)	n/a
Availability	timeline only
Updates	timeline changes
Result	{ "timelineType", "SavedTimeline" \| "Timeline", "themeURL" : [ array-of-additional-CSS-files ], "sourceURL" : "timeline-source-url", "feedReference": { full-feed-reference-from-feed }, "metadata": { global-metadata-from-feed }, "debugLogs": true \| false } The source URL is in the /t/feedid format.

timelinesInfo

Get all visible timelines.

Parameter(s)	n/a
Availability	storefront only
Updates	n/a
Result	{ tab parameters, "baseUrl" : “base url string” } The "css" array is rewritten to be config-relative

trackAnalyticsEvent

Track an analytics event

Parameter(s)	{ "name" : String, "category" : String, "param" : String, "dimensions" : { [String:String] }} category and param are optional
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

updateTime

Time content was last refreshed in timeline view calling the bridge.

Parameter(s)	n/a
Availability	timelines only
Updates	Timeline refresh
Result	{ "dateTime", "time-last-updated", "lastCheckedDateTime" : "time-last-checked" } The times are in UTC, in format yyyy-MM-ddTHH:mm:ssZ

viewArticle

Open article associated with story. This will open within the context of the timeline that makes the call.

Parameter(s)	Story
Availability	timeline only
Updates	n/a
Result	n/a

webviewInfo

General configuration for active web view

Parameter(s)	n/a
Availability	all bridge-enabled views
Updates	n/a
Result	{ "baseUrl": url, "localeInfo" : { "locale": language-region, "direction": "ltr" \| "rtl" }, "collectionSets": ["set1", "set2", ...] } Locale language is the ISO 639-1 language code, region is the ISO 3166-1 region code. It's legal for there to be no region.

Deprecated bridges

baseUrl

Deprecated. Use webviewInfo bridge.

Current web view base url.

Parameter(s)	n/a
Availability	all bridge-enabled views
Updates	n/a
Result	n/a

localeInfo