Composer Actions

Show offer Management + Billing

Use the Show offer card to define when a user in your experience is shown an offer. The card combines (1) an offer (with terms or upgrade options), (2) a template that controls design, language, and functionality, and, if applicable, (3) a checkout flow that tailors the checkout or upgrade process.

There are three offer types you can show with this card. The settings are similar in some ways and different in others:

• Purchase offer

• Upgrade/downgrade offer (upgrade-option-based)

• Legacy upgrade/downgrade offer (checkout-flow-based)

Purchase offer

1. In the Title of card field, enter the card name.

2. Select offer type: Purchase offer.

Offer tab

3. In the Offer field, select a purchase offer to show to the user. The terms of this offer will be listed. You can reopen the dropdown by clicking Change or edit a selected offer by clicking the pencil icon.

3.1. For Identity Management-powered applications: For each term on the list, you can select a Checkout form to be shown to the user before the checkout proceeds. The forms are configured via custom fields.

3.2. If the offer consists of exactly one payment or registration term, a Direct checkout toggle is displayed. When ON (default), the Show offer action will bring the user directly to the term checkout (for a payment term) or the Identity Management registration form (for a registration term), without showing an offer modal.

4. Select the Checkout flow specifying the payment providers, passwordless login, and single-step checkout settings. You can leave Default checkout flow or select one you have configured in the Checkout flows menu. One checkout flow can be reused in multiple Show offer cards.

5. Set the Don’t show to users with active access toggle. When ON, users who currently have access to at least one resource connected to this offer will not see it. You can also exclude users with active access by selecting to ignore users with particular resources in the User Segmentation card. Switch to the Template tab.

Template tab

6. Click Select a template or a variant from your library and select a Purchase offer template.

7. Scroll down and define the Display mode parameters.

7.1. Type: choose between Inline on page (embedded within the page) and Modal/lightbox (an overlay that obscures content on the page).

7.1.1. Allow user to close modal: available for the Modal/Lightbox option. If deselected, the user must complete checkout for one of the terms before continuing to consume content on this page or any other pages where this experience is running. Clients often use A/B testing to determine whether a dismissible or non-dismissible offer is more effective for a given offer.

7.1.2. Selector for inline container: If you present your offer Inline on page, specify the CSS selector of the container you created for the offer. For example, to use

, enter #content-container in the Selector for inline container field. To use a class like , enter .housead. The field supports all selectors recognized by jQuery.

7.2. Delay by: Delay the offer by a set number of seconds or trigger it when the user reaches a specific scroll depth. For inline offers, scroll depth determines when the offer appears, not where; the offer always renders inside the specified container. You can view conversions and micro-conversions for this template in the Composer Conversions report. The current limit for the list of available templates displayed is 2000.

8. When ready, click Save in the top right corner. The card with its settings listed will appear on the canvas.

These settings only appear if the Lightweight templates feature is enabled on your application. Once enabled, the settings are visible for all templates, but they only take effect when a Lightweight template is selected. If you select a classic template, the lightweight settings remain visible but are greyed out, since classic templates use their own predefined styling and do not support these options.

To use the lightweight template settings, first select a Lightweight template from the template list. The settings will become editable, and any changes you make apply to the selected template only.

For more details about adding a Lightweight template or offer follow this link.

Upgrade/downgrade offer (upgrade-option-based)

1. In the Title of card field, enter the card name.

2. Select offer type: Upgrade/downgrade offer (without "Legacy").

Offer tab

3. In the Offer section, select an upgrade offer. The upgrade options of this offer and their settings will be listed. You can reopen the dropdown by clicking Change or edit a chosen offer by clicking the pencil icon.

Template tab

4. Click Select a template or a variant from your library and select an upgrade offer template.

5. Define the Display mode parameters as described for the purchase offer above.

6. When ready, click Save in the top right corner. The card with its settings listed will appear on the canvas.

For adding a Lightweight template or offer follow this link.

Legacy upgrade/downgrade offer (checkout-flow-based)

1. In the Title of card field, enter the card name.

2. Select offer type: Legacy upgrade/downgrade offer.

Offer tab

3. In the Offer field, select a purchase offer that contains a set of target terms (term_to) for your upgrade. The terms of this offer will be listed. Make sure all the terms in the offer comply with the upgrade limitations. You can reopen the dropdown by clicking Change or edit a chosen offer by clicking the pencil icon.

3.1. If the offer consists of exactly one payment term, a Direct checkout toggle is displayed. When ON (default), the Show offer action will bring the user directly to the term checkout without showing an offer modal.

4. Offer rules: Select a term to be the source term (term_from) of the upgrade (consider the upgrade limitations). The Show offer action will work for all active subscribers of this term who are going through this experience.

5. Create or select an upgrade/downgrade checkout flow specifying your upgrade settings. One checkout flow can be reused in multiple Show offer cards. Switch to the Template tab.

Template tab

6. Click Select a template or a variant from your library and select a purchase offer template.

7. Define the Display mode parameters as described for the purchase offer above.

8. When ready, click Save in the top right corner. The card with its settings listed will appear on the canvas.

For adding a Lightweight template or offer follow this link.

Show form  ID ONLY

The Show form card can be used to display any custom forms that you have created to your users. Most applicable for progressive profiling purposes, you can use this card to collect user information at any point in the user flow. You cannot select the My Account form.

This card will not display the registration fields (first name, last name, email, and password) to users who are already logged in. If an unregistered or signed-out user triggers this card, it will first display the login modal and it will display the registration form with the custom fields if the user indicates they do not have an account.

We recommend using this card only for a segment that targets logged-in users as a means for progressive profiling. Additionally, we recommend attaching this card to a pageview meter that executes in increments so your dedicated users aren't continuously being shown a form.

You can select a form:

As well as a Identity Management template or variant that should be displayed to users:

In addition, you can also set the modal width if this display type is selected, choose whether or not the form is displayed to users with access, and indicate whether users should be prompted to complete fields that they have already completed.

Show template

The Show Template card functions much like Show offer, except a Show template card, contains no terms. A user, therefore, cannot go through the Management + Billing checkout process by being shown a template alone. Show template is primarily used for three reasons:

1. to direct users to a third-party checkout process (for clients using Composer without Management + Billing)

2. to display marketing messages (such as advertising an event)

3. to ask users to perform actions that don't require converting on a term (such as disabling ad blockers)

The Display mode, Template, Delay by, and Selector for inline container settings within the Show Template work exactly the same as those within Show offer. For more information about how these settings work, see the Show offer documentation above.

You can view conversions and microconversions that occur on this template in the Composer Conversions report.

Apply CSS

Apply CSS allows you to dynamically change the appearance of your website. This is frequently used to hide "please subscribe" buttons for those users who are already subscribers or to replace those buttons with new ones cross-selling additional products to that paying audience. We've also seen clients use Apply CSS to change a site's navigation so premium content is prominently displayed to those users who have access to that content.

Non-site action

The Non-site action card is mainly used to finish experience branches where you are not changing the user experience, but it also creates a nonSite JavaScript event that you can listen for and perform some action in response to. Here's the event listener code for the nonSite event:

tp.push(["addHandler", "nonSite",
    function(eventParams, cardParams, contextParams) { ...
    }
]);

If you add this code to your website, the event listener code will be executed when a nonSite event is triggered. The nonSite event will be triggered regardless of name given on the non-site action card. If you wanted to know exactly which non-site action was executed, you could use the cardParams parameter in the event listener.

A client not using Management + Billing might use the non-site action event to trigger a third-party checkout process, send data to a third-party analytics system, or activate some other logic already implemented within the scope of their site. Since the non-site action JavaScript event does nothing unless a publisher captures the event and takes some action in response, this card is frequently used for control groups during A/B tests.

Run JS

The Run JS card allows you to trigger any custom JavaScript functions or scripts you've defined within the scope of your site. We've seen this card used to:

• trigger a reminder banner informing users how many free views they have left.

• redirect users to a dedicated subscription page rather than popping up an offer.

• send data to third-party analytics systems.

• capture third-party conversions.

If you prefer not to use the Set cookie card for any reason, Run JS can also be used to set a cookie of your own.

When using Action cards in combination, keep in mind that actions are triggered on the canvas synchronously from top to bottom. That means you could use a Run JS card to create a new HTML element and then insert a template into that newly created element using a Show Template card. But the RunJS card would need to be above the Show Template card on the canvas in order for the Run JS element to have loaded prior to the template firing.

The Run JS code runs within the scope of your website, not within the scope of Piano. However, when you use the card, there is some additional information from within Piano's system that is made available. Here, for example, is the full JavaScript an alert('hello world') function placed inside a Run JS card would create within your site (with example values):

(function() {
    var context = {
        "experienceId": "EX44K1BHE2K6",
        "executionId": "268f5546-4211-4244-87af-9c20af933137",
        "trackingId": "{jcx}H4sIAAAAAAAAAF2PW0vDQBCF_8s-d2Fv2UvfFFqJYku1Fqr4MNmdbRfSNHSTWBD_u6mioC_D4cx85zDvBFIgU7Lehht7vze4JRPSwg43Cd_Ky0YwbijjlDvKFR210NSManCljT2uHhazZVUPKwpMOwzBShUiBBFlUQC3Kmjt0TKtx2A8t3hK2HicndH3XTo23x3axqJQmirB-TiUotZApM4LBtFJyaX5g1_5X_bUN7d5vmHFcv14t9w-ldyNp7mtU7fG3OUyZDJ9eZ2QDg9tDR1eqKav6wnxcGgh7Zr8Ywwpp-4rdaD__taUOapkQSWalK_VIT3veV7MjxQiA8tQuEqACM56VlkpjTRaV1w4IB-fsQ_YbGUBAAA",
        "splitTests": [],
        "currentMeterName": null,
        "user": {
            "uid": "anon",
            "firstName": null,
            "lastName": null,
            "email": null
        },
        "region": "NY",
        "countryCode": "US",
        "accessList": []
    };
    var custom = {
        "host": "example.com",
        "pianoLoggedOut": null
    };
    alert('hello world');
})();

As you can see, within the Run JS scope you have access to contextual variables of various sorts: experience variables, trackingId (which can be used to log third-party conversions), user variables, and information about any A/B tests you have running. You also have access to any custom variables you've set.

If you call a template via the Run JS card, conversions and microconversions that occur on the called template will not appear in the Composer Conversions report.

Run JS Presets

Run JS Presets allow you to save and manage reusable JavaScript scripts that can be applied across multiple branches and experiences within the same app. Instead of duplicating Run JS cards with similar logic, you can centralize scripts as presets and reuse them, while still retaining the ability to customize each individual Run JS card.

Presets are visible and usable across all applications within your merchant account, making cross-app reuse seamless without any additional configuration.

Saving a Run JS script as a preset 

You can save any existing Run JS script as a preset directly from the Run JS card. 

How it works 

1. Open a Run JS card and add or edit a script 

2. Click Save as a preset
   

3. In the modal:

   • Enter a Preset name 

   • Enter a Description 

4. Click Save 

Important notes 

• JavaScript syntax is validated when saving; any errors may be highlighted

• Preset names must be unique within the app 

• If a duplicate name is used, you will see:

  “A preset with this name already exists. Please choose a different name to save your preset.”

Once saved, the preset becomes available for reuse across all applications within your merchant account.

Using an existing Run JS preset 

You can apply any saved preset to a Run JS card, including presets created in other applications within your merchant account.

How it works 

1. Open a Run JS card 

2. Click Presets
   

3. Browse or search the full list of available presets from all accessible applications

   

4. Select a preset to apply it to the card 

After applying a preset 

• The preset’s JavaScript code is copied into the Run JS card

• The script is fully editable

• Editing the script does not modify the original preset

About the application selector

Each preset displays the icon of the application it belongs to, so you can identify its source at a glance. To narrow the list, choose an application from the selector; only presets from that application will be shown. Selecting All apps restores the full cross-application list.

Editing an existing Run JS preset 

You can update an existing preset's name, description, and script. Edit access is determined by preset ownership, a preset can only be edited from the application it was originally created in.

How it works 

1. Open a Run JS card 

2. Click Presets

   

3. Locate the preset you want to edit

   

4. Click the pencil icon next to the preset

   

5. In the edit modal, update:

   • Preset name 

   • Description 

   • JavaScript code

     

6. Save your changes 

Notes

• The pencil icon only appears for presets owned by your current application. If a preset was created in a different application, it can be selected and used, but not edited from your current application.

• To edit a preset owned by another application, log into that application directly.

• Each application can have up to 256 Run JS Presets. 

Set cookie

The Set cookie card makes it easy to create cookies on select users’ browsers based on those users’ behaviors and actions. After a readable cookie has been set, you can target or ignore those users by specifying cookies on the User Segment card. All cookie fields are detailed below.

Set readable cookie: The toggle determines whether or not Piano can read the cookie. If the cookie is set to readable, Composer will read its value on the next page execution and you will be able to target users by specifying the cookie and value in the User Segment card. If a cookie is set to non-readable, you will not be able to target based on this cookie because Composer will not read the cookie. A non-readable cookie is a regular browser cookie that you can use in whatever manner you see fit using your own page code.

_pc_: This prefix is only shown for readable cookies. The “pc” prefix stands for “piano cookie” and Composer only reads cookies that include this prefix. For example, if you were to enter a cookie name of "mycookie", Composer would set a cookie with the name "mycookie" in case of a non-readable cookie and "_pc_mycookie" in case of a readable cookie.

Value: The value of the cookie.

Path: Tells the browser the scope of the cookie. By default it’s "/", which means the cookie will be available on any page on your domain.

Session cookie: If this setting is toggled on, the cookie will expire at the end of the session.

Domain: Tells the browser the scope of the cookie. You could, for example, specify a sub-domain and only have the cookie available within that scope.

Expiration: When the cookie expires (if Session cookie is toggled off). Value can be set in seconds, minutes, hours, days, months, or years.

Show newsletter signup ESP ONLY

The Show newsletter signup card can be used to display any newsletter signup template that you have created to your audience. The signed up emails are placed into active ESP mailing list(s) that have been selected in this card.

Similar to the Show offer card, the Show newsletter signup card will support “Modal” and “Inline” display. If you select modal, you'll have the additional option of deciding whether or not you want your newsletter to be dismissible.

In case you don't want to show this template to users who already have signed up for a newsletter during their current browser session, you can enable the following toggle:

Show recommendations C1x ONLY

The Show recommendations card can be applied to the display content recommendations that you have created in Piano Content. A content module must be created first before you are able to use this card. There can only be one content module selected at a time.

Similar to the Show offer card, the Show recommendations card will support "Modal" and "Inline" display. If you select modal, you'll have the additional option of deciding whether or not you want your recommendations to be dismissible.

Show push signup ESP ONLY

In this card, you have the option to intercept users before the generic browser notification opt-in prompt displays, with a fully customized template to drive push campaign enrollment.

Once you have added the Push signup card to your Experience, you can select the push list (configured in ESP) you wish to link the action to. You can also select a template to display. Push signup templates can be configured in your Management + Billing template library.

The template selected will display to the user before the generic browser prompt. Upon opt-in, the generic browser prompt will display.

If the Don't show to users who have already opted in to notifications for your domain toggle is enabled, the template will not display to users who have already opted in to push notifications for your domain. If this toggle is disabled, the template will display.

Set response variable

This card is used to set one or more response variables for your users. The action returns variable value(s) to your frontend. The supported types are boolean, string, and integer.

After the card is executed, you can send the variable values directly to your frontend to use them outside of the Piano environment. To do that, a handler can be added to relevant pages:

tp.push(["addHandler", "setResponseVariable",

function(eventParams){
  ...
    }
]);

Last updated: July 07, 2026