Connector Script 3 Beta

New features and improvements are available in Connector Script 3 beta. Note that there is no stable release of Connector Script 3 yet. If you opt-in to use the beta, expect things to change until the first stable release.

This page lists changes that affect how you integrate Connector into your website with Connector Script 3 beta.

URLs of Connector Script 3 Pre-Releases

Region Environment Locale URL
EU Sandbox English (US) https://connector-script.laterpay.net/3-pre/eu/sbx/app-en-us.js
EU Sandbox German (Germany) https://connector-script.laterpay.net/3-pre/eu/sbx/app-de-de.js
EU Live English (US) https://connector-script.laterpay.net/3-pre/eu/prod/app-en-us.js
EU Live German (Germany) https://connector-script.laterpay.net/3-pre/eu/prod/app-de-de.js
US Sandbox English (US) https://connector-script.uselaterpay.com/3-pre/us/sbx/app-en-us.js
US Sandbox German (Germany) https://connector-script.uselaterpay.com/3-pre/us/sbx/app-de-de.js
US Live English (US) https://connector-script.uselaterpay.com/3-pre/us/prod/app-en-us.js
US Live German (Germany) https://connector-script.uselaterpay.com/3-pre/us/prod/app-de-de.js

The URLs in the table above will always point to the latest release of Connector Script 3 (including pre-releases and stable releases).

If you wish to pin a specific release, replace “3-pre” with the corresponding semver string of that release.

See Releases of Connector Script for a complete list of all releases.

As soon as the first stable release of Connector Script 3 is available, another redirect “3-stable” will always point to the latest stable release (excluding pre-releases).

JWT Paid Content API

The most prominent change with Connector Script 3 is the extension of the JWT Dynamic Paid Content API: You can now define Purchase Options of all Sales Models: Single Purchases, Time Passes and Subscriptions. It also allows for more granular control over which Purchase Options from Connector Admin Interface should be presented to the user.

The In-Page Configuration Token allows you to publish new paid content without having to configure anything in Connector Admin Interface.

Create a signed JSON web token (JWT) containing the required Purchase Options and sign it with your secret API Key. Then pass it as the In-Page Configuration property laterpay:connector:config_token:

<meta property="laterpay:connector:config_token" content="[...]">

Note, that in the example above, [...] is used as a placeholder for the actual token. See details on how to create the In-Page Configuration Token in the following sections.

Note

Your secret API Key can be retrieved from the “Developer” section in Merchant Backend. The URL that you use to access Merchant Backend depends on the region and environment of your integration. You can find the appropriate URL in section URLs of Merchant Backend.

JWT Object Properties

This is a JSON Web Token per RFC 7519, encoding In-Page Purchase Options and other options.

The JWT consists of three parts:

  1. The header, defining the algorithm and type
  2. The payload, defining the In-Page Purchase Options and other options
  3. The signature
Header:

The header must use the HS256 algorithm and the JWT type:

{
    "alg": "HS256",
    "typ": "JWT"
}
Payload:

The payload has one required key purchase_options. The keys ignore_database_single_purchases, ignore_database_subscriptions, ignore_database_timepasses, and template are optional.

purchase_options:
 

Required

An array of Purchase Options. Each element is an object with an article_id, a price, a sales_model and a title. For Subscriptions and Time Passes, a description and an expiry are also required.

article_id:

Required

Article IDs give more flexibility by allowing to use them on arbitrary sides or content, regardless of the URL.

An article_id has to match the RegEx ^[a-zA-Z0-9_-]{1,128}$.

In other words, it’s a string consisting of letters, digits, hyphens and underscores no longer than 128 characters that is unique for the article being offered.

price:

Required

An object stating the amount, currency, and Payment Model. For a 1.23 EUR “Pay Later” pricing, using this:

"price": {
    "amount": 123,
    "currency": "EUR",
    "payment_model": "pay_later"
}

A 4.99 EUR “Pay Now” pricing looks like this:

"price": {
    "amount": 499,
    "currency": "EUR",
    "payment_model": "pay_now"
}
sales_model:

Required

Either “single_purchase”, “subscription”, or “timepass”.

title:

Required

A human-readable string with at most 256 characters.

description:

Required when ``sales_model`` is a Subscription or Time Pass

A human-readable string that is shown below the title. While the title for a Time Pass might be “Week pass”, the description could be “7 day access to all our premium content”.

expiry:

Required when ``sales_model`` is ``subscription`` or ``timepass``

Defines the duration/expiration of the Subscription or Time Pass.

The unit can be one of "h", "d", "w", or "m" for hour, day, week or month.

The value can be any integer from 1 to 24 (including):

"expiry": {
    "unit": "w",
    "value": 2
}
ignore_database_single_purchases:
 

Optional

Boolean value that defines if Single Purchases that were defined through Connector Admin Interface should be ignored and thus should not be presented to the user.

ignore_database_subscriptions:
 

Optional

Boolean value that defines if Subscriptions that were defined through Connector Admin Interface should be ignored and thus should not be presented to the user.

ignore_database_timepasses:
 

Optional

Boolean value that defines if Time Passes that were defined through Connector Admin Interface should be ignored and thus should not be presented to the user.

template:

Optional

Most times templates will be assigned to Purchase Options through Connector Admin Interface. If a different template should be used for this page, pass the UUID of the template here.

Signature:

The signature is the HMAC-SHA-256 over the base64 URL encoded header, concatenated with a ., concatenated with the base64 URL encoded payload. The key or secret for the signature function is the merchant’s secret.

Example

Given this payload:

{
    "purchase_options": [
        {
            "article_id": "article_12345",
            "price": {
                "amount": 42,
                "currency": "EUR",
                "payment_model": "pay_later"
            },
            "sales_model": "single_purchase",
            "title": "Team A wins over Team B"
        },
        {
            "article_id": "category_sports",
            "price": {
                "amount": 899,
                "currency": "EUR",
                "payment_model": "pay_now"
            },
            "sales_model": "subscription",
            "title": "Monthly Sports Subscription",
            "description": "Monthly subscription to all our sports news",
            "expiry": {
                "unit": "m",
                "value": 1
            }
        },
        {
            "article_id": "category_sports",
            "price": {
                "amount": 234,
                "currency": "EUR",
                "payment_model": "pay_now"
            },
            "sales_model": "timepass",
            "title": "7 Days of Sport",
            "description": "Access to all our sports news for 7 days",
            "expiry": {
                "unit": "d",
                "value": 7
            }
        }
    ],
    "ignore_database_single_purchases": true,
    "template": "78c10144-1ee9-4547-a6b4-d16f742102cd"
}

and a merchant secret 2e910ba0f326421a8fa7dfe1621755e2 will result in a JWT much like this (line breaks for readability):

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.
eyJwdXJjaGFzZV9vcHRpb25zIjpbeyJhcnRpY2xlX2lkIjoiYXJ0aWNsZToxMjM0NSIsInByaWN
lIjp7ImFtb3VudCI6NDIsImN1cnJlbmN5IjoiRVVSIiwicGF5bWVudF9tb2RlbCI6InBheV9sYX
RlciJ9LCJzYWxlc19tb2RlbCI6InNpbmdsZV9wdXJjaGFzZSIsInRpdGxlIjoiVGVhbSBBIHdpb
nMgb3ZlciBUZWFtIEIifSx7ImFydGljbGVfaWQiOiJjYXRlZ29yeTpzcG9ydHMiLCJwcmljZSI6
eyJhbW91bnQiOjg5OSwiY3VycmVuY3kiOiJFVVIiLCJwYXltZW50X21vZGVsIjoicGF5X25vdyJ
9LCJzYWxlc19tb2RlbCI6InN1YnNjcmlwdGlvbiIsInRpdGxlIjoiTW9udGhseSBTcG9ydHMgU3
Vic2NyaXB0aW9uIiwiZGVzY3JpcHRpb24iOiJNb250aGx5IHN1YnNjcmlwdGlvbiB0byBhbGwgb
3VyIHNwb3J0cyBuZXdzIiwiZXhwaXJ5Ijp7InVuaXQiOiJtIiwidmFsdWUiOjF9fSx7ImFydGlj
bGVfaWQiOiJjYXRlZ29yeTpzcG9ydHMiLCJwcmljZSI6eyJhbW91bnQiOjIzNCwiY3VycmVuY3k
iOiJFVVIiLCJwYXltZW50X21vZGVsIjoicGF5X25vdyJ9LCJzYWxlc19tb2RlbCI6InRpbWVwYX
NzIiwidGl0bGUiOiI3IERheXMgb2YgU3BvcnQiLCJkZXNjcmlwdGlvbiI6IkFjY2VzcyB0byBhb
Gwgb3VyIHNwb3J0cyBuZXdzIGZvciA3IGRheXMiLCJleHBpcnkiOnsidW5pdCI6ImQiLCJ2YWx1
ZSI6N319XSwiaWdub3JlX2RhdGFiYXNlX3NpbmdsZV9wdXJjaGFzZXMiOnRydWUsInRlbXBsYXR
lIjoiNzhjMTAxNDQtMWVlOS00NTQ3LWE2YjQtZDE2Zjc0MjEwMmNkIn0.
UxLfG9Dd9TZIfEWGyWKqv2yAIKCg94yD2ZkARwyJObo

This JWT will result in Connector Script showing no database defined Single Purchases for this page, but all database defined Subscriptions and Time Passes for this page. Additionally, a “Pay Later” Single Purchase for 42 Euro cents, a monthly Subscription for 8.99 EUR and a one-week Time Pass for 2.34 EUR will be shown. Lastly, the template Connector Service will return the template with the ID 78c10144-1ee9-4547-a6b4-d16f742102cd.

Automatic Analytics Integration

Connector Script 3 automatically supports Google Analytics for Web (analytics.js).

If you are using Automatic Analytics Integration with Legacy Google Analytics for Web (ga.js) or Webtrekk, you need to implement a Custom Analytics Integration.

AdVantage

The AdVantage service has been discontinued and it is not supported by Connector Script 3.

In-Page Configuration Callback “On Ready”

The new In-Page Configuration Callback “On Ready” can be registered to receive the lpcHandle object which exposes functions for controlling the program flow of Connector Script.

The “On Ready” callback is invoked after Connector Script has been loaded and initialized but before the API is requested. The lpcHandle object is passed to the callback function as its first and only parameter.

The following functions are exposed as properties of the lpcHandle object:

reset:Resets Connector Script to its initial state and deobfuscates any obfuscated Paid Content
init:Initializes the app from local data (reads In-Page Configuration) but doesn’t request the API
fetch:Fetches data from the API based on the current configuration that was initialized by init
preventDefault:When called immediately within the In-Page Config Callback “On Ready”, this disables automatic fetching of data from the API and thus stops the execution of Connector Script before it renders any UI into the DOM

Example:

<meta property="laterpay:connector:callbacks:on_ready" content="lpcReadyCallback">
<script type="text/javascript">
    function lpcReadyCallback(lpcHandle) {
        console.log('Received lpcHandle:', lpcHandle)
        lpcHandle.preventDefault()
        // Use functions `lpcHandle.fetch()`, `lpcHandle.reset()` and `lpcHandle.init()`
        // to control the flow of Connector Script
    }
</script>

In the example above, the global function lpcReadyCallback is registered as In-Page Configuration Callback “On Ready”. It is invoked by Connector Script as soon as the app is loaded and initialized but before the API is requested.

By calling lpcHandle.preventDefault() the default behavior of Connector Script is disabled which means that:

  • the API will not be requested
  • the Purchase Overlay will not be rendered
  • the Paid Content (elements matched by the Content Selector) will not be obfuscated

At this point you can use the functions exposed by the lpcHandle object for custom control of Connector Script.

A typical use case for this kind of fine-grained control is a Single Page Application:

  1. Use lpcHandle.preventDefault() to prevent Connector Script from requesting the API and from rendering any UI automatically.
  2. Call lpcHandle.init() and lpcHandle.fetch() as soon as your dynamic content is fully rendered.
  3. Call lpcHandle.reset() before changing the page content.
  4. Start from #2 again after new page content has been rendered.