import Listening from '@npr/npr-one-sdk/controller/listening.js'

public class | source

Listening

Encapsulates all of the logic for communication with the Listening Service in the NPR One API.

Note that consumers should not be accessing this class directly but should instead use the provided pass-through functions in the main NprOneSDK class.

Example:

Implementing a rudimentary 'Explore' view

const nprOneSDK = new NprOneSDK();
nprOneSDK.config = { ... };
nprOneSDK.getRecommendationsFromChannel('recommended')
    .then((recommendations) => {
        // in a real app, the user would select a piece; here we've simulated them selecting one at index 3
        const selectedRecommendationId = recommendations[3].attributes.uid;
        return nprOneSDK.queueRecommendationFromChannel('recommended', selectedRecommendationId);
     })
    .then(() => {
        nprOneSDK.getRecommendation(); // proceed to play the recommendation
    });

Test:

Listening

Constructor Summary

Public Constructor
public	constructor Initializes the controller class with private variables needed later on.

Method Summary

Public Methods
public	getHistory(): Promise<Array<Recommendation>> Retrieves a user's history as an array of recommendation objects.
public	getRecommendation(uid: string, channel: string): Promise<Recommendation> Get a recommendation from NPR.
public	getRecommendationsFromChannel(channel: string): Promise<Array<Recommendation>> Makes a new API call to get a list of recommendations.
public	getUpcomingFlowRecommendations(channel: string): Promise<Array<Recommendation>> this method is experimental. Return possible recommendations that may come next in the flow.
public	queueRecommendationFromChannel(channel: string, uid: string): Recommendation This synchronous method is intended to be used alongside getRecommendationsFromChannel.
public	resetFlow(): Promise Resets the current flow for the user.
public	resumeFlowFromRecommendation(json: Object): Recommendation Given a valid JSON recommendation object, the flow will advance as normal from this recommendation.

Public Constructors

public constructor source

Initializes the controller class with private variables needed later on.

Public Methods

public getHistory(): Promise<Array<Recommendation>> source

Retrieves a user's history as an array of recommendation objects.

Return:

Promise<Array<Recommendation>>

Test:

Listening getHistory

public getRecommendation(uid: string, channel: string): Promise<Recommendation> source

Get a recommendation from NPR.

Caution: the resulting recommendation may have been returned previously and must be checked to ensure the same recommendation is not played twice.

Params:

Name	Type	Attribute	Description
uid	string	optional default: ''	Optional; a UID for a specific recommendation to play. In 99% of use cases, this is not needed.
channel	string	optional default: 'npr'	Optional; a channel to pull the recommendation from; the main flow channel of `npr` is used as the default. In 99% of use cases, this does not need to be changed.

Return:

Promise<Recommendation>

Test:

Listening getRecommendation

public getRecommendationsFromChannel(channel: string): Promise<Array<Recommendation>> source

Makes a new API call to get a list of recommendations. This is NOT intended for regular piece-by-piece consumption; this function is designed to be used for consumers implementing e.g. the Explore view from the NPR One apps, where the client displays a list or grid of content, and the user can select a piece to listen to next. It is hard-coded to use the "recommended" channel by default, although other channels can be used also. That said, you should really never use this with channel "npr" (the main flow channel), as this is not how that content is intended to be consumed.

Params:

Name	Type	Attribute	Description
channel	string	optional default: 'recommended'	A non-flow (i.e. non-`npr`) channel to retrieve a list of recommendations from

Return:

Promise<Array<Recommendation>>

Test:

Listening getRecommendationsFromChannel

public getUpcomingFlowRecommendations(channel: string): Promise<Array<Recommendation>> source

this method is experimental.

Return possible recommendations that may come next in the flow. Useful for pre-caching audio and displaying upcoming recommendations.

Recommendations returned are not guaranteed to always come next in the flow.

Params:

Name	Type	Attribute	Description
channel	string	optional default: 'npr'	A channel to pull the next recommendation from

Return:

Promise<Array<Recommendation>>

Test:

Listening getUpcomingFlowRecommendations

public queueRecommendationFromChannel(channel: string, uid: string): Recommendation source

This synchronous method is intended to be used alongside getRecommendationsFromChannel. Once you have a list of recommendations from a channel and an audio story has been selected to play, this method ensures that the correct ratings (actions) will be sent and the flow of audio will continue appropriately with the necessary API calls. If the recommendation with the given UID can be found, it is delivered immediately to be played. Importantly, this function also returns the selected recommendation on a subsequent call to getRecommendation (assuming no other ratings are sent in between), so that the consumer can assume that the correct recommendation will be played next.

Params:

Name	Type	Attribute	Description
channel	string		The channel used in the original call to `getRecommendationsFromChannel()`
uid	string		The unique ID of the item to queue up for the user

Return:

Recommendation

Throw:

TypeError	If no valid channel or UID is passed in
Error	If no recommendations for this channel were previously cached, or if the UID was not found in that cached list

Test:

Listening queueRecommendationFromChannel

public resetFlow(): Promise source

Resets the current flow for the user. Note that 99% of the time, clients will never have to do this (and it is generally considered an undesirable user experience), but in a few rare cases it might be needed. The best example is after calling setUserStation() if the current recommendation is of type === 'stationId'; in this case, resetting the flow may be necessary in order to make the user aware that they successfully changed their station.

Return:

Promise

Example:

let currentRecommendation = nprOneSDK.getRecommendation();
playAudio(currentRecommendation); // given a hypothetical playAudio() function in your app
...
nprOneSDK.setUserStation(123)
    .then(() => {
        if (currentRecommendation.attributes.type === 'stationId') {
            nprOneSDK.resetFlow()
                .then(() => {
                    currentRecommendation = nprOneSDK.getRecommendation();
                    playAudio(currentRecommendation);
                });
        }
    });

Test:

Listening resetFlow

public resumeFlowFromRecommendation(json: Object): Recommendation source

Given a valid JSON recommendation object, the flow will advance as normal from this recommendation. This method has been created for a special case (Chromecast sharing) and is not intended for use in a traditional SDK implementation.

NOTE: this function will overwrite ALL existing flow recommendations.

Params:

Name	Type	Attribute	Description
json	Object		Recommendation JSON Object (CDoc+JSON)

Return:

Recommendation

Test:

Listening resumeFlowFromRecommendation