Paywall imperative invocation

In addition to the declarative invocation, the Paperview Paywall also supports a manner that we call imperative invocation. This invocation is performed exclusively through Javascript instructions, and thus endows the developer with much more control over the Paywall's operation.

The Paywall can be used in imperative mode simply by loading the Paywall javascript file into the web page, and then calling the Paperview.set and Paperview.do javascript functions with a set of supported commands.

Paperview
  .set('<command>', '<command argument>')
  .do('<optional command>')

Of course, the Paperview.set and Paperview.do functions are only available after the Paywall javascript finishes loading; until then, calling them will result in a null reference exception.
You can address this by listening for the ''paperview::lib_loaded'' event and only then issuing your commands. Alternatively, in a script tag in your web page, declare a global variable, with the name Paperview, and issue your commands:

function(r){if(!r.Paperview){var t=r.document,n=[];r.Paperview={q:n,script:t.scripts[t.scripts.length-1],set:function(){return arguments.length>0&&n.push(["set"].concat(Array.from(arguments))),r.Paperview},do:function(){n.push(["do"].concat(Array.from(arguments)))}}}}(window);
Paperview
  .set('<command>', '<command argument>')
  .do('<optional command>')

Note that this snippet also ends up setting the DOM element that is the parent to the script tag as the element which will contain the article's content, if the Reader acquires the article. Nevertheless, it is always recommended that you explicitly indicate the element(s) that will contain the article content.

A complete example with the bare minimum to invoke the Paywall could be:

<script>
function(r){if(!r.Paperview){var t=r.document,n=[];r.Paperview={q:n,script:t.scripts[t.scripts.length-1],set:function(){return arguments.length>0&&n.push(["set"].concat(Array.from(arguments))),r.Paperview},do:function(){n.push(["do"].concat(Array.from(arguments)))}}}}(window);
 
Paperview
  .set('publication', '--publication-ID--')
  .set('article', '--article-ID--')
  .do()
</script>
<script src="https://cdn.paperview-services.com/reader/paywall-invoker/paperview.js" async></script>

Note that the Paperview.set function always returns the Paperview object itself, so you can perform multiple calls to the Paperview.set function by chaining them, as shown in the previous example. The Paperview.do function does not return anything, as it invokes a Paywall workflow and will thus be the last step in your desired Paperview interaction.

The Paywall script supports a set of commands that are detailed in this page.

Be aware that commands are not cumulative, i.e. any call to a certain command will overwrite previous calls to that same command:

Paperview
  .set('publication', 'publication-ID')
  .set('article', 'article-ID-1')
  .set('article', 'article-ID-2')
  .do()

In this example, the Paywall will open for acquiring the article article-ID-2 belonging to publication publication-ID; the article article-ID-1 will effectively be ignored.

Argument type: string
The Publication ID for the Publication which provides the desired article, bundles, or subscriptions. This is always mandatory, except when the app workflow is perform_acquisition and you provide the reading_token.

Argument type: string
The Article ID for the desired article.
If this is provided, the Paywall will show the article acquisition screen, along with the possibility to acquire any bundles in which the article is included. Otherwise, only the Publication's bundles or subscriptions can be acquired.

Argument type: one or more string or DOM elements
A string (with a CSS selector) or a DOM element into which the article's content will be placed when the Reader becomes eligible to read the article.
Of course, this can also be an ordered Array of such elements, for cases in which the article has multiple content pieces.
If you call this multiple times, the new value(s) will be appended to the previous values, not replace them.
By default, this will be initialized with the DOM element that is the parent to the script tag that initially provided the commands. If you wish to remove this element from the list, be sure to invoke new_invoke first.

Argument type: string
A reading token to allow the Reader to view the article's content without needing to acquire it. Developers can use this attribute to easily perform an integration with their own subscription management mechanism.

Argument type: string
A ROAuth token to automatically login the Reader. This can be used to enable single sign-on (SSO) scenarios.

Argument type: string
The ID of the Reader that referred the current Reader to this article (and Paywall).
In most cases, this command will not be used, and the referrer will be determined from the current URL instead.

Argument type: string
The ID of the Reseller that is “selling” the article, subscription, or bundle. This is only used when selling Publication contents via a Reseller's web site.

Argument type: boolean
Whether anonymous Readers should not view the initial text explaining that they need a Paperview account in order to acquire an article, bundle, or subscription. Authenticated Readers will not view that message.
Any “truthy” value is true, otherwise false. Note that an empty string or null means false. Default value is false.

Argument type: boolean
Whether the Paywall should go back to the previous page if it is manually closed by the Reader. The default is false.

Argument type: one or more strings
A list of Paywall screens that should be hidden from the Reader. The screens available are payment_introduction, article_payment_introduction, acquire_article, acquire_bundle, and subscribe_publication.

• payment_introduction: Shown to the anonymous Reader when no article for acquisition is specified.
• article_payment_introduction: Shown to the anonymous Reader when an article for acquisition has been specified.
• acquire_article: The screen where the Reader can acquire the article.
• acquire_bundle: The screen where the Reader can acquire the Publication's bundles (filtered by the provided article, if any).
• subscribe_publication: The screen where the Reader can subscribe to the Publication

An example for a Paywall that should only display the article acquisition screen would be: acquire_bundle,subscribe_publication
If you call this multiple times, the new value(s) will be appended to the previous values, not replace them.

Argument type: string
A Publisher-specific token that should be associated with any transaction that is performed during this paywall interaction. Can be used by the Publisher to associate purchases (such as subscriptions) with other information that has previously been collected by the Publisher.

Argument type: string
What part of the target HTML DOM element should be replaced by the article content. Can be one of element or content. Default value is content.

• element: the HTML element itself should be replaced (and the element will be unavailable after replacement, of course).
• content: the HTML element's content will be replaced, but the element itself will remain in the DOM (and be available after replacement).

Argument type: string or none
Perform the specified workflow, displaying the Paywall if necessary.

The Paywall workflow to be used can be specified by an argument to the command, a string with one of acquire_article, acquire_bundle, subscribe_publication, or obtain_roauth_token.
If no argument is provided, and if the article is provided, this will default to acquire_article; otherwise, the default will be subscribe_publication.

Clears the stored set of commands. This command receives no arguments.