Initializing the tp object
Piano leverages the command pattern for configuration and execution on the global tp object. Prior to any tp.push commands, there's an assumption that you have initialized the tp object by using this code:
tp = window["tp"] || [];
This ensures that tp is initialized and tp.push(['command', arguments]); will function correctly. You'll notice this tp initialization code in many of the code samples used in this guide.
Using init callback functions
It's important to put any Piano-specific functionality 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's JavaScript library is initialized. These callbacks can be placed anywhere on the page (in the header, in the footer, as an external script, etc).
As an example, you could check access at one point on your page:
tp.push(["init", function() {
tp.api.callApi("/access/check", {}, function(response) {});
}]);
And then, further down the page after that check access script is loaded, 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 and place them in different parts of your page while ensuring that each of them gets executed after the tp object is initialized and the Piano library is loaded.
More information on manually triggering offers with JavaScript can be found here.
Common tp.push Commands
Working in Sandbox
If you are operating within a Piano Sandbox application, you'll need to set the Sandbox boolean to true on initialization (you don't need to do anything for a Production application):
tp.push(["setSandbox", true]);
Adding External Libraries
If you have external libraries that need to include on the page before executing Piano-specific functionality, you can do so in this manner:
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
}]);
This will inject the script in the <head> of your website (not in the Piano iframe, but the website itself). After the script is injected, the callback function will be executed.
Debugging
If you are operating in Sandbox, it can be helpful to enable Piano debugging. This will increase the verbosity of debug messages in the browser's console.
tp.push(["setDebug", true]);
Piano ID
If you're using Identity Management, you'll need to set the setUsePianoIdUserProvider boolean on the tp global object to true. Like so:
tp.push(["setUsePianoIdUserProvider", 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. For more info on Identity Management, see our complete set-up guide.
Piano Go/Tinypass Accounts (Legacy)
By default, the useTinypassAccounts boolean on the tp global object is set to false. Like so:
tp.push(["setUseTinypassAccounts", false]);
Only in case you are still using the Piano Go/Tinypass Accounts legacy user management integration, you'll need to set the value to 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.
For Identity Management Accounts, the configuration is described here.