Leveraging events in Affinity

Affinity emits events to broadcast crucial information about customer behavior, and listens for directives that let your custom code trigger Affinity behaviors. Use events to track customer journeys, synchronize custom content, and build custom flows.

Before you start

You must be on the Recharge Plus or Custom pricing plans to make advanced customizations to the Affinity customer portal.

Event types

Click and action events

Click and action events describe different points in the same journey. For example, Recharge::click::skip is emitted when the customer clicks Skip, while Recharge::action::skip is emitted only after the order has been skipped. Comparing the two can show where customers abandon a flow.

Track customer behavior

Listen for events with document.addEventListener. The following example records when a customer starts and successfully completes the Skip flow:

document.addEventListener('Recharge::click::skip', event => {
  analytics.track('Affinity skip started', event.detail?.payload);
});
document.addEventListener('Recharge::action::skip', event => {
  analytics.track('Affinity skip completed', event.detail?.payload);
});

Click events occur before Affinity continues with its default behavior. To intercept a click event and replace the standard flow with your own experience, see Personalize user journeys with custom flow extensions.

Navigation events

Listen for Recharge::location::change to detect when a customer moves to another page in Affinity. The event detail includes the new path, which you can use for journey analytics:

document.addEventListener('Recharge::location::change', event => {
  analytics.track('Affinity page viewed', {
    path: event.detail?.pathname,
  });
});

Slot lifecycle events

Slot lifecycle events are triggered when slot content is added to or removed from the Document Object Model (DOM). Use them to manage the lifecycle of custom code linked to slot content.

Slot content in Affinity is dynamically loaded, meaning it is not present in the DOM during the initial page render but is added shortly afterward. When developing advanced content extensions, host initial placeholder elements in Slots, then wait for those elements to be present in the DOM before initializing your custom code:

<script type="text/html" data-recharge-slot="overview.header">
  <div id="placeholder-for-my-app"></div>
</script>

document.addEventListener("Recharge::slot::mounted", (event) => {
  if (event.detail.name === "header" && event.detail.pathname === "/overview") {
    // Initialize my app
  }
});

Directives

Directives work in the opposite direction from events: your code dispatches a supported event for Affinity to receive and act on. Use directives to open common actions or refresh portal data after external changes.

Dispatch a directive as a CustomEvent on document. Unlike events emitted by Affinity, directive details are placed directly on event.detail rather than inside event.detail.payload.

To open Reschedule for the complete upcoming charge:

document.dispatchEvent(new CustomEvent('Recharge::order::openRescheduleModal'));

To open Reschedule for one specific subscription:

document.dispatchEvent(
  new CustomEvent('Recharge::order::openRescheduleModal', {
    detail: { subscriptionId: 12345 },
  })
);

If custom code changes data outside the standard Affinity flow, dispatch the refresh directive so the page requests the latest data:

document.dispatchEvent(new CustomEvent('Affinity:refresh'));

Migrating event code to Affinity 2.0

If you built event-driven customizations on Affinity 1.0, review the following before migrating:

• Recharge::extension::cancellation_flow is deprecated. It continues to work, but update your listeners to Recharge::click::cancel.
• Slot lifecycle events are not available in 2.0. If your extension initializes custom code on Recharge::slot::mounted, it needs a new initialization strategy in 2.0. [TODO: Confirm, and document the 2.0 replacement pattern for content extensions if one exists.]
• Event detail structure. Events emitted by Affinity place data in event.detail.payload; directive details are placed directly on event.detail. [TODO: Confirm whether this differs between 1.0 and 2.0.]
• Click event payloads include subscription IDs. All click events include the relevant subscription IDs under event.detail.payload.subscriptionIds.

All click and action events use the same names in both versions, so intent/completion analytics carry over without changes.