PianoVX JavaScript

When integrating with PianoVX, we recommend that you drop the Piano javascript on all pages. This will enable you to track data across your entire site as well as leverage the full suite of Piano functionality.

The bare minimum required to initialize PianoVX on your page is to paste this code into the header of all of your pages:

tp = window["tp"] || [];
tp.push(["setAid", "AID"]);
tp.push(["init", function() {
    // any additional functionality you need to execute after
    // the tinypass javascript loads
}]);
(function(src){var a=document.createElement("script");a.type = "text/javascript";a.async=true;a.src=src;var b=document.getElementsByTagName("script")[0];b.parentNode.insertBefore(a, b)})("//cdn.tinypass.com/api/tinypass.min.js");

If you are developing against sandbox the script src is: sandbox.tinypass.com/api/tinypass.min.js

Be sure that the AID that you use is the correct AID from the environment that you're operating in. Be sure not to “go live” with your sandbox AID, or vice versa.

Command pattern

The PianoVX javascript leverages the command pattern for configuration and execution on the global tp object. This means that, for the purposes of these docs, there's an assumption that you have initialized the tp object thusly prior to any tp.push commands.

tp = window["tp"] || [];

This ensures that tp is initialized and tp.push(['command', arguments]); will function correctly.

In addition to the above tp initialization, don't forget that you need to drop in the Piano javascript once on the page - preferably in the <head> section of your site so that DOM polling can work effectively.

(function(src){var a=document.createElement("script");a.type = "text/javascript";a.async=true;a.src=src;var b=document.getElementsByTagName("script")[0];b.parentNode.insertBefore(a, b)})("//cdn.tinypass.com/api/tinypass.min.js");

You only need to drop in the tinypass.min.js javascript file once. Including it more than once is unnecessary and will place an unneeded burden on the end user's browser.

Multiple callbacks

It's important to put any Piano-specific functionality that you need to execute inside of a Piano init callback function. If you need to execute Piano functionality at different points during page execution, you can create multiple callbacks that will all fire after Piano is initialized.

For example, you could check access at one point on your page:

tp.push(["init", function() {
    tp.api.callApi("/access/check", {}, function(response) {
    });
}]);

And then later on, show an offer:

tp.push(["init", function() {
    tp.offer.show({
        displayMode : "modal",
        templateId : "OT12345",
        offerId : "OABCDE",
    });
}]);

This allows you to create more than one callback at various points on your page and ensure that each of them gets executed after Piano is loaded.

You can have as many init callback functions as you need; however, you only need to set the AID once, and you should only embed the tinypass.min.js once as well.

Don't forget that in these examples the tp object needs to first be initialized with tp = window[“tp”] || [];.

Asynchronous loading

By placing the Piano javascript in the header of your page, the Piano javascript will be loaded into the browser asynchronously. This allows the rest of the page to load while the browser fetches and executes the Piano javascript. To optimize the speed of delivery, we use a global CDN (Content Delivery Network) to deliver all of our assets.

By leveraging DOM polling, you can also call tp.offer.show at any point, even before div container is on the page if you are rendering inline templates. In this case, we will immediately fetch the template from our system and swap out the contents after the container is in the DOM. This provides a better end-user experience:

  • You don't have to build a “loading” indicator for inline offers
  • Users don't see a “pop” after the template is fetched from Piano

Non-production Environments

If you are operating in production, there's no need to configure the javascript endpoint or further configure what the browser should connect to for rendering offers and checking out. If you are operating in Piano sandbox, set the sandbox boolean to true on initialization.

tp.push(["setSandbox", true]);

If Piano has setup a dedicated environment for your business, you'll need to configure the endpoint manually. Ask your Piano account representative what endpoint you should use to configure the Piano javascript.

tp.push(["setEndpoint", "https://your-environment.tinypass.com"]);

Piano Accounts

If you're using Piano Accounts, you'll need to set the useTinypassAccounts boolean on the tp global object.

tp.push(["setUseTinypassAccounts", true]);

You do not need to set the UserRef or pass us any additional information. We will determine if the user is logged in or not, and present the appropriate login or registration popups necessary for checkout to proceed.

Setting the UserRef

If your users are stored in a local database - either in Wordpress, Drupal, or your own identity management system - and you're not using a third-party database like Piano ID, Janrain, or Gigya, you will need to set the userRef property on the tp global object.

tp.push(["setUserRef", "<base64-encoded, encrypted userRef>"]);

Please note that each UserRef times out after 10 minutes (we key off of the “timestamp” field to determine this) so it should be generated programmatically every time there is a request.

External Libraries

If you have external libraries that need to include on the page before executing Piano-specific functionality, you can include any external libraries.

tp.push(["addExternalLibrary", "http://your-domain.com/external.js", function() {
    // at this point, you are guaranteed to have both Piano
    // and your external javascript library loaded
}]);

Debugging

If you are operating in a non-production environment, it can be helpful to enable Piano debugging. This will increase the verbosity of debug messages in the browser's console. This can be helpful to know what is happening inside of the Piano context.

tp.push(["setDebug", true]);