Composer JavaScript Integration

Composer Integration

Select “Composer” in the “Products” tab on the dashboard and then click the button labeled “Integrate” located on the upper right of the tool bar. Clicking “Integrate” will expose a JavaScript code snippet, take that snippet and place it within the head tags on all the pages of your site. Most of the popular content management systems (CMSs) will have a simple interface that allows you to enter code in one place to have it applied to your entire site.

After you have placed the code in your head tags, you can build Experiences without writing or copying code.

Custom Variables and Tags

To use custom variables or page tags in Composer you need to pass them to our JS library during initialization. You can also use custom variables in templates.

When you load Composer via the provided code snippet - it already does a lot of initialization, like setting the application ID or API endpoint (sandbox or production). So in the ideal case, passing variable on the page would look like this:

<script>
	// Get tp object
	tp = window["tp"] || [];
	// Add custom variable. The first parameter would be the name, and the second is the value
	tp.push(['setCustomVariable', 'name', 'value']);
	// In this case we'll set the variable named "blukai_segment" to the value of "likely_subscriber"
	tp.push(['setCustomVariable', 'bluekai', 'likely_subscriber']);
	// Also setting tags
	tp.push(['setTags', ['Economy', 'Jobs', 'US' ]]);
	// Set Zone. Zone can be used to indicate the AAM platform
	tp.push(['setZone', 'Web']);
</script>

And if you want to use these variables in Composer - it can look like this:

And as for Tags, it will look like this:

Composer JavaScript Callbacks

Checkout events

Complete

The checkoutComplete event fires when the conversion process has completed. If you are leveraging webhooks for access control, Piano strongly recommends that you implement this method to update your local datastore, since webhooks are sent asynchronously.

tp.push(["addHandler", "checkoutComplete", function(conversion){ 
   // Your code after successful purchase
}]);

It will return a conversion object similar to:

{
   "chargeAmount": 1.99,
   "chargeCurrency": "USD",
   "cookie_domain": "yoursite.com",
   "email": "[email protected]",
   "expires": 1456245899, // Timestamp of the access expiration
   "promotionId": null, // If promo code was used, this will be the ID of promotion
   "rid": "RPUV65H",
   "startedAt": "2016-02-22T16:44:59.777+0000",
   "termConversionId": "TCS0ELTCW3LR",
   "termId": "TMP9UFZB97RJ",
   "token_list": "{jax}1xc23NBegZededpBk5n0AZ...",
   "uid": "O6EDJtQiZz",
   "user_token": "{jax}hoZoQRENxtZWaZF2ekHT_b...",
}

Close

The checkoutClose event fires when the modal or popup closes. There should be no assumption that the user has checked out at this point. You could hook into this event to, for example, present to the user another abandonment prevention offer.

tp.push(["addHandler", "checkoutClose", function( event ){
    // The event parameter contains information about the state of closed modal
    switch (event.state){
        case 'checkoutCompleted':
            // User completed the purchase and now has access
            // Usually it's a good practice to reload the page
            break;
        case 'alreadyHasAccess':
            // User already has access
            // This state could be a result of user logging in during checkout process
            // Usually it's a good practice to reload the page as well
            break;
        case 'close':
            // User did not complete the purchase and simply closed the modal
    }
}]);

Custom event

The checkoutCustomEvent can be used to track custom events within the checkout process. When editing your checkout templates, any element with the external-event will trigger an event to be fired on click. In the case where you want to embed custom links or actions that a user might do that require the main publisher site to handle the event, external-event should be used. Below is a sample snippet from a checkout template

<span external-event="login">Click here to login</span>

And here is the the javascript configuration for listening to the custom event.

tp.push(["addHandler", "checkoutCustomEvent", function(event){
   switch(event.eventName) {
       case "login":
           window.location.href = "/login";
           break;
   }
} ]);

Error

The checkoutError event executes whenever the unexpected error has been encountered during the checkout.

tp.push(["addHandler", "checkoutError", function(errorData){
   alert("Error! " + errorData.message);
}]);

Show Offer

The Show Offer event fires whenever a user is presented with an offer.

tp.push(["addHandler", "showOffer", function( offerParams ){
    // Your code after offer has been shown
} ]);

The “offerParams” attribute passed to a callback function has the same fields as parameters required for showing an offer, described here.

Show Template

The Show Template event fires whenever a user is presented with a template. Show Template is different from Show Offer, because a user cannot make a purchase in a simple template.

tp.push( [ "addHandler", "showTemplate", function ( templateParams ) {
	// Your code after template has been shown
}]);

The “templateParams” attribute passed to a callback function has the same fields as parameters required for showing an offer, described here.

User events

Login required

The loginRequired event fires when someone is not logged in and attempts to start checkout. 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 implement this callback to redirect the user to your login or registration screen, or to display the login or registration modal. Once the user is logged in, checkout can continue.

tp.push(["addHandler", "loginRequired", function(params){
  // this is a reference implementation only
  // your own custom login/registration implementation would
  // need to return the tinypass-compatible userRef inside the callback
  mysite.showLoginRegistration(function(tinypassUserRef) {
     tp.push(["setUserRef", tinypassUserRef]);
     tp.offer.startCheckout(params);
  });
 
  // this will prevent the Piano error screen from displaying
  return false;
}

Login success

The loginSuccess event fires when user completes login process using Piano ID.

tp.push(["addHandler", "loginSuccess", function(){
  // Any logic required after a successful login
}]);

Meter events

Active

The meterActive event is fired when user is being metered and still has free views. It will return the meterData object which contains information about the current meter status, it looks like this:

{
   "callback": null,
   "meterName": "DefaultMeter",
   "views": 2,
   "viewsLeft": 3,
   "maxViews": 5
}

The meterName attribute will have the same value as “Meter Name” parameter specified in composer in “Pageview meter” card.

tp.push(["addHandler", "meterActive", function(meterData){
   alert("You've seen " + meterData.views
       + " out of " + meterData.maxViews
       + " free articles. You have" + meterData.viewsLeft
       + " articles left."
   );
}]);

Expired

The meterExpired event is fired when allowed limit of views has been reached. The format of meterData parameter is the same as in meterActive event.

tp.push(["addHandler", "meterExpired", function(meterData){
   // The logic executed here could differentiate
   // Based on meterData.meterName value
}]);