Using custom extensions for Affinity 2.0

Custom extensions let you build and register your own UI components when using the Affinity Home Page Builder.

This guide explains how to register and add custom extensions to Affinity landing pages, including the Home page, Cancellation Prevention, Win Backs, and Upcoming Order Email pages.

Before you start

• You must build your custom extension before registering it. You can either upload the file directly in the Page Builder or host it externally.
• This guide applies only to the Affinity Home Page Builder. See Customizing the Affinity customer portal if you use the original next order page version of Affinity.
• You must contact the Recharge Support team to request access to this feature.
• You can use custom extensions on Affinity landing pages, including the Home page, Cancellation Prevention, Win Backs, and Upcoming Order Email pages.

Overview

Custom extensions are Web Components that you:

• Register in the Affinity Page Builder
• Add as sections to Affinity landing pages, including the Home page, Cancellation Prevention, Win Backs, and Upcoming Order Email pages
• Render in the customer portal

Step 1 - Build a custom extension

Build your custom extension as a Web Component. You can use any framework or library (React, Vue, Svelte, or vanilla JavaScript), as long as the final output is a Web Component.

Requirements

• HTTPS only: The customer portal runs in a secure context. The browser blocks non-HTTPS resources.

• Default export: Export the Web Component class as the default export. Do not use named exports.

• Load time: Ensure the extension loads within 5 seconds. The portal removes extensions that exceed this limit.

• Valid tag name: Use a tag name that matches the custom element defined in your component.

Example

class MyWidget extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `<p>Hello from my custom extension!</p>`;
  }
}

export default MyWidget;

See custom extension example for a reference example.

Step 2 - Open the page builder

Updating the customer portal

Access the page builder from your customer portal settings:

1. In the merchant portal, click Storefront, then select Customer portal.
2. Under Themes, click your theme’s Home page to expand the options.
3. From the expanded list, choose Affinity 2.0 under the Affinity customer portal theme.
4. Click Customize.

Updating a landing page

Open the flow builder for Cancellation Prevention, Win Backs, and Upcoming Order Email pages to access the landing page editor. See Building landing pages using the Site Builder for more information.

Step 3 - Register a custom extension

You can register a custom extension in one of the following ways:

• Upload the compiled JavaScript file directly (recommended)
• Provide a hosted file URL (alternative)

Upload a custom extension file (recommended)

You can upload your compiled extension file directly in the Page Builder instead of hosting it externally.

When you upload a file:

• Recharge stores the file in Shopify Admin → Content → Files
• The file is available across all Shopify themes in your store
• You do not need to host the file on a CDN or external service

After opening the page builder in Step 2, you can upload a file:

1. Open the landing page where you want the extension to appear, then select Header, Main column, or Right column and click Add a section.
2. Select the Custom extensions tab.
3. Click Create a custom extension.
4. Upload your compiled JavaScript file.
5. Complete the remaining fields, then click Save.

Use a hosted file URL (alternative)

If you host your extension externally (for example, using a CDN or cloud storage), you can register it using a file URL.

After opening the page builder in Step 2, you can register using a file URL:

1. Open the landing page where you want the extension to appear, then select Header, Main column, or Right column and click Add a section.
2. Select the Custom extensions tab.
3. Click Create a custom extension.
4. In the File URL field, provide an HTTPS URL to your compiled JavaScript file.
5. Complete the remaining fields, then click Save.

Custom extension fields

Use the table below to complete the custom extension fields.

Event behavior

When a configured event fires:

• The portal calls the component’s refresh() method
• The portal does not pass any data to refresh()
• The component fetches its own data

Step 4 - Add the extension to your page

After you register the extension, you can add it as a section to any supported Affinity landing page.

1. Click Add a section in the Page Builder.
2. Open the Custom extensions tab. You should now see your custom extension on this tab.
3. Select your extension to add it to the selected landing page.
4. Click and drag the custom extension section to reposition it on the page.

Step 5 - Test and publish

New extensions start in test mode:

• The portal shows them only in preview
• Customers cannot see them

Once you've verified the extension works as expected, make the extension visible:

1. Click on the custom extension section.
2. Enable Make this extension visible to customers.
3. Click Done to publish your changes.