Piano Plugin

This plugin adds Piano integration which offers full Subscriptions implementations. This includes page tracking, custom data, and template rendering, including paywalls, registration, login, and account management.

Getting Started

This plugin will automatically take care of adding the Piano integration, however, some configuration is required on the brand level.

Once enabled, this plugin will create the WordPress "pages" required by Piano, i.e. "Subscribe", "My Account", and "Password Reset".

Prerequisites

The site must be set up in Piano so that an application id already exists. There is an application id for sandbox and a separate one for production.

The pmc-sportico-2020 repo has an example of how to set up this plugin in the file plugins/_config/class-pmc-piano.php.

Implementation

Use the piano_application_id filter to set the Piano application id from the theme. There is one aid for sandbox and one for production.
Use the \PMC\Piano\Plugin::get_instance()->get_script_url() function to get the Piano script url required on the site. This is used to configure Piano on all pages.
Load the plugin in the theme.

Initializing Piano on the Site

To use the features of Piano on your site, the following script must be in the head tag of every page. This is handled by the plugin:

<!-- Piano Application Script -->
load_tp: function () {
    var script = document.createElement('script');
    script.type = 'text/javascript';
    script.async = true;
    script.src = pianopmc.script_url;
    document.getElementsByTagName('head')[0].appendChild(script);

},
<!-- End Piano Application Script -->

Use the get_script_url function to get the script url. You must first add piano_application_id filter which sets the aid for the given brand and environment (qa or prod). The plugin sets the global script_url variable via the get_pmc_piano_data function.

For production we load https://experience.tinypass.com/xbuilder/experience/load?aid= (opens in a new tab) and sandbox https://sandbox.tinypass.com/xbuilder/experience/load?aid= (opens in a new tab)

Subscriptions Pages

This plugin creates subscribe-control pages which are required for a Piano integration.

List of pages created by this plugin:

My Account
- site.com/my-account
Password Reset
- site.com/password-reset
Subscribe
- site.com/subscribe

Note, while this plugin creates the Subscribe page (site.com/subscribe) the rendering of that page is the responsibility of the theme. This is primarily because each theme builds their Subscribe page differently. The present standard for Subscribe is a Larva-built template residing in the theme's page-subscribe.php file. See Sportico (opens in a new tab), Billboard (opens in a new tab), or Sourcing Journal (opens in a new tab) for references.

Custom Tags

Custom tags send to Piano whenever a page is viewed. Custom tags can contain contextual information about the page or information about the user viewing the page.

Prefixes

All custom tags sent to Piano must be prefixed with pmc-.

Piano Templates

Piano Templates are personalized sections of content that can be rendered wherever desired.

Templates must first be set up in Piano and the template id is needed to show the correct one on the page.

Template div tag

The div tag and id attribute for each template must be added to every page where it should be displayed.

Page Template Setup

Example:

...
<div id="piano-login-container"></div>
...

AMP

Piano offers ability to serve experience on AMP pages using amp-subscriptions (opens in a new tab) component.

Implementation

To add subscriptions component we need to include amp-subcriptions js to head of every amp page.

<script async custom-element="amp-subscriptions" src="https://cdn.ampproject.org/v0/amp-subscriptions-0.1.js"></script>

Subscriptions amp script uses subscription config to serve piano experiences. Config is added to head of every amp page.

Subscriptions config example:

<script id="amp-subscriptions" type="application/json">
        {
            "services": [
                {
                    "authorizationUrl": "https://sandbox.tinypass.com/xbuilder/experience/executeAmpSubscriptions?protocol_version=1&aid=<YOUR_AID>&reader_id=READER_ID&url=SOURCE_URL&referer=DOCUMENT_REFERRER&_=RANDOM",
                    "noPingback": "true",
                    "actions":{
                        "login": "https://<site-domain>/amp-login.html?reader_id=READER_ID&url=SOURCE_URL&_=RANDOM",
                        "subscribe": "https://<site-domain>/amp-subscribe.html?reader_id=READER_ID&url=SOURCE_URL&_=RANDOM",
                        "logout": "https://<site-domain>/amp-logout.html?reader_id=READER_ID&_=RANDOM"
                    },
                    "baseScore": 100
                }
            ],
            "fallbackEntitlement": {
                "source": "fallback",
                "granted": true,
                "grantReason": "METERING",
                "data": {
                    "error": true
                }
            }
        }
    </script>

More details regarding config attributes (opens in a new tab)

Authorization url for staging site : https://sandbox.tinypass.com/xbuilder/experience/executeAmpSubscriptions

Authorization url for production site : https://experience.tinypass.com/xbuilder/experience/executeAmpSubscriptions

To serve an AMP piano experience we need to place Piano AMP template and css to every amp page.

How it works

The AMP Page is loaded in the AMP viewer with some sections obscured using attributes.
The AMP Runtime calls the Authorization endpoint of all configured services.
If all services fail to respond, the fallback entitlement will be used.
The AMP Runtime uses the response to either hide or show different sections as defined by the Attributes. [ Attributes Docs ] (opens in a new tab)
Diagram reference : AMP subscriptions working with piano (opens in a new tab)

Refrence doc

Amp subscriptions component : https://amp.dev/documentation/components/amp-subscriptions/ (opens in a new tab)
Piano amp implementation : https://docs.piano.io/amp-experiences/#AMPimplement (opens in a new tab)

Open House

"Open House" is a period of time dictated by the business as a time when no subscriber features will be present on a site. This feature is employed during subscriptions-related migrations, 3rd-party outages, or possibly a marketing campaign.

This plugin provides a Cheezcap to "Enable" Open House.
- Theme Settings > Piano > Open House
During "Open House" all subscriptions touchpoints should NOT be shown to end users, e.g. Login, Subscribe, etc. .Touchpoints are to be handled by the theme by wrapping the touchpoint code with this plugin's helper function. Under-the-hood this helper reads the value of the Cheezcap.
```
<?php if ( ! \PMC\Piano\Open_House::get_instance()->is_enabled() ) : ?>
 
    <button class="js-subscription-login-link">
        Log In
    </button>
	
<?php endif; ?>
```
During open house; this plugin redirects visits from the following pages to the home page: My Account, Password Reset, and Subscribe. Under-the-hood this functionality reads the value of the Cheezcap when determining to redirect or not. This ensures that no existing user data is updated during Open House, and that no new orders are placed.

Pmc Performance Metrics Pmc Plugins