@datafire/npr_sponsorship
Client library for NPR Sponsorship Service
Installation and Usage
npm install --save @datafire/npr_sponsorship
let npr_sponsorship = require('@datafire/npr_sponsorship').create({
access_token: "",
refresh_token: "",
client_id: "",
client_secret: "",
redirect_uri: ""
});
.then(data => {
console.log(data);
});
Description
Sponsorship for non-NPR One client applications
Actions
oauthCallback
Exchange the code passed to your redirect URI for an access_token
npr_sponsorship.oauthCallback({
"code": ""
}, context)
Input
- input
object
- code required
string
- code required
Output
- output
object
- access_token
string
- refresh_token
string
- token_type
string
- scope
string
- expiration
string
- access_token
oauthRefresh
Exchange a refresh_token for an access_token
npr_sponsorship.oauthRefresh(null, context)
Input
This action has no parameters
Output
- output
object
- access_token
string
- refresh_token
string
- token_type
string
- scope
string
- expiration
string
- access_token
getAds
Not for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to request sponsorship on behalf of a user. Sponsorship units are returned in the form of VAST XML. It is worth noting that this endpoint attempts to always return XML, even in the case of exceptions.
The default behavior of this endpoint is asynchronous; on an initial request, a call to our external sponsorship provider is placed on a queue, which is typically processed within 3 minutes. Once the sponsorship call is received and processed, the returned sponsorship units are placed in a cache on our server for the current user. Subsequent calls to this endpoint will return VAST sponsorship units from this cache until tracking information is submitted, which removes the ad from the cache and will automatically request additional ads asynchronously if there are fewer than a certain number remaining in the cache.
For development purposes, it's worth noting that there is currently no way to clear a user's cache without submitting some form of tracking.
npr_sponsorship.getAds({
"Authorization": ""
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - forceResult
boolean
: Whether to force a synchronous call to our external sponsorship provider; the default behavior is asynchronous. - adCount
integer
: How many sponsorship units to request in one call; if left unspecified, the default behavior is to return only 1.
- Authorization required
Output
- output VASTXml
receiveAdTracking
Not for use by NPR One clients (for whom sponsorship is already integrated into the Listening Service), this endpoint is designed to be used by our other client applications to submit tracking information for sponsorship units obtained from the GET /sponsorship/v2/ads
endpoint.
The tracking information should be submitted in the body of the request in the form of a JSON object following the Collection.Doc+JSON specification.
npr_sponsorship.receiveAdTracking({
"Authorization": "",
"body": null
}, context)
Input
- input
object
- Authorization required
string
: Your access token from the Authorization Service. Should start withBearer
, followed by a space, followed by the token. - X-Advertising-ID
string
: A device-specific advertising identifier, if possible. Apple's IDFA is an example. - body required UserAdDocument
- Authorization required
Output
Output schema unknown
Definitions
AbstractCDocLink
- AbstractCDocLink
- href required
string
: The link to be followed - content-type required
string
: The MIME type of the response of this link
- href required
AbstractLink
- AbstractLink
object
- href required
string
: The link to be followed
- href required
AdTrackingData
- AdTrackingData
object
: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider- adId required
string
: The VAST Ad nodeid
attribute value, (e.g. AdswizzAd12345) - event required
string
(values: start, firstQuartile, midpoint, thirdQuartile, complete): The user-interaction event to submit tracking for
- adId required
AdTrackingDocument
- AdTrackingDocument: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
object
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
object
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes AdTrackingData
- items
array
: Not used- items
object
- items
- attributes required
AdXml
- AdXml
object
- InLine InLineXml
- id
string
Affiliation
- Affiliation
object
: A program (aggregation) that a given user has shown an affiliation with- daysSinceLastListen
integer
: The number of days since a user last listened to a story from this aggregation. Absent if user never listened to the aggregation. - following required
boolean
: Whether or not the user is following the aggregation. When changing affiliation status, the client is expected to toggle this value and then send the entire object back. - href required
string
: A link to more details about the program from the NPR Story API - id required
string
: A unique identifier for the aggregation (program) - notif_following
array
: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they follow.- items
string
- items
- notif_rated
array
: The topic in Firebase Cloud Messaging to which the device should subscribe if it supports notifications and the user wants notifications about the podcasts they have highly rated.- items
string
- items
- rating
number
: The user's average rating for this affiliation on a scale of 0-1. Absent if user never listened to the aggregation. - title
string
: The title for the aggregation (program)
- daysSinceLastListen
CollectionDocument
- CollectionDocument
object
: Base Collection.Doc+JSON output- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
object
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
object
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used
- attributes required
CompanionXml
- CompanionXml
object
- CompanionClickThrough
string
- StaticResource StaticResourceXml
- TrackingEvents
array
- items TrackingXml
- height
integer
- id
integer
- width
integer
- CompanionClickThrough
CreativeXml
- CreativeXml
object
- CompanionAds
array
- items CompanionXml
- Linear LinearXml
- id
integer
- sequence required
integer
- CompanionAds
Error
- Error
object
: A serialized version of any error encountered when processing this request- code required
integer
: The error code - debug
string
: Additional debug information if debug mode is turned on - text
string
: The error description
- code required
ErrorDocument
- ErrorDocument: A Collection.doc+JSON representation of an error result from an API call
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
object
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
object
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes
object
: Ignore; will be empty for errors - errors
array
: A list of encountered errors, ignored on POST, PUT- items Error
- items
array
: Ignore; will be empty for errors- items
object
- items
- links
object
: Ignore; will be empty for errors
- attributes required
ErrorXmlDocument
- ErrorXmlDocument
object
: One or more errors represented in a VAST XML document- error required
array
- items
string
: An individual error, presented in XML format
- items
- version required
string
- error required
ImpressionXml
- ImpressionXml
string
- id required
integer
- id required
InLineXml
- InLineXml
object
- AdSystem
string
- AdTitle
string
- Category
string
- Creatives
array
- items CreativeXml
- Description
string
- Extensions
array
- items
string
- items
- Impression
array
- items ImpressionXml
- AdSystem
LinearXml
- LinearXml
object
- Duration
string
- MediaFiles
array
- items MediaFileXml
- TrackingEvents
array
- items TrackingXml
- Duration
MediaFileXml
- MediaFileXml
string
- bitrate
integer
- delivery
string
- type
string
- bitrate
StaticResourceXml
- StaticResourceXml
string
- creativeType
string
- creativeType
TrackingXml
- TrackingXml
string
- event
string
(values: start, firstQuartile, midpoint, thirdQuartile, complete, creativeView)
- event
UserAdData
- UserAdData
object
: All information relevant to a user who has requested sponsorship or submitted tracking information- ipAddress
string
: The TCP/IP address of the client making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine an IP address from the request. - userAgent
string
: An identifying string for the browser making the request. The server will attempt to grab this from the headers, so it probably does not need to be passed in the body unless you get back an error message stating that we were unable to determine a User-Agent from the request.
- ipAddress
UserAdDocument
- UserAdDocument: All information relevant to a user who has requested sponsorship or submitted tracking information
- attributes required
object
- errors required
array
: A list of encountered errors, ignored on POST, PUT- items
object
- items
- href required
string
: A URL representation of the resource; should generally be ignored by clients unless noted otherwise - items required
array
- items
object
- items
- links required
object
- version required
string
: The version of the Collection.Doc+JSON spec being used - attributes UserAdData
- items
array
: All the information needed for the Sponsorship Service to send back tracking information to our external sponsorship provider- items AdTrackingDocument
- attributes required
VASTXml
- VASTXml
object
: Please visit https://www.iab.com/guidelines/digital-video-ad-serving-template-vast/ for more information on the VAST XML specification.- Ad AdXml
- version required
string