JavaScript SDK client side integration

The plenigo JavaScript-SDK offers the possibility to implement the plenigo functionality without a need for a server side request.

General functionality

The plenigo JavaScript-SDK offers additional functionality in addition to the PayWall functionality. These functions are completely independent from the usage of the SDK.

If you are using one of the plenigo SDKs you may not need all the functionality because the SDKs may already encapsulate some calls. Please refer to the according SDK documentation to cover this up.

Functions that are not covered on this page are used by your own risk. Only functions covered here will be supported by plenigo and are guaranteed to live up. If a function disappears it normally isn’t needed anymore and if you are still using it nothing happens. But you could also remove this function. Functions that must be replaced with other functions are marked as deprecated with an end date mentioned.

Start - Initialization call

The plenigo JavaScript-SDK initialize itself automatically when it is included in the HTML page after the page is loaded completely. If you are loading the Javascript-SDK manually after the page is loaded you need to start the initialization by calling this method.

/**
 * Initialize the plenigo JavaScript-SDK.
 */
plenigo.start();

Checkout - Start a plenigo checkout

This function offers the possibility to start a checkout process for the customer including the login and registration process of plenigo.

/**
 * Start a checkout process.
 * 
 * @param {object} configuration              
 */
plenigo.checkout(configuration);

The following tables describes the configuration object. Non mandatory parameters can be filled with null.

Checkout with remote login - Start a plenigo checkout with external user management

This function offers the possibility to start a checkout process for the customer including the login and registration process of plenigo.

/**
 * Start checkout process for external managed users.
 * 
 * @param {object} configuration              
 */
plenigo.checkoutWithRemoteLogin(configuration);

The following tables describes the configuration object. Non mandatory parameters can be filled with null.

Login - Open the plenigo login window

This function offers the possibility to open up the plenigo login window. It is possible for the user to switch to the registration window if needed.

/**
 * Open up login screen.
 * 
 * @param {object} configuration              
 */
plenigo.login(configuration);

The following tables describes the configuration object. Non mandatory parameters can be filled with null.

If the “productIds” parameter is passed the targetUrl will only be called if the customer has successfully bought a product. Otherwise the user will stay on the current page. If the user has bought a product the target url will be called with the following additional parameters.

Registration - Open the plenigo registration window

This function offers the possibility to open up the plenigo registration window. It is possible for the user to switch to the login window if needed.

/**
 * Open up registration screen.
 * 
 * @param {object} configuration              
 */
plenigo.registration(configuration);

The following tables describes the configuration object. Non mandatory parameters can be filled with null.

If the “productIds” parameter is passed the targetUrl will only be called if the customer has successfully bought a product. Otherwise the user will stay on the current page. If the user has bought a product the target url will be called with the following additional parameters.

Forgot Password - start a forgot password process

With this function you can display the forgot password window to let users change their password. It is recommended, if you imported users with an external subscription ID and without any password. In these cases your customers have to set a new password.

/**
 * Open up password forgotten screen.
 *
 * @param {object} params
 */

plenigo.passwordForgotten({object});

The following tables describes the configuration object. Non mandatory parameters can be filled with null.

Logout - Logout the user

This function deletes the user’s login cookie. It doesn’t have any additional functionality.

/**
 * Logout the user.
 * 
 * @param {object} configuration              
 */
plenigo.logout({object});

Is user logged in - Indicates if the user is currently logged in

This function indicates if the user is logged in.

/**
 * Get flag indicating if user is logged in.
 *
 * @returns {*|boolean} true if the user is logged in false otherwise
 */
plenigo.isUserLoggedIn();

Reset layer opened detection - reset detection to prevent double opened login and checkout layers

Reset the detection for preventing double opened login and checkout layers.

/**
 * Resets the SDKs detection to prevent double opened login and checkout layers.
 */
plenigo.resetLayerOpenedDetection();

Usage examples

Following are a few examples of the usage for JavaScript-SDK.

JavaScript only checkout

The JavaScript only checkout can be used on LandingPages or something similar. This way you can integrate plenigo easily on pages where you don’t have direct control over the server side code execution.

To get a working example you have to replace some variables. Variables to are starting and ending with a dollar sign, e.g. $COMPANY_ID$ and described in a comment.

<!DOCTYPE html>
<html>
    <head>
        <title>Greatest product ever!</title>
    
        // Replace $COMPANY_ID$ with the company id from the plenigo merchant backend. 
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/$COMPANY_ID$/plenigo_sdk.min.js"
            data-disable-metered="true">
        </script>
        
        <script type="application/javascript">
            // Replace $CHECKOUT_STRING$ with the checkout string of the product that you can retrieve 
            // from the product overview page in the plenigo backend.
            // Replace $TARGET_URL$ with the url the checkout should redirect after being finished. Could be
            // a thank you page.
            var checkoutConfig = {
                paymentData: "$CHECKOUT_STRING$",
                startWithRegistration: "true",
                sourceUrl: null,
                targetUrl: "$TARGET_URL$",
                affiliateId: null,
                elementId: null
            }
        </script>
    </head>
    <body>
        <h2>The greatest product ever available</h2>
        
        
        <p>
            This is your chance to buy the best product ever available!
            
            <button onclick="plenigo.checkout(checkoutConfig); return false;">
                Buy now
            </button>
        </p>
    </body>
</html>

Snippets functionality

The plenigo JavaScript-SDK offers you the possibility to enable your users to do self management of their user data, orders, subscriptions, etc. This way you provide a whole backend functionality without great programming efforts. What kind of data the user can see and edit can be freely defined by you. Only show the snippets you want the user to see. Snippets are only available in embedded mode.

The snippet call expects the following parameters. All of these parameters are mandatory.

Otherwise you can use one parameter as an object with the following keys

Snippets that combine different elements

• plenigo.Snippet.PERSONAL_DATA
• plenigo.Snippet.ORDER
• plenigo.Snippet.SUBSCRIPTION
• plenigo.Snippet.PAYMENT_METHODS
• plenigo.Snippet.ADDRESS_DATA

Single elements

• plenigo.Snippet.BILLING_ADDRESS_DATA
• plenigo.Snippet.DELIVERY_ADDRESS_DATA
• plenigo.Snippet.BANK_ACCOUNT
• plenigo.Snippet.CREDIT_CARD
• plenigo.Snippet.PERSONAL_DATA_SETTINGS
• plenigo.Snippet.PERSONAL_DATA_ADDRESS
• plenigo.Snippet.PERSONAL_DATA_PROTECTION
• plenigo.Snippet.PERSONAL_DATA_SOCIAL_MEDIA
• plenigo.Snippet.PERSONAL_DATA_PASSWORD

Example snippet for the JavaScript to render a personal data snippet.

<head><script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-disable-metered="true"></script></head>
<body>
    <div id="plenigoSnippet"></div>

    <!-- End of the HTML body. Not really necessary, but possible -->
    <script type="application/javascript">
        // we render the personal data snippet in this example ( parameter style)
        plenigo.renderSnippet("plenigoSnippet", plenigo.Snippet.PERSONAL_DATA, "https://www.YOUR_DOMAIN.com/");
    
    
        // we render the snippet in object style
        plenigo.renderSnippet({ 
            elementId:"plenigoSnippetPersonalData", 
            snippetId: plenigo.Snippet.PERSONAL_DATA_ADDRESS, 
            loggedOutRedirectUrl: "https://www.YOUR_DOMAIN.com/", 
            edit: false 
        });
    </script>
</body>

PayWall functionality

If you plan to use the PayWall functionality of plenigo you have to choose between three different use cases:

Hide content afterwards

The content will be visible on the page from the beginning and the plenigo JavaScript-SDK is going to hide it if the user is not allowed to see the content. If JavaScript is disabled or the user blocks the plenigo JavaScript-SDK she can access the whole page without any restrictions.

The plenigo JavaScript checks if the user has all rights necessary to see the content and if not the content is replaced with an up selling window or anything else. To integrate the JavaScript SDK add the following line to your template/html. The COMPANY_ID variable must be replaced with the actual company id.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true"></script>

There are additional configuration options. This options are added as attributes to the JavaScript tag.

Example snippet for the JavaScript to include if you use the client side PayWall and hide the content if user has not bought the product.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true" data-paywall-type="hide" data-paywall-source-element-id="upselling-teaser" data-paywall-target-element-id="page-content" data-product-id="product"></script>

A complete example page where you only need to insert your data. This example assumes you are running in test mode with metered views enabled.

<!DOCTYPE html>
<html>
    <head>
        <title>A great news page </title>
    
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true" data-paywall-type="hide" data-paywall-source-element-id="sourceId" data-paywall-target-element-id="targetId" data-product-id="YOUR_PRODUCT_ID" data-test-mode="true">
        </script>
    </head>
    <body>
        <h2>This is the content area</h2>
        
        <div id="targetId">
            <p>
                This is the content you waited for!
            </p>
        </div>
        <div id="sourceId" style="display:none;">
            <p>
                You don't have the right to see this content! Sry!
                <button onclick="plenigo.checkout({paymentData: 'CHECKOUT_STRING'})">
                    Buy now
                </button>
                <button onclick="plenigo.login();">
                    Login
                </button>
            </p>
        </div>
    </body>
</html>

Hide content by default

The content will be placed in an HTML element that is hidden. After the user was verified to be allowed to see the content the content will be made visible by the plenigo JavaScript-SDK. The user is still able to access the content in the HTML sources.

The plenigo JavaScript checks if the user has all rights necessary to see the content and if the content is accessible the CSS style that hides the content is removed and the up selling window is hidden. To integrate the JavaScript SDK add the following line to your template/html. The COMPANY_ID variable must be replaced with the actual company id.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true"></script>

There are additional configuration options. This options are added as attributes to the JavaScript tag.

Example snippet for the JavaScript to include if you use the client side PayWall and show the content if user has bought the product.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true" data-paywall-type="show" data-paywall-source-element-id="page-content" data-paywall-target-element-id="upselling-teaser" data-product-id="productId"></script>

A complete example page where you only need to insert your data. This example assumes you are running in test mode with metered views enabled.

<!DOCTYPE html>
<html>
    <head>
        <title>A great news page </title>
    
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true" data-paywall-type="show" data-paywall-source-element-id="sourceId" data-paywall-target-element-id="targetId" data-product-id="YOUR_PRODUCT_ID" data-test-mode="true"> </script>
    </head>
    <body>
        <h2>This is the content area</h2>
        
        <div id="targetId">
            <p>
                You don't have the right to see this content! Sry!
                <button onclick="plenigo.checkout({paymentData: 'CHECKOUT_STRING'})">
                    Buy now
                </button>
                <button onclick="plenigo.login();">
                    Login
                </button>
            </p>
        </div>
        <div id="sourceId" style="display:none;">
            <p>
                This is the content you waited for!
            </p>
        </div>
    </body>
</html>

Load content afterwards

The content to be protected isn’t on the site at all. After the user was verified to be allowed to see the content the content will be loaded by another URL. If the user disables JavaScript or blocks the plenigo JavaScript-SDK he will not be able to see the content. It is also not visible in the HTML sources.

The page is only rendered with a teaser and an up selling window or anything else defined. The plenigo JavaScript checks if the user has all rights necessary to see the content and if the content is accessible it loads the complete article snippet from another URL not visible to the user. To integrate the JavaScript SDK add the following line to your template/html. The COMPANY_ID variable must be replaced with the actual company id.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true"></script>                      

There are additional configuration options. This options are added as attributes to the JavaScript tag.

Example snippet for the JavaScript to include if you use the client side PayWall and load the content from another url if user has not bought the product.

<script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js" data-client-paywall="true" data-paywall-type="url" data-paywall-base-url="http://example.com" data-paywall-target-element-id="targetId" data-product-id="productId" data-paywall-external-content-id="externalContentId"></script>

A complete example page where you only need to insert your data. This example assumes you are running in test mode with metered views enabled.

<!DOCTYPE html>
<html>
    <head>
        <title>A great news page </title>
    
        <!--
        The following configuration will load the content from the following url after
        the user has bought YOUR_DOMAIN_URL/MD5(YOUR_IDENTIFIER_FOR_THIS_CONTENT).
        Let's use concrete values
        data-paywall-base-url="http://example.com" (has to be the same domain like the page)
        data-paywall-external-content-id="great-article-number-one"
        would produce the following url
        http://example.com/a0048edd23a9aa85e37c248bd28f270b
        -->
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/COMPANY_ID/plenigo_sdk.min.js"
                data-client-paywall="true" data-paywall-type="url" data-paywall-base-url="YOUR_DOMAIN_URL"
                data-paywall-target-element-id="targetId" data-product-id="YOUR_PRODUCT_ID" data-paywall-external-content-id="YOUR_IDENTIFIER_FOR_THIS_CONTENT">
        </script>
    </head>
    <body>
        <h2>This is the content area</h2>
        
        <div id="targetId">
            <p>
                You don't have the right to see this content! Sry!
                <button onclick="plenigo.checkout({paymentData: 'CHECKOUT_STRING'})">
                    Buy now
                </button>
                <button onclick="plenigo.login();">
                    Login
                </button>
            </p>
        </div>
    </body>
</html>

Web Statistics

As by design, the SDK opens up an iframe to offer the plenigo checkout process. This makes it difficult to track the user experience through this process. With the plenigo module web analytics we offer you a look inside this process and give the missing data.

Installation

The installation is just adding the new attribute data-on-action to your plenigo SDK call:

<!DOCTYPE html>
<html>
    <head>
        <title>Track even interactive elements</title>
    
        // Replace $COMPANY_ID$ with the company id from the plenigo merchant backend. 
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/$COMPANY_ID$/plenigo_sdk.min.js"
            data-disable-metered="true"
            data-on-action="statisticFunction">
        </script>
  ```
 
You are free to name the method _statisticFunction_. It can be a method at an object, but has to be accessible or be part of the _window_ object. 

### Debugging

To debug this function simply use the _console_ function:

```html
<script>
  var statisticFunction = function (data) { console.log(data) }
</script>

On Submit this will result in the following data:

// on submit
data = {
    action: "submit"
    data: [
      0: {name: "userCountry", value: "DE"}
      1: {name: "userState", value: ""}
      2: {name: "billingAddressNeeded", value: "false"}
      3: {name: "paymentMethod", value: "BILLING"}
      4: {name: "useVoucher", value: "true"}
      5: {name: "ageVerification", value: "false"}
      ]
};

// on load
data = { 
    action:"load"
    data: [],
    page: "previousStep",
    pageName: "basket",
    product: "" // will be set on the basket page
    };
    

working with Events

If your tracking javascript code should not be accassible from outside, you should use our tracking events:

document.addEventListener("plenigo.Statistic", function(e) {
    // debugging Code:
    console.info("Event is: ", e);
    console.info("Custom data is: ", e.detail);
});

The additional data-on-action attribute is not used.

Description of data

The onAction Callback gets some data to have a better look inside of tho plenigo checkout process. Best way to know the path, your customer takes through the checkout is, tracking each page of the checkout process. This is done by only taking calls with action === "load". In these cases you will miss some data and get the name of the page on pageName. Since one can easily change the product during the checkout, we will put in the productID on the product-parameter whenever the change of it is done. This should always be the basket page.

// valid pageNames are:
basket
payPalSummary
payPalRedirect
zeroPayment
creditCardSummary
invoiceAddress
selectCreditCard
invoiceAddressVerification
enterCreditCard
voucher
bankAccountSummary
enterBankAccount
sofortUeberweisungSummary
selectBankAccount
sofortUeberweisungRedirect
paymentFailed

Example with analytics

To get a working example you have to replace some variables. Variables to are starting and ending with a dollar sign, e.g. $COMPANY_ID$ and described in a comment.

<!DOCTYPE html>
<html>
    <head>
        <title>Greatest product ever!</title>
    
        // Replace $COMPANY_ID$ with the company id from the plenigo merchant backend. 
        <script type="application/javascript" src="https://static.plenigo.com/static_resources/javascript/$COMPANY_ID$/plenigo_sdk.min.js"
            data-disable-metered="true"
            data-on-action="statistics.checkout">
        </script>
        
        <script type="application/javascript">
            var statistics = {
                checkout: function(data) {
                    var i = 0, form = [];
                    // checks, if analytics is fully initialized
                    if (typeof ga === "undefined") {
                        return;
                    }

                    if (data.action === "load") {
                        ga("send", {
                            hitType: "pageview",
                            page: "/checkout/" + data.pageName
                        });
                    } else if (data.action === "submit") {
                        form = data.data || form;
                        for (i = 0; i < form.length; i++) {
                            if (form[i].name === "paymentMethod") {
                                ga("send", {
                                    hitType: "event",
                                    eventCategory: "PaymentMethod",
                                    eventAction: form[i].name,
                                    eventLabel: "plenigo"
                                });
                            }
                        }
                    }
                }
            };
        </script>
    </head>
    <body>
        <h2>The greatest product ever available</h2>
        
        
        <p>
            This is your chance to buy the best product ever available!
            
            <button onclick="plenigo.checkout(checkoutConfig); return false;">
                Buy now
            </button>
        </p>
    </body>
</html>

execute and read metered (SPA)

With normal configuration and metered enabled, the meter will count automatically on each page load. For Single Page Applications this will not work.

control metered

Even in Single Page Applications one have to control the metered behavior. This is done with a call of the method plenigo.countMeteredView. It needs one parameter to identify the actual view:

// define the config object
var config = {
  identifier: 'myActualView' // key to define the provided view
};

// execute the metered counter with given configuration
plenigo.countMeteredView(config);

get metered information

Not only in Single Page Applications one wants to read the actual metered status. You can use it in your statistic tools too. To read the metered status simply call plenigo.getMeteredViewInfo.

var info = plenigo.getMeteredViewInfo();

console.log(info);

// will output
info = {
  activated: true,
  browserId: "b17ef4299ec632302ab155f3b1bb9a42"
  cookieCreation: 1526971537227,
  cookieVersion: 1526980598208,
  fingerprint: "b17ef4299ec632302ab155f3b1bb9a42",
  freeAfterLogin: 10,
  freeAfterLoginTaken: 0,
  freeViews: 20,
  ignoreSearchEngines: true,
  ignoreSocialMedia: true,
  limitReached: false,
  limitReachedAfterLogin: false,
  onlyUniqueViews: true,
  period: "MONTH",
  startTime: 1525132800000,
  startWithFirstVisit: false,
  uniquelyVisitedSites: "05ee2a41,c4ca4238,c81e728d,eccbc87e,a87ff679,e1671797,a2e84d15",
  viewsTaken: 7
 };

Video-Player with access control

Based on the 3q video player plenigo offers you a video player with access control. You may need a 3q account one can create at 3q video

There one can upload multiple videos.

Installation

The installation is based on the 3qvideo player. All the configuration parameters you can see in their documentation

        window.plenigoVideoPlayer = window.plenigoVideoPlayer || [];

            plenigoVideoPlayer.push({
                'data-id': '5280e612-c311-11e8-ae4b-0cc47a188158', // Video ID from 3q backend
                'container': 'video1', // ID of HTML-Element in you html page
                'productIDs': 'P_PWywB6996251827351,P_ygHn66932077286351', // lst of plenigo product IDs to check access against
                'teaserLength': 2, // length of free videoteaser until video is stopped
                'no-access-callback': function (par1, par2) { // callbackfunction we call, if customer has no access
                    location.href = "/landingpage";
                }
            });
          

Example with full html

Just put the plenigo Jacascript call somewhere in your html. To enable video player, add attribute data-video="3q".

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
</head>
<body>

    <header class="main">
        <h1>My 1st video</h1>
    </header>


        <div id="video"></div>
    
    
<script type="application/javascript"
        src="https://static.plenigo.com/static_resources/javascript/$COMPANY_ID$/plenigo_sdk.min.js" 
        data-lang="de" 
        data-video="3q"></script>

<script>

        window.plenigoVideoPlayer = window.plenigoVideoPlayer || [];

            plenigoVideoPlayer.push({
                'data-id': '5280e612-c311-11e8-ae4b-0cc47a188158',
                'container': 'video',
                'productIDs': 'P_WWWWQQQQ27351,P_WWWWQQQQ77286351',
                'sticky': true,
                'playlistbar' : true,
                'teaserLength': 2,
                'no-access-callback': function (productIds, videoId) {

                    location.href = "/video/checkout";
                }
            });
    </script>

</body>
</html>

If the customer has not bought at least one of the products given in the productIDs parameter, it will call call function given in no-access-callback. Here one can simply call a landing page, or open a dialog or simply start a plenigo checkout.

Checkout with API v3.0

plenigo started its APIv3.0 in late 2019. It comes with several new API-calls.

Installation

The installation is equal to plenigo Javscript-SDK and needs no changes. You can copy this code with matching company id from you plenigo backend in section settings / developer. Please note, that javascript embeds may slow down your page. Thats why we designed our sdk to be embeded at the end of your html code. Please also note, that your plenigo stage account has a different company id to your live account. Working against plenigo stage also means, to load the sdk from a different domain.

   <div id="plenigoCheckout"></div>
   <!-- please replace {your_companyId} with your companyId -->
   <!-- for implementing in production environment -->
   <script src="https://static.plenigo.com/static_resources/javascript/{your_companyId}/plenigo_sdk.min.js"
                                    data-disable-redirect="true"
                                    data-companyId="{your_companyId}"
                                    data-lang="en"></script>

   <!-- for implementing in stage environment only -->
   <script src="https://static.plenigo-stage.com/static_resources/javascript/{your_companyId}/plenigo_sdk.min.js"
                                    data-disable-redirect="true"
                                    data-companyId="{your_companyId}"
                                    data-lang="en"></script>
                            

Starting checkout

To start a plenigo Checkout you need to obtain a purchaseId plenigo Checkout starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/success-page/?order=" + e.detail.orderId ;
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout(purchase.purchaseId, { elementId: "plenigoCheckout" }).start();

Dealing with already bought products

If customer starts a checkout with a product he has already bought, checkout will display a message and a next button. Next button will trigger plenigo.PurchaseSuccess-Event too, but not with the original orderId. It will use -1 instead:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        let orderId = e.detail.orderId;
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
         if (orderId < 0) {
            location.href = "/customer-came-again-page/";
         } else {
         // Solution from example before
            location.href = "/success-page/?order=" + orderId;
         }
     
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout(purchase.purchaseId, { elementId: "plenigoCheckout" }).start();

Empty Checkout

If customer starts a checkout with a product he can’t buy based on rules, checkout will show an error message. If user wants to proceed, checkout calls plenigo.PurchaseSuccess-Event too, but not with the original orderId. It will use -2 instead:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        let orderId = e.detail.orderId;
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
         if (orderId < 0) {
            location.href = "/customer-came-again-page/";
         } else {
         // Solution from example before
            location.href = "/success-page/?order=" + orderId;
         }
     
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout(purchase.purchaseId, { elementId: "plenigoCheckout" }).start();

Additional event plenigo.PurchaseFailed is used.

Important!

If you are using dynamic urls for the page to include the checkout, take care about the maximum length of its url. The url of the page containing a checkout should not be longer than 220 chars, including protocols, ports and all query parameters.
An example: https://www.example.com/news/architecture/park-and-garden/why-everybody-needs-to-have-oaks-behind-the-house.0a2937db-e3f1-471f-8a5d-80212929ee30.html?utm_source=homepage&utm_medium=web&utm_campaign=summer_sale&utm_term=architecture&utm_content=gardening is 253 chars long and this will be too long.

Example with full html

Just put the plenigo Jacascript call somewhere in your html.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
</head>
<body>

    <header class="main">
        <h1>My 1st Checkout</h1>
    </header>


        <div id="plenigoCheckout"></div>
    
    
<!-- please replace {your_companyId} with your companyId -->
   <script src="https://static.plenigo.com/static_resources/javascript/{your_companyId}/plenigo_sdk.min.js" data-disable-redirect="true" data-lang="de"></script>
   
   <script>
// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/success-page/?order=" + e.detail.orderId ;
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout("$purchase.purchaseId", { elementId: "plenigoCheckout" }).start();
    </script>

</body>
</html>

Dealing with errors

If there are Errors in the checkout, user gets displayed error message and steps, how to proceed. If there are errors, the customer can not fix, checkout will stop with an error message. If customer is not able to restart the checkout process by simply reloading the whole page, you should implement some error handling here. You should start by listening to error events:

   <script>
// Checkout breaks with a javascript-Event one have to listen to
document.addEventListener("plenigo.Error", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.Error") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we display error message in console:
        console.info(e.detail.errorMsg);
      // reload the page to restart checkout
      location.reload(true);
         
      });
   </script>

Configuration

var config = { elementId: "plenigoCheckout" };
new plenigo.Checkout(purchase.purchaseId, config).start();

config can have the following attributes:

Passing additional data through the checkout

You can pass some additional data through the checkout. This would be usable for example to have a redirect url after the checkout.

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);        
        console.info("additional data is: ", e.detail.data);
        
        if (typeof e.detail.orderId !== "undefined") {
              location.href = e.detail.data.redirectUrl;
              return;
        }
        
        // here we redirect to a new page
        location.href = "/success-page/?order=" + e.detail.orderId ;
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout(purchase.purchaseId, { elementId: "plenigoCheckout", redirectUrl: "https://www.example.com/link/to/article.html" }).start();

If there are Errors in the checkout, user gets displayed error message and steps, how to proceed. If there are errors, the customer can not fix, checkout will stop with an error message. If customer is not able to restart the checkout process by simply reloading the whole page, you should implement some error handling here. You should start by listening to error events:

   <script>
// Checkout breaks with a javascript-Event one have to listen to
document.addEventListener("plenigo.Error", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.Error") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we display error message in console:
        console.info(e.detail.errorMsg);
      // reload the page to restart checkout
      location.reload(true);
         
      });
   </script>

Using plenigo SSO

The code above shows, how to start a plenigo checkout with you own user provider. plenigo itselfs offers you an outstanding SSO functionality to enable you using users credentials on every website. Starting it is quite easy. The plenigo Javascript comes with its SSO object: plenigo.SSO. The login or registration process is completely in an iframe. To start it, you can chose between one of these functions: login, register, forgotPassword.

Installation

The installation is equal to plenigo Javscript-SDK.

   <div id="plenigoLogin"></div>
   <!-- please replace {your_companyId} with your companyId -->
   <script src="https://static.plenigo.com/static_resources/javascript/{your_companyId}/plenigo_sdk.min.js" 
           data-disable-redirect="true" 
           data-sso="true"
           data-companyId="{your_companyId}"
           data-lang="de"></script>

Starting Registration

To start a plenigo SSO Registration you need to the following code. plenigo SSO starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.LoginSuccess", function(e) {
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/start-session/?session=" + e.detail.customerSession;
      });
      // start the process
      var config = {
         elementId: "plenigoLogin" // the DOM element you want to put the iframe in
      };
new plenigo.SSO(config).register();

Starting Login

To start a plenigo SSO Login you need to the following code. plenigo SSO starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.LoginSuccess", function(e) {
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/start-session/?session=" + e.detail.customerSession;
      });
      // start the process
      var config = {
         elementId: "plenigoLogin" // the DOM element you want to put the iframe in
      };
new plenigo.SSO(config).login();

Additional configuration examples

Javascript methods know some more configuration

// start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         email: "john.doe@example.com", // default: '' -> prefill email address in forms
         source: "news-website", // default: 'plenigoSSO' -> source for registration, to filter users by their origin
         showTabs: true, // show registration and login as tabs on top of the page
      };
new plenigo.SSO(config).login();

Starting Registration with connect feature (loginIdentifier)

If you import subscriptions into plenigo system there may be some users without an e-mail address. To enable these users to login into plenigo SSO they have to connect their imported account with their e-mail address. plenigo connect feature will lead you customer through this process.

You have to enable and configure this feature in checkout settings in the plenigo backend. To start the process you should create an additional registration process with the following settings:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.LoginSuccess", function(e) {
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/start-session/?session=" + e.detail.customerSession;
      });
      // start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         loginIdentifier: true
      };
new plenigo.SSO(config).register();

To display the connect feature in registration screen you can use property showLoginIdentifier:

      // start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         showLoginIdentifier: true // show link to connect feature in registration screen
      };
new plenigo.SSO(config).register();

You can use custom text for the link:

      // start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         showLoginIdentifier: "Click here to connect with an existing subscription" // show link to connect feature in registration screen
      };
new plenigo.SSO(config).register();

Starting Registration without using plenigo token process

You may wonder about the token process: If you register as a new user, you have to validate email address with a token plenigo sends to the new registered email. If you want to implement a different process, you can use your own implementation. Simply add a verification url to the process. You will find this url in the email templates in plenigo backend to be able to start your very own process right here. plenigo SSO starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.LoginSuccess", function(e) {
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/start-session/?session=" + e.detail.customerSession;
      });
      // start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         verificationUrl: "https://www.example.com/start-email-verification" // url that points to verification process on your site
      };
new plenigo.SSO(config).register();

Implementation

If configured plenigo adds two parameters to verification URL: verificationToken and token. You simply grab these two parameters and call: https://api.plenigo-stage.com/#operation/validateRegistration to verify user.

Starting Password forgot

To start a plenigo SSO Login you need to the following code. plenigo SSO starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.LoginSuccess", function(e) {
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/start-session/?session=" + e.detail.customerSession;
      });
      // start the process
      var config = {
         elementId: "plenigoLogin" // the DOM element you want to put the iframe in
      };
new plenigo.SSO(config).forgotPassword();

If you want to set the email address before starting password forgot process you have to change your code in the following way:

   // start the process
      var config = {
         elementId: "plenigoLogin", // the DOM element you want to put the iframe in
         email: "john.doe@example.com" // use config attribute email to set the email address in password forgot form
      };
new plenigo.SSO(config).forgotPassword();

Starting a Checkout with plenigo SSO

To start a plenigo Checkout you need to obtain a purchaseId plenigo Checkout starts in an iframe and needs some Javscript to start:

// Checkout finishes with a javascript-Event one have to listen to
document.addEventListener("plenigo.PurchaseSuccess", function(e) {
        // debugging Code:
        if (e.type !== "plenigo.PurchaseSuccess") {
          return false;
        }
        console.info("Event is: " + e.type);
        console.info(e);
        console.info("Custom data is: ", e.detail);
        // here we redirect to a new page
        location.href = "/success-page/?order=" + e.detail.orderId + "&session=" + e.detail.customerSession;
      });
// start Checkout
// put in purchaseId and elementId to start checkout
new plenigo.Checkout("$purchase.purchaseId", { elementId: "plenigoCheckout" }).login();

To start with registration instead of login, please use new plenigo.Checkout("$purchase.purchaseId", { elementId: "plenigoCheckout" }).register();.

Multi user products

plenigo enables you to sell products for families or B2B customers. These products work with an invitation. Once a multi user product is bought, customer can invite people to use it together with himself. You can start invitation process with plenigo javascript SDK.

Start invitation

The invitation process is called connection. You connect a permission to use a product with a person. The process itself will start either login or registration process. Thats why it is an enhancement of these already known processes. Connect process starts like this:

// starting with login
new plenigo.SSO({
    elementId: 'plenigoCheckout',
    connect: 'USER',
  }).login();

// starting with registration
new plenigo.SSO({
    elementId: 'plenigoCheckout',
    connect: 'USER',
  }).register();

You can prefill the token for your customers to skip this step in the process:

// starting with registration, prefill process and skip token form
new plenigo.SSO({
    elementId: 'plenigoCheckout',
    connect: 'USER',
    connectToken: 'E97876wef8EFGRWR',
  }).register();

If customer is already logged in, you can skip login during connection process. You need to create a transferToken to pass it into the javascript method:

// starting with registration, prefill process and skip token form
new plenigo.SSO({
    elementId: 'plenigoCheckout',
    connect: 'USER',
    transferToken: 'Jhge6jhgIRBMkjhe9'
  }).register();

Using Web-Analytics

Since the plenigo checkout is running in an iFrame, you can’t track the whole process in your analytics tool. We offer the ability to track all page loads inside of the iFrame by using Javascript Events.

// All page loads trigger this event
  document.addEventListener("plenigo.WebAnalyticsLoad", function (e) {
    // debugging Code:
    console.group("ANALYTICS");
    console.info("Event is: ", e);
    console.info("Custom data is: ", e.detail);
    console.groupEnd();
  });

The different pages are:

Using Selfservice with API v3.0

plenigo offers a complete customer selfservice portal, where users can manage their SSO profiles, payment methods and orders.

You can embedd this selfservice portal into your website with a single Javascript method: new plenigo.Snippets(plenigoTransferToken, {elementId: "plenigoSnippets"}).start();. Where plenigoTransferToken represents a secure transfer token for a plenigoSessionString.

Create a session

If you are using plenigo SSO you should already have a plenigo session string. Otherwise you have to create a plenigo session with an api call https://api.plenigo-stage.com/#operation/createCustomerSession. You can limit sessions in the plenigo backend, the default limit is 2 sessions per user. If you then create a 3rd session, you will get an error message and have to delete one of the existing sessions.

Create a transfer token

For security reasons it is not recommended to work directly with this session string in any frontend application, javascript or html, since 3rd parties will have access to it. Thats why plenigo uses a mechanism called plenigo transfer token. It is used to generate a single one time token out of a session to be able to share it. To create a transfer token use the following call: https://api.plenigo-stage.com/#operation/createTransferToken.

Starting Snippets

<div id="plenigoSnippets"></div>

<!-- please replace {your_companyId} with your companyId -->
<script src="https://static.plenigo.com/static_resources/javascript/{your_companyId}/plenigo_sdk.min.js" 
        data-disable-redirect="true" 
        data-sso="true"
        data-companyId="{your_companyId}"
        data-lang="de"></script>
<script>
   // use plenigo session to create transfer token: https://api.plenigo-stage.com/#operation/createTransferToken
   new plenigo.Snippets(plenigoTransferToken, {elementId: "plenigoSnippets"}).start();
</script>

Starting Snippets with special pages

If you want to display only one page of the selfservice, you can control it by using method

   new plenigo.Snippets(plenigoTransferToken, {elementId: "plenigoSnippets"}).open(plenigo.CONSTS.SNIPPETS.PAYMENT_METHODS);

The available constants are the following:

    PERSONAL_DATA: 'PERSONAL_DATA',
    PERSONAL_DATA_ADDRESS: 'PERSONAL_DATA_ADDRESS',
    PERSONAL_DATA_SETTINGS: 'PERSONAL_DATA_SETTINGS',
    ADDRESS_DATA: 'ADDRESS_DATA',
    PERSONAL_DATA_PASSWORD: 'PERSONAL_DATA_PASSWORD',
    ORDER: 'ORDER',
    INVOICE: 'INVOICE',
    DASHBOARD: 'DASHBOARD',
    SUBSCRIPTION: 'SUBSCRIPTION',
    PAYMENT_METHODS: 'PAYMENT_METHODS',
    BILLING_ADDRESS_DATA: 'BILLING_ADDRESS_DATA',
    DELIVERY_ADDRESS_DATA: 'DELIVERY_ADDRESS_DATA',
    CREDIT_CARD: 'CREDIT_CARD',
    BANK_ACCOUNT: 'BANK_ACCOUNT',
    PERSONAL_DATA_PROTECTION: 'PERSONAL_DATA_PROTECTION',
    TERMS_AND_CONDITIONS: 'TERMS_AND_CONDITIONS',
    NEWSLETTER: 'NEWSLETTER',
    MULTI_USER_ACCOUNTS: 'MULTI_USER_ACCOUNTS',
    OPT_IN: 'OPT_IN'

manipulate or hide Snippets navigation

You can hide navigation or toggle navigation type

   new plenigo.Snippets(plenigoTransferToken, {elementId: "plenigoSnippets", navigation: plenigo.CONSTS.SNIPPET_NAVIGATION.DEFAULT}).open(plenigo.CONSTS.SNIPPETS.PAYMENT_METHODS);

The available constants are the following:

    OFF: 'OFF', // hide navigation
    HORIZONTAL: 'HORIZONTAL', // display navigation on top of the page
    VERTICAL: 'VERTICAL', // display navigation on the left side of the page
    DEFAULT: 'HORIZONTAL', // the default setting

Disable User Data to prevent changes

If plenigo is not your SSO, customers should change their user data as there are e-mail address, password or 2-factor settings directly in your SSO. In this case you can disable or hide managing user data in self service. You simply have to enhance the configuration a bit:

{
 elementId: "plenigoSnippets",
 displaySettings: {
    SSO: {
        personalDetails: 'VIEW',
        twoFactor: 'HIDE'
    }
  }
}

You can chose from these values: SHOW, HIDE and EDIT. Here is the complete example:

   let snippetConfig = {
    elementId: "plenigoSnippets",
    displaySettings: {
       SSO: {
           personalDetails: 'VIEW',
           twoFactor: 'HIDE'
       }
    }
};

new plenigo.Snippets(plenigoTransferToken, snippetConfig).start();