Differences

This shows you the differences between two versions of the page.

--- paywall_invoker:imperative [2023/11/24 02:07] – joaosaraiva
+++ paywall_invoker:imperative [2026/03/27 17:24] (current) – external edit 127.0.0.1
@@ Line 1: / Line 1: @@
+====== Paywall imperative invocation ======
+In addition to the [[paywall_invoker:declarative|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 [[paywall_invoker:start#loading_the_paywall|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.
+<code javascript>
+Paperview
+  .set('<command>', '<command argument>')
+  .do('<optional command>')
+</code>
+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 [[paywall_invoker:javascript_events|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:
+<code javascript>
+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>')
+</code>
+Note that this snippet also ends up setting the DOM element that is the parent to the ''script'' tag as [[#content_selector|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:
+<code html>
+<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>
+</code>
+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.
+===== Paywall commands =====
+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:
+<code javascript>
+Paperview
+  .set('publication', 'publication-ID')
+  .set('article', 'article-ID-1')
+  .set('article', 'article-ID-2')
+  .do()
+</code>
+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.
+==== Paperview.set('publication', <argument>) ====
+**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|reading_token]].
+==== Paperview.set('article', <argument>) ====
+**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.
+==== Paperview.set('content_selector', <argument>) ====
+**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|new_invoke]] first.
+==== Paperview.set('reading_token', <argument>) ====
+**Argument type: string**\\
+A [[reading_token_provider:start|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.
+==== Paperview.set('roauth_token', <argument>) ====
+**Argument type: string**\\
+A ROAuth token to automatically login the Reader. This can be used to enable single sign-on (SSO) scenarios.
+==== Paperview.set('referrer', <argument>) ====
+**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.
+==== Paperview.set('seller', <argument>) ====
+**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.
+==== Paperview.set('skip_intro', <argument>) ====
+**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''.
+==== Paperview.set('go_back_on_close', <argument>) ====
+**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''.
+==== Paperview.set('remove_views', <argument>) ====
+**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|article for acquisition]] is specified.
+  * ''article_payment_introduction'': Shown to the anonymous Reader when an [[#article|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.
+==== Paperview.set('publisher_transaction_token', <argument>) ====
+**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.
+==== Paperview.set('will_replace', <argument>) ====
+**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).
+==== Paperview.do([<optional argument>]) ====
+**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|article]] is provided, this will default to ''acquire_article''; otherwise, the default will be ''subscribe_publication''.
+==== Paperview.set('new_invoke') ====
+Clears the stored set of commands. This command receives no arguments.