Overview

The Vingd [1] popup library facilitates a nicer interaction of your users with Vingd. In a standard-sized popup window, it will happily handle user purchases, rewarding, and login (to your site) via Vingd.

Confirming a purchase, redeeming a voucher or logging in to your site via Vingd identity provider can always be accomplished by redirect her to the Vingd frontend. Although this is the most robust way to interact with Vingd in terms of cross-browser/environment compatibility, a more fluent user experience is achieved with Vingd popup.

The popup library can be seen in action on Vingd Newspapers demo site (reference implementation), and Vingd API demo site (full source available on both sites).

A quick how-to guide

The library provides an onclick link handler that opens the Vingd frontend in a popup window (for user to confirm purchase or redeem voucher) and notifies you afterwards of the result (user action) via event callbacks you provide.

For library to work, you have to ensure a working popupURL location where Vingd frontend shall be redirecting users when they are done. The library provides an out of-the-box handler, popup.html (see the Download page) and it is critical to place it in a web accessible location on your site (or, at least, on the same domain).

Purchase confirmation

For this example let’s suppose you are running a site at http://example.com/; you already took care of enrolling objects in Vingd Registry, and you already implemented generating of Vingd Orders (if not, see Vingd API docs).

Let’s say you hosted our popup.html file at http://example.com/popup.html (this is the popupParams.popupURL).

Now just add the following in the <head> section of your page:

<script type="text/javascript" src="http://apps.vingd.com/cdn/vingd-popup/v0.8/build/main.min.js"></script>
<script type="text/javascript">
    var orderOpener = new vingd.popupOpener({
        popupURL: "http://example.com/popup.html",
        siteURL: "http://example.com",
        lang: "en",
        onSuccess: function(hwnd, args) {
            // TODO: verify purchase of 'oid' with 'token' (args.token),
            // probably via AJAX; notify user or update this page
        }
    });
</script>

popupParams.siteURL can be omitted, in which case will default to parent page URL. Later on in your document, you can provide the purchase link (you should generate an Order before that to get the Order purchase URL):

<a href="https://www.vingd.com/orders/2598/add/" onclick="return orderOpener(this)" class="vingd-purchase">
    Purchase X via Vingd!
</a>

or, if you are using jQuery:

jQuery(function($) { $(".vingd-purchase").click(orderOpener); });

By default, orderOpener will inspect href of the caller’s source element and redirect the user there (in case of purchase this is the Order URL on Vingd frontend). The practice of setting href to Order URL provides a fail-back in cases of error (or disabled JavaScript); the popup will not open - user will instead be redirected to Vingd frontend and she will still be able to confirm the purchase [2].

Note, however, that you do not have to pre-generate all orders in advance. If you need to generate user/context-specific orders on demand, you can do that from the onInit() callback. In that case though, the functionality of your site depends on JavaScript, and there is no safe fail-back.

In the example above, what remains for you to implement is the verification of purchase in your backend and displaying the requested content to the user. Put it in (call it from) your onSuccess() callback.

For more advanced scenarios, bear in mind the library enables you to have different openers (orderOpeners) for different objects. That way you can handle individual purchases differently.

Redeeming vouchers

Using Vingd vouchers is somewhat simpler than confirming purchases, in a sense that handling onSuccess callback is not critical for user to receive vingds.

The minimal code for redeeming a voucher in popup is analogous to the one above (assuming we’re still on the example.com site):

<script type="text/javascript" src="http://apps.vingd.com/cdn/vingd-popup/v0.8/build/main.min.js"></script>
<script type="text/javascript">
    var voucherOpener = new vingd.popupOpener({
        popupURL: "http://example.com/popup.html",
        siteURL: "http://example.com",
        lang: "en"
    });
</script>

The callbacks like onSuccess, onCancel, etc. are optional. They can be added to the popupParams (after siteURL, for example), like this:

onSuccess: function() {
    alert("Voucher used successfully.");
},
onCancel: function() {
    alert("Voucher not used.");
},
onError: function(hwnd, args) {
    alert("Failed to cash-in the voucher: " + args.msg);
}

Dynamic voucher (order) fetch

Vouchers (as orders) can be generated on demand, when popup launches and calls the onInit() callback. You should amend popupParams above with:

onInit: function(hwnd, args, onDone) {
    $.get('ajax/voucher.php', function(data) {
        onDone(data.voucherURL);
    });
}

For further details, please see the documentation of vingd() class. The good starting point is vingd.popupOpener() function.

Footnotes

[1]We’re in process of re-branding as Vingd. Libraries may still have some internal references to the old name, “knopso”, but “on the outside”, towards the end-user, we are building the Vingd brand.
[2]In the redirect mode (contrast with popup mode), after a successful purchase on Vingd frontend, user is redirected to object_url, an URL given upon registering the object with Vingd Registry.

Table Of Contents

Previous topic

Vingd Popup Library

Next topic

Download

This Page