Security, Privacy, AI and CSR information for all Piano products now lives in one place. Explore our Compliance Center.
Subscriptions
English French
English French

External events

LIGHTWEIGHT TEMPLATES

Not to be confused with Events, which cover DOM handlers inside a template (onClick, onInput, etc.). This page is about events the template sends out of the widget.

What an external event is

An external event is a named notification a template sends out of the widget when the user interacts with it, optionally carrying a bag of parameters. Firing one does two things:

  • logs an auto micro conversion with event type EXTERNAL_EVENT and the event name as its event group id; this is what appears in the Conversion Report;

  • calls the publisher's customEvent handler on the host page with the event name and the params object.

JavaScript
tp.push(["addHandler", "customEvent", function (event) {
  event.eventName; // the name you passed
  event.params;    // the params object you passed
}]);

This is the same customEvent handler classic templates used, so an existing publisher integration keeps receiving events after a migration. What changes is the shape of params; see Coming from classic templates below.

What can fire one

Mechanism

Use it when

Documented in

PianoExternalEvent

you need to fire an event from arbitrary markup, a plain <button>, a link, a form's submit button, a whole card

Components → PianoExternalEvent

externalEventName + externalEventParams on a Piano button

you are already using a Piano button component

Components → Buttons

Both are current, and both are the same mechanism underneath. Pick whichever fits the markup you already have. There is no third way: the classic external-event-* HTML attributes do nothing in a Lightweight template, whether written in the JSX tab or set from the JS tab with setAttribute().

Buttons that accept externalEventName / externalEventParams

PianoExternalEvent

Attribute name

type

required / optional

default value

description

name

string

required


external event name

params

object

optional

""

parameters sent with the event

children

JSX.Element

required


the markup whose clicks fire the event

class / id / classList / style

N/A

optional


applied to the wrapper element

PianoExternalEvent renders a wrapper <div> around its children and listens for clicks on it in the capture phase. Two consequences worth knowing up front:

Any click inside the wrapper fires the event, not only a click on the button; keep the wrapper tight around the element you mean.

The event is sent before the click handlers of the wrapped content run.

React JSX
<PianoExternalEvent name="cta-click" style={{ display: "contents" }}>
  <button type="submit">Continue</button>
</PianoExternalEvent>

Example 1: static parameters

Everything is known at authoring time, so only the JSX tab is involved.

React JSX
<PianoExternalEvent
  name="cta-click"
  params={{ placement: "sidebar", campaign: "[%% campaign_id %%]" }}
>
  <button type="button">Continue</button>
</PianoExternalEvent>

Example 2: parameters read from the form at click time

This is the case that needs both tabs. The JSX tab declares the markup and the params; the JS tab declares the variables the markup binds to and any helpers the params call. Two kinds of binding appear here: ref, when the value is read straight off the DOM at fire time, and a signal, when the template has to render the value as well.

JS tab

JavaScript
// read off the DOM at fire time
let comment;
let topicA;
let topicB;

// a signal, because the subject is rendered as well as sent
const [subject, setSubject] = createSignal("");

const selectedTopics = () =>
  [
    topicA?.checked ? "[%% topic_a_id %%]" : "",
    topicB?.checked ? "[%% topic_b_id %%]" : "",
  ]
    .filter(Boolean)
    .join(",");

JSX tab

React JSX
<form>
  <label for="comment">Comment</label>
  <input id="comment" type="text" ref={comment} required />

  <label>
    <input type="checkbox" ref={topicA} /> Topic A
  </label>
  <label>
    <input type="checkbox" ref={topicB} /> Topic B
  </label>

  <label for="subject">Subject</label>
  <input
    id="subject"
    type="text"
    maxlength="60"
    onInput={(e) => setSubject(e.currentTarget.value)}
  />
  <p>{subject().length} / 60</p>

  <PianoExternalEvent
    name="[%% event_name %%]"
    params={{
      comment: comment?.value,
      topicIds: selectedTopics(),
      subject: subject(),
      formId: "[%% form_id %%]",
    }}
    style={{ display: "contents" }}
  >
    <button type="submit">Send</button>
  </PianoExternalEvent>
</form>

How the two tabs connect

  1. The JS tab is the component body. Your JS tab and the JSX tab are compiled into the same function, in that order. Anything you declare at the top level of the JS tab is visible to the JSX; anything you hide inside an IIFE is not. FAQ: How does the JS tab interact with the JSX tab?

    JavaScript
    // ✅ visible to the JSX
    let comment;
    
    // ❌ invisible to the JSX
    (function () {
      let comment;
    })();
    
  2. ref={x} assigns the DOM element to x. It is a plain assignment, not a signal setter, so x must be declared with let or var at the top level of the JS tab. const throws, and so does an undeclared name: the template code runs as an ES module, in strict mode, so the assignment throws a ReferenceError at render time instead of creating a global. FAQ: What is ref and how do I use it? and Which variables from the JS tab can the JSX see, and how do I declare them?

  3. A signal is the other option, and the one to pick when the value also drives rendering; the character count above cannot be written with a ref. createSignal and the other Solid primitives the JS tab receives batch, catchError, createComputed, createDeferred, createEffect, createMemo, createReaction, createRenderEffect, createResource, createSelector, mapArray, mergeProps, on, onCleanup, onMount and splitProps- are already in scope, so no import is needed; other Solid primitives, such as untrack, are not in scope.

  4. params is evaluated when the event fires, not when the template renders. That is what makes comment?.value, subject() and selectedTopics() return what the user actually typed and picked. You do not need to mirror form state into variables on every onChange; read it inside params.

  5. [%% field %%] content fields are substituted in the JS tab too. Substitution runs over all three tabs, HTML/JSX, CSS and JS, before the template reaches the browser, and the editor offers content-field autocompletion in all three. FAQ: Are content fields substituted in the JS tab too?

Buttons

A Piano button fires the event on its own click, before your onClick runs. No wrapper element is added.

React JSX
<PianoPrimaryButton
  onClick={(e) => context.login()}
  externalEventName="header-login"
  externalEventParams={{ placement: "header" }}
>
  <T>Log in</T>
</PianoPrimaryButton>

The example uses PianoPrimaryButton, but externalEventName and externalEventParams work the same way on every button in the list above. PianoStartCheckoutButton and PianoBuyAsAGiftButton also add termId, taken from their term prop, to externalEventParams, so you don't have to pass it yourself.

Runtime parameters work exactly as they do for PianoExternalEvent; externalEventParams is evaluated at click time, so it can read live DOM values bound with ref:

JS tab

JavaScript
let promoCode;

JSX tab

React JSX
<input type="text" ref={promoCode} placeholder="Promo code" />

<PianoPrimaryButton
  onClick={(e) => context.startCheckout({ term: item })}
  externalEventName="promo-applied"
  externalEventParams={{ code: promoCode?.value, termId: item.termId }}
>
  <T>Subscribe</T>
</PianoPrimaryButton>

Note. The example above uses PianoPrimaryButton, but externalEventName and externalEventParams behave identically on every button listed above: PianoPrimaryButton, PianoSecondaryButton, PianoOutlineButton, PianoGhostButton, PianoIconButton, PianoCloseButton / CloseButton, PianoBackButton, PianoStartCheckoutButton and PianoBuyAsAGiftButton.
Two of them add a parameter of their own: PianoStartCheckoutButton and PianoBuyAsAGiftButton merge termId (taken from their term prop) into externalEventParams, so you do not have to pass it yourself.

Coming from classic templates

In a classic (AngularJS) template, an external event was an attribute directive:

HTML
<button external-event="cta-click"
        external-event-event-label="sidebar"
        external-event-plan="{{ selectedPlan }}">
  Continue
</button>

The classic runtime read every attribute whose name began with external-event-, turned the dash-separated suffix into a camelCase key with a lowercased first letter, and used the attribute's (interpolated) string value:

Classic attribute

params key

external-event-href

href

external-event-event-label

eventLabel

external-event-argument-1

argument1

external-event-clicktext

clicktext

Because these were HTML attributes, every classic parameter was a string, and the browser lowercases attribute names, so external-event-eventLabel produced the key eventlabel, not eventLabel. In a Lightweight template, params is a real JavaScript object: keys keep their case, and values keep their types.

The classic directive also fires on submit as well as click, on the element itself. PianoExternalEvent listens for click only, on its wrapper. Clicking a submit button (including implicit submission by pressing Enter in a field) still fires it; a form submitted from JavaScript does not.

Mapping table

Every classic form with its Lightweight equivalent, written out as code. Both Lightweight columns do the same thing: the PianoExternalEvent wrapper in one, the externalEventName / externalEventParams props on a Piano button in the other; pick whichever fits the markup you already have. Rows about a single attribute show only the lines that differ, and where a row needs template-side state, the JS tab snippet follows the JSX one.

Classic (piano-vx)

Lightweight PianoExternalEvent equivalent

Lightweight Button ExternalEvent equivalent

HTML
<button external-event="cta-click">
  Continue
</button>
React JSX
<PianoExternalEvent name="cta-click">
  <button type="button"><T>Continue</T></button>
</PianoExternalEvent>
React JSX
{/* onClick is required even when the
    event is all you want */}
<PianoPrimaryButton
  onClick={() => {}}
  externalEventName="cta-click"
>
  <T>Continue</T>
</PianoPrimaryButton>
HTML
<button external-event="cta-click"
        external-event-placement="sidebar">
React JSX
<PianoExternalEvent
  name="cta-click"
  params={{ placement: "sidebar" }}
>
React JSX
<PianoPrimaryButton
  onClick={() => {}}
  externalEventName="cta-click"
  externalEventParams={{ placement: "sidebar" }}
>
HTML
<!-- HTML lowercases attribute names,
     so write dashes, never
     external-event-eventLabel -->
external-event-event-label="hero"
React JSX
{/* the key keeps its camelCase */}
params={{ eventLabel: "hero" }}
React JSX
externalEventParams={{ eventLabel: "hero" }}
HTML
<!-- digits pass through:
     argument-1 becomes argument1 -->
external-event-argument-1="42"
React JSX
params={{ argument1: "42" }}
React JSX
externalEventParams={{ argument1: "42" }}
HTML
<!-- one attribute per parameter -->
external-event="cta-click"
external-event-placement="sidebar"
external-event-event-label="hero"
React JSX
{/* one object instead of N attributes */}
params={{
  placement: "sidebar",
  eventLabel: "hero",
}}
React JSX
externalEventParams={{
  placement: "sidebar",
  eventLabel: "hero",
}}
HTML
<!-- a value the widget already had -->
external-event-app="{{ app.name }}"
React JSX
params={{ appName: context?.app?.name }}
React JSX
externalEventParams={{ appName: context?.app?.name }}
HTML
external-event="[%% event_name %%]"
external-event-campaign="[%% campaign_id %%]"
React JSX
name="[%% event_name %%]"
params={{ campaign: "[%% campaign_id %%]" }}
React JSX
externalEventName="[%% event_name %%]"
externalEventParams={{ campaign: "[%% campaign_id %%]" }}
HTML
<!-- value the user typed, via ng-model -->
<input ng-model="code">
<button external-event="promo"
        external-event-code="{{ code }}">
React JSX
<input type="text" ref={code} />

<PianoExternalEvent
  name="promo"
  params={{ code: code?.value }}
>
  <button type="button"><T>Apply</T></button>
</PianoExternalEvent>
JavaScript
// JS tab — ref assigns the element itself,
// so the value is read off the DOM on click
let code;
React JSX
<input type="text" ref={code} />

<PianoPrimaryButton
  onClick={() => {}}
  externalEventName="promo"
  externalEventParams={{ code: code?.value }}
>
  <T>Apply</T>
</PianoPrimaryButton>
JavaScript
// JS tab
let code;
HTML
<!-- same thing; the scope held the value
     and other markup could read it too -->
<input ng-model="code">
<span>{{ code }}</span>
<button external-event="promo"
        external-event-code="{{ code }}">
React JSX
{/* no ref: a signal holds the value, so the
    rest of the template can render it too */}
<input type="text" onInput={(e) => setCode(e.currentTarget.value)} />
<span>{code()}</span>

<PianoExternalEvent
  name="promo"
  params={{ code: code() }}
>
  <button type="button"><T>Apply</T></button>
</PianoExternalEvent>
JavaScript
// JS tab — createSignal is already in scope,
// no import needed
const [code, setCode] = createSignal("");
React JSX
<input type="text" onInput={(e) => setCode(e.currentTarget.value)} />

<PianoPrimaryButton
  onClick={() => {}}
  externalEventName="promo"
  externalEventParams={{ code: code() }}
>
  <T>Apply</T>
</PianoPrimaryButton>
JavaScript
// JS tab
const [code, setCode] = createSignal("");
HTML
<!-- conditional inside the interpolation -->
external-event-plan="{{ isAnnual ? 'annual' : 'monthly' }}"
React JSX
params={{ plan: plan() }}
JavaScript
// JS tab — a ternary written straight into
// params compiles to a function, not a value,
// so keep it here
let isAnnual;
const plan = () =>
  isAnnual?.checked ? "annual" : "monthly";
React JSX
externalEventParams={{ plan: plan() }}
JavaScript
// JS tab
let isAnnual;
const plan = () =>
  isAnnual?.checked ? "annual" : "monthly";
HTML
<!-- legacy object bag -->
external-event-params="{{ { name: app.name, url: app.url } }}"
React JSX
{/* the bag's keys become ordinary keys */}
params={{
  name: context?.app?.name,
  url: context?.app?.url,
}}
React JSX
externalEventParams={{
  name: context?.app?.name,
  url: context?.app?.url,
}}
HTML
<!-- a NON-object value stayed under the
     literal key "params" -->
external-event-params="{{ app.url }}"
React JSX
params={{ params: context?.app?.url }}
React JSX
externalEventParams={{ params: context?.app?.url }}
HTML
<!-- empty element, label came from the
     attribute -->
<div external-event="cta"
     external-event-clicktext="Read more"></div>
React JSX
{/* label goes into children; keep the
    parameter if the publisher reads it */}
<PianoExternalEvent
  name="cta"
  params={{ clicktext: "Read more" }}
>
  <button type="button"><T>Read more</T></button>
</PianoExternalEvent>
React JSX
<PianoPrimaryButton
  onClick={() => {}}
  externalEventName="cta"
  externalEventParams={{ clicktext: "Read more" }}
>
  <T>Read more</T>
</PianoPrimaryButton>
HTML
<!-- the publisher's handler did the
     navigation -->
<div external-event="banner"
     external-event-href="[%% target_url %%]">
  Read more
</div>
React JSX
{/* the wrapper never navigates — <A> does,
    and tracks the link as well */}
<PianoExternalEvent
  name="banner"
  params={{ href: "[%% target_url %%]" }}
>
  <A href="[%% target_url %%]"><T>Read more</T></A>
</PianoExternalEvent>

Not applicable; a button does not navigate. Use the wrapper with <A>.

HTML
<!-- classic fired on click AND submit -->
<form external-event="signup-submit">
  <button type="submit">Send</button>
</form>
React JSX
{/* the wrapper listens for click only —
    put it around the submit button */}
<form>
  <PianoExternalEvent
    name="signup-submit"
    style={{ display: "contents" }}
  >
    <button type="submit"><T>Send</T></button>
  </PianoExternalEvent>
</form>
React JSX
{/* Piano buttons render type="button" and
    never submit a form — do it in onClick */}
<PianoPrimaryButton
  onClick={() => sendForm()}
  externalEventName="signup-submit"
>
  <T>Send</T>
</PianoPrimaryButton>
HTML
<!-- custom-script, at runtime -->
btn.setAttribute('external-event-code', code);
React JSX
{/* not supported: parameters come from the
    prop, which is read at click time */}
params={{ code: code?.value }}
JavaScript
// JS tab
let code;
React JSX
externalEventParams={{ code: code?.value }}
JavaScript
// JS tab
let code;
HTML
<!-- the attribute only notified;
     ng-click did the closing -->
<button ng-click="close()"
        external-event="close">×</button>
React JSX
{/* closing already logs a "close" external
    event, so no wrapper is needed */}
<button
  type="button"
  onClick={() => context.close()}
>×</button>
React JSX
{/* it already closes the widget and logs
    a "close" external event */}
<PianoCloseButton />
HTML
<!-- the attribute only notified;
     ng-click started the login flow -->
<button ng-click="login()"
        external-event="login">
  Log in
</button>
React JSX
{/* same split: the wrapper notifies,
    the context call acts */}
<PianoExternalEvent name="login">
  <button
    type="button"
    onClick={() => context.login()}
  ><T>Log in</T></button>
</PianoExternalEvent>
React JSX
<PianoPrimaryButton
  onClick={() => context.login()}
  externalEventName="login"
>
  <T>Log in</T>
</PianoPrimaryButton>
HTML
<!-- the attribute only notified;
     ng-click started the checkout -->
<button ng-click="startCheckout(term)"
        external-event="startCheckout"
        external-event-term-id="{{ term.termId }}">
  Subscribe
</button>
React JSX
<PianoExternalEvent
  name="startCheckout"
  params={{ termId: item.termId }}
>
  <button
    type="button"
    onClick={() => context.startCheckout({ term: item })}
  ><T>Subscribe</T></button>
</PianoExternalEvent>
React JSX
{/* termId is merged into the params for you */}
<PianoStartCheckoutButton
  term={item}
  externalEventName="startCheckout"
>
  <T>Subscribe</T>
</PianoStartCheckoutButton>

Gotchas

  • A parameter expression that throws swallows the event. comment.value where comment was never bound (the input is inside a <Show> that has not rendered) throws at click time; the click still does whatever else it does, but no event and no conversion are recorded. Use optional chaining comment?.value inside params. Optional chaining does not help when the name itself is not visible to the JSX (declared inside an IIFE, for example): reading an undeclared name throws a ReferenceError with or without ?., so declare it at the top level of the JS tab. A Piano button is different: it reads externalEventParams before its own onClick (and before PianoCloseButton, PianoBackButton, PianoStartCheckoutButton and PianoBuyAsAGiftButton do their own work: close, back, checkout), so a throw there cancels the whole click. It also reads externalEventParams while it renders, so use optional chaining inside externalEventParams too.

  • params is not reactive state. It is read once per fire. Do not expect a createEffect to re-send anything.

  • Wrapper vs. button. If both PianoExternalEvent and a button's externalEventName are present around/on the same element, two events fire. Pick one.

Tracking IDs & conversion attribution (_ptid)

External events are also how a Lightweight template feeds conversion attribution; a template on the article starts a journey, the visitor converts later on a separate landing page, and the tracking ID is what ties that later conversion back to the experience and variant that started it. This section covers the two auto micro conversions a template can log, how the tracking ID reaches a link, and how to read it yourself.

This is the Lightweight-template counterpart to the Classic page How to record conversions with the tracking parameter _ptid when a button inside a Piano template is clicked. The Classic recipe, a Run JS card reading params.trackingId from the checkoutCustomEvent callback and wiring external-event-* attributes, does not work in LWT (the external-event-* attributes do nothing here). Use what is below instead.

A template can log two different auto micro conversions; keep them apart:

Event type

Logged by

eventGroupId

EXTERNAL_EVENT

PianoExternalEvent, and a Piano button's externalEventName

the event name you chose

EXTERNAL_LINK

the <A> component, on click

the destination URL (without query or hash)

Both are stamped with the widget's tracking ID automatically; you never attach it yourself. EXTERNAL_EVENT is the one described everywhere above on this page; EXTERNAL_LINK is new here and belongs to the <A> component.

<A href="https://your-landing-page.example/subscribe">Subscribe</A>

<A> appends _ptid=<trackingId> to the destination and logs an EXTERNAL_LINK on click. _ptid is added only when all of these hold:

  • the href is an absolute http(s):// URL, lowercase http; uppercase HTTP:// does not match;

  • the widget's tracking ID is present when the link renders;

  • noptid is not set.

If any fails, the link still works but carries no _ptid (and logs no EXTERNAL_LINK). This is the recommended path whenever the destination is a Piano offer/checkout opened on the landing page: the landing-page SDK reads _ptid and uses it as the tracking ID (see The landing page below), so you never handle the ID yourself. Don't also add ?_ptid=… by hand; <A> does it. A promoted <A> opens in _blank unless you set target to _self, _parent or _top.

Record the article-side click

To make the article-side click appear in the Conversion Report, wrap the CTA (see PianoExternalEvent, above):

<PianoExternalEvent name="subscribe-cta">
  <A href="https://your-landing-page.example/subscribe">Subscribe</A>
</PianoExternalEvent>

An <A> inside the wrapper logs both events: the wrapper's EXTERNAL_EVENT (fired in the capture phase, first) and the link's own EXTERNAL_LINK. So one text-link click produces two conversions; a plain <button> inside the wrapper produces one. Account for this when reading reports.

Read the tracking ID yourself

These are standard context members on every Lightweight template, read straight from the widget:

Member

Type

Notes

context.trackingId

string

The Piano tracking ID used for _ptid

context.browserId

string

The Piano browser ID, optional: can be empty until the SDK has seeded one, so guard for the empty case if your URL requires it

context.experienceId

string

The Composer experience ID, filled when the widget is shown by an experience, empty otherwise

Use them when <A>/_ptid doesn't fit, a non-<A> redirect (e.g. a <button> that navigates with custom JS), or your own checkout/landing page that expects the ID under your own parameter name:

// a button that redirects to your own checkout:
const url = `https://your-checkout.example/subscribe`
  + `?piano_tracking_id=${context.trackingId}`
  + `&browser_id=${context.browserId}`;

For a plain link to a Piano landing page, prefer <A>; it adds _ptid for you, and the landing page reads it automatically. Reach for context.trackingId only when you need the raw value on a non-<A> redirect or under a custom parameter name.

Converting a Classic template

The converter resolves the Classic tracking placeholders on their own, no manual edit:

Classic placeholder

After conversion

Result

{{params.trackingId}}

context.trackingId

resolved; the real Piano tracking ID

{{custom.browserId}}

context.browserId

resolved; the converter promotes the old custom.browserId spelling for you

{{params.experienceId}}

context.experienceId

resolved; the Composer experience ID

So a converted tracking link such as ?piano_tracking_id={{params.trackingId}}&browser_id={{custom.browserId}} keeps working with no edit.

One edge case.browserId is the only key the converter lifts out of the publisher custom bag. If you deliberately kept your own custom field literally named browserId for something unrelated, it is now read as Piano's browser ID; rename your own field. The rewrite is recorded in the conversion report; every other custom.* key is left untouched.

The landing page

  • The landing page must load tinypass.min.js.

  • The SDK reads _ptid from the page URL and uses it as the tracking ID for any offer/checkout opened on that page; it never writes _ptid. The article-side <A> (or your own URL above) is what puts it there.

  • As with Classic, this applies to a Piano checkout/offer opened on the landing page, not to an external checkout.

Pitfalls

  • noptid must be noptid={true}. A bare noptid collapses to an empty string (falsy) in a template, so _ptid is still added; the opposite of what you intended.

  • Empty tracking ID at render. If the tracking ID isn't available when an <A> first renders, the href is set without _ptid. The same caution applies to a URL you build from context.trackingId, which can be empty at first render; guard for it.

  • Only absolute http(s) links track. Relative paths, #anchors, mailto:/tel:, protocol-relative //cdn… and uppercase HTTP:// get no _ptid and no EXTERNAL_LINK.

  • Double events. An <A> inside PianoExternalEvent logs two conversions (above); account for it when reading reports.

Last updated: