Tulo Paywall - Plug & Play¶
Target audience: Developers, Stakeholders
Introduction¶
This document describes how you can integrate with the Tulo Paywall using the Plug & Play method.
Step 1¶
Create a Tulo Paywall API user¶
To enable communication between your site and Payway you need to create a Tulo Paywall API user. The API user must include the following scopes:
/external/paywall/r
Since the communication will be done client-side rather than server-side it will also trigger a CORS request. Hence the API user must allow incoming requests from your domain. To allow client-side requests to the API you need to whitelist your domains that perform the requests to the API user.
Example of whitelisting a domain for an API user
Contact Adeprimo¶
Once you have your API user successfully created, you'll need to contact our support to enable the Tulo Paywalls feature. When contacting our support, the following information must be provided:
- API Key: Can be found and copied in your API user settings.
Step 2¶
Create your first Tulo Paywall¶
Once Tulo Paywalls have been enabled, you will be able to navigate to Marketing => Paywalls in the PAP and create your first paywall. To get started, we recommend you check out our guide in creating a Tulo Paywall.
Step 3¶
Preparing your site¶
Great job! If you got this far, you got your API user ready to go, and your first Tulo Paywall standing by. To start using your paywall, it will now have to be embedded on your site.
Include our CSS¶
For the Tulo Paywall to render correctly, you will need to include our CSS on your site. The CSS defined in this file can of course be overridden in your own CSS if you wish to do so. Choose the correct file, depending on what environment you are working in.
Environment | URL |
---|---|
Production | https://payway-cdn.worldoftulo.com/css/paywall.css |
Staging | https://payway-cdn-stage.adeprimo.se/css/paywall.css |
Include our Javascript¶
For the Tulo Paywall to function as it should, you will need to include our JS on your site. Choose the correct file, depending on what environment you are working in.
Environment | URL |
---|---|
Production | https://payway-cdn.worldoftulo.com/js/paywall.js |
Staging | https://payway-cdn-stage.adeprimo.se/js/paywall.js |
When to display the Paywall¶
Your site will need to determine if the Paywall needs to be shown to the end user. The paywall does not itself perform any access control. You can however pass information about the user to the Paywall and it can determine what offer the user will be shown, if any.
User logged in? | User has access? | Action |
---|---|---|
No | No | Show paywall |
Yes | No | Show paywall |
Yes | Yes | Do not show paywall |
Display paywall to logged in user¶
If you determine the user to be logged in and without access you will need to provide the account_id
as the claim aid
when generating the JWT token.
Step 4¶
Generating a JWT Token¶
All information exchanged between the Tulo Paywall JS and the paywall is transmitted in JSON Web Tokens (JWT) that are signed and encoded. The JWT is signed using your API Client secret, both ways, which enables both your website and Payway to verify that the token has not been tampered with and that it originates from the correct sender, in possession of the shared secret. For details about creating, signing, verifying, encoding and decoding JWT please read more on JWT.io.
A decoded JWT might look like this:
{
"alg": "HS256",
"typ": "JWT"
}
{
"iss": "57221f11584d54e28b000001",
"aud": "pw-paywall",
"nbf": 1603455793,
"exp": 1603542193,
"iat": 1603455793,
"aid": "63cfafea09c04c30c9e17c21",
"t": "TITLE_CODE"
}
Claim | Type | Description | Required |
---|---|---|---|
iss | string | Issuer should be your Tulo Paywall API user Client ID from Step 1. | Yes |
nbf | int(epoch) | Not before should be the epoch timestamp of when this token is created. | Yes |
exp | int(epoch) | Expires should be the epoch timestamp for 60 seconds after the token was created. | Yes |
iat | int(epoch) | Issued At should be the epoch timestamp of when this token is created. | Yes |
aud | string | Audience should always be "pw-paywall". | Yes |
t | string | Title is the title code for the site the Tulo Paywall is being initialized. | Yes |
aid | string | Account ID of the logged in user. Exclude or leave empty for anonymous. | No |
Step 5¶
Embedding your Tulo Paywall¶
To embed your Tulo Paywall, you will first need to define an HTML container where the paywall should live. This container can be anywhere on your site, though we recommend you give it plenty of space.
<div id="paywall-container"></div>
Afterwards, you can initialize the Javascript, that will take care of embedding your paywall into the container:
<script type="text/javascript">
new Paywall().Init({
url: "https://payway-paywall-stage.adeprimo.se/api/paywall",
jwtToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
debug: false
....
....
....
});
</script>
When initializing the Tulo Paywall script, an url
and jwtToken
must be provided.
Tulo Paywall URL¶
Choose the correct url
, depending on what environment you are working in.
Environment | URL |
---|---|
Production | https://paywall.worldoftulo.com/api/paywall |
Staging | https://payway-paywall-stage.adeprimo.se/api/paywall |
However, if you would like to take this one step further, some optional attributes can also be provided:
Available attributes¶
Attribute | Type | Description | Required | Available as resource in Paywall template |
---|---|---|---|---|
url | string | Tulo Paywall URL | Yes | No |
jwtToken | string | Generated server side in Step 4 | Yes | No |
debug | boolean | Set to true for additional information when troubleshooting | No | No |
accountOrigin | string | Read more about Account origin | No | No |
trafficSource | string | Read more about Traffic source | No | No |
merchantReference | string | Read more about Merchant reference | No | No |
returnUrl | string | Read more about Return url | No | Yes, [RETURN_URL] |
backUrl | string | Can be used as an alternative link back to the website from Tulo Shop, not to be mistaken for the returnUrl. | No | No |
loginUrl | string | Can be used for displaying a link for the customer to log in. | No | Yes, [LOGIN_URL] |
shopUrl | string | Can be used for displaying a custom link to the Tulo Shop. For example to all offers available. | No | Yes, [SHOP_URL] |
utmSource | string | GA support | No | No |
utmMedium | string | GA support | No | No |
utmCampaign | string | GA support | No | No |
utmContent | string | GA support | No | No |
resources | object | Overridable text resources. You'll find the available resources and default values here. | No | No |
engageTracking | object | Engage BI tracking meta data | No | No |
articleId |
string | If the Tulo Paywall is initiated from an article add the articleId to this parameter. | No | No |
categories |
array | Categories e.g. ["cat 1", "cat 2"] | No | No |
sections |
array | Sections e.g. ["sec 1", "sec 2"] | No | No |
onError | function | Callback if a Tulo Paywall error occurs. Will override default onError behaviour. Read more here. | No | No |
Text resources¶
There are several overridable text resources. Here you'll find which they are and when and where they occur. These resources can overridden using the resources
property.
Property | Type | Default value | Description |
---|---|---|---|
loadingText | string | Loading... | Text shown under the loading icon when the Tulo Paywall UI is rendering |
errorHeader | string | An error has occurred | The header shown when an error occurs |
errorDescription | string | Something unexpected happened. Please try again later, and if the problem persists, contact support. | The description shown when an error occurs |
Error handling¶
If an error within the Tulo Paywall occurs, an onError
function will be triggered. By default, this means that an error will be shown to the end-user, and you will receive debug information (granted the debug
flag is set to true) in the browser console.
If you would like to override this behaviour, you can simply define an onError
function when initializing the paywall. Furthermore, the function should accept one argument, in the form of the exception that was thrown. The exception that is thrown will always contain the following information:
Property | Type | Description |
---|---|---|
name | string | Will always be set to "PaywallError" |
code | string | The error code that was thrown |
field | string | The field relating to the error that was thrown |
pwCorrelationId | string | The correlation ID of the error. If you contact our support regarding a Tulo Paywall error, this ID should always be included in the support request. |
toString | function | Returns a stringified version of the error. |
The default error that is shown to the end user will always look like the following, though the text resources are customizable via the resources
property.
Step 6¶
Test & go live¶
Once everything above is said and done, we highly recommend you take some final steps before publishing your Tulo Paywall to a production environment:
- Test your Tulo Paywall and implementation in a testing/staging environment.
- Make sure the Tulo Paywall renders correctly, and no errors in the browser console are shown.