Feeds Client JavaScript reference
The JavaScript client for Pusher Feeds. If you aren't already here, you can find the source on Github.
For more information on the Feeds service, see here. For full documentation, see here
Installation
yarn:
$ yarn add pusher-feeds-client
In a script tag:
Instantiate a Feeds object
The constructor Feeds
takes a single options object with the following
properties.
-
instanceLocator
: [required] get this from your dashboard -
authEndpiont
: [optional] the endpoint to use to request tokens for access to private feeds -
authData
: [optional] data to pass to the auth endpoint along with token requests -
logLevel
: [optional] a number between 1 and 5, corresponding toVERBOSE
,DEBUG
,INFO
,WARNING
, andERROR
respectively. 1 logs everything, 5 only logs errors etc. -
logger
: [optional] a cutom logger implementation, must conform to the following interface
Example
const feeds = instanceLocator: your_instance_locator ;
Get a reference to a feed
Given the feeds
object above, feeds.feed
Returns a reference to a
particular feed, from which subscriptions and history queries can then be made.
Takes a feedId
.
Example
const yourFeed = feeds;
Subscribe to a feed
Given a feed object such as yourFeed
above, use yourFeed.subscribe
to
receive new items published to yourFeed
. A subscription can be resumed from
some previously seen item by providing a lastItemId
, or can be initiated
with a fixed number of previously seen items by providing the previousItems
option. Private
feeds require "READ"
permission. Takes a single options object with the following properties.
-
onItem
: [required] callback to handle items, takes each item as a parameter -
lastItemId
: [optional] retrieve every item published afterlastItemId
, and then live items as they are published -
previousItems
: [optional] if this parameter is provided, then the most recentpreviousItems
items will be retrieved, followed by live items as they are published (lastItemId
takes precedence if both are provided) -
onOpen
: [optional] callback to fire when the subscription is open, takes an object containingnext_cursor
andremaining
as a parameter -
onEnd
: [optional] callback to fire when the subscription ends normally -
onError
: [optional] callback to fire when the subscription is closed with error
Returns a subscription
object with an unsubscribe
method.
Items are passed to the onItem
callback with the following format
id: item_id // this corresponds to the published item_id created: timestamp data: item_data
Example
const subscription = feed; // Unsubscribe after 5 seconds;
Pagination
Given a feed object such as yourFeed
above, use yourFeed.paginate
to query a
feed for pages of previously published items. Items are returned in descending
order of item ID. Private
feeds require "READ"
permission. Takes a single (optional) options object with the following
properties.
-
cursor
: [optional] the ID of the first item in the page – if not provided, retrieves the most recently published items -
limit
: [optional] limit the number of items to retrieve
Returns a promise resolving with a single object of the following format.
items: ... id: item_id created: timestamp data: item_data ... next_cursor: next_cursor remaining: remaining
next_cursor
should be used as the cursor
parameter to get the next page of
results. It will be null
if there are no more results. remaining
is a count
of the number of unseen items further back in the history of the feed.
Example
// Get a page containing the last 25 items (but don’t subscribe)yourFeed;
List feeds for an instance
Given a feeds object feeds
, feeds.list
lists non-empty feeds. This method
requires "READ"
permission on the path "feeds"
, see the auth
docs.
Takes a single options object with the following properties.
-
prefix
: [optional] only return those feeds that start with this string -
limit
: [optional] return at most this many matches
Subscribe to the Firehose
Given a feeds object feeds
, feeds.firehose
subscribes to the firehose for
this instance to see all events and subscriptions on a single subscription.
This method requires "READ"
permission on the path "firehose/items"
– see
auth docs. Takes a
single options object with the following properties
-
onPublish
: callback to fire when a Publish event is received -
onSubscribe
: callback to fire when a Subscribe event is received -
onUnsubscribe
: callback to fire when an Unsubscribe event is received -
onOpen
: [optional] callback to fire when the subscription is open -
onEnd
: [optional] callback to fire when the subscription ends normally -
onError
: [optional] callback to fire when the subscription is closed with error
At least one of onPublish
, onSubscribe
, and onUnsubscribe
must be
provided.