Personalizing the user journey in Affinity

Custom flow extensions intercept the initial click before the action occurs. Recharge no longer owns the interaction after the click is intercepted, and gives you full control over the flow. In addition to click events, Affinity emits action events after an action completes and navigation events when a customer moves between pages, which you can use to track customer behavior or trigger custom experiences.

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

The following event types are available when customizing the Affinity customer portals:

Available 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.

Implement custom flow extensions to respond when a user clicks one of the following:

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 can be used for journey analytics:

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

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. For example, 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 },
  })
);

To open the Add product experience for a specific product:

document.dispatchEvent(
  new CustomEvent('Recharge::order::openAddProductModal', {
    detail: { productId: '9876543210' },
  })
);

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'));

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);
});

Replace a standard flow with a custom flow extension

Click events occur before Affinity continues with its default behavior. A custom flow extension intercepts the click, blocks the standard flow, and displays your own experience instead.

To create a custom flow extension:

1. Listen for the specific click event.
2. Call event.preventDefault() to block the standard flow.
3. Retrieve the relevant subscription IDs. All click events include a list of relevant subscription IDs in the payload under event.detail.payload.subscriptionIds.
4. Use the storefront SDK to access additional context about the subscription, address, or customer.
5. Display your custom flow based on the gained context.

Custom flow example

The following example interrupts the cancelation process for specific products. If the subscription being canceled matches a list of restricted product IDs, a message urges the customer to contact support instead. The standard cancelation flow applies to all other products:

<script>
// Define the list of product IDs that are not eligible for direct cancellation
const uncancellableProductIds = [PRODUCTID];

// Customize the message to guide customers to contact you
const alertMessage = "To cancel this product, please reach out to us at [email protected]";

// Listen for the cancel click event
// Note: Recharge::click::cancel replaces Recharge::extension::cancellation_flow
document.addEventListener(
  "Recharge::click::cancel",
  (event) => {
    const { subscription } = event.detail;
    const subscriptionProductId = subscription.shopify_product_id;

    // Check if the product is in the list of uncancellable products
    if (uncancellableProductIds.includes(subscriptionProductId)) {
      // Prevent the default cancellation flow
      event.preventDefault();

      // Display an alert to guide customers
      window.alert(alertMessage);
    }
  }
);
</script>