> ## Documentation Index
> Fetch the complete documentation index at: https://developers.appstle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript events and portal embed for Appstle Memberships on Shopify themes

> The AppstleMembership:CustomerPortal:ReadyToEmbed and AppstleMembership:CustomerPortal:Embedded events that Appstle Memberships fires on a Shopify theme, and how to embed the customer portal on your own page and start it from your code with appstleMembershipCustomerPortalInit.

On a Shopify theme, the Appstle Memberships app embed fires two JavaScript events, both about the customer portal: `AppstleMembership:CustomerPortal:ReadyToEmbed` and `AppstleMembership:CustomerPortal:Embedded`. Use them to start the portal from your own code once it can run, and to run your code once the portal is on the page.

The events exist only on a Shopify theme where the **Appstle℠ Memberships** app embed is on (in the theme editor, under **App embeds**). If you build a headless storefront or your own front end on the [Storefront API](https://developers.appstle.com/memberships/authentication.md#storefront-api-authentication), nothing fires them: update your own UI when your own calls return.

> [!WARNING]
>
> **Build on the events and on `appstleMembershipCustomerPortalInit`, not on the portal's markup.** The portal's HTML, CSS class names and element IDs aren't part of this interface and can change whenever the portal's design is updated. To restyle the portal with CSS, see [Member portal CSS](https://developers.appstle.com/memberships/member-portal-css.md). For changes to the events, see the [API changelog](https://developers.appstle.com/memberships/api-changelog.md).

## The events

Both events are plain `Event` objects with no `detail`, and they don't bubble. The app embed dispatches each one on `document` and then on `window`, so a listener on both runs twice. Listen on one of them.

| Event name | Fires when |
| - | - |
| `AppstleMembership:CustomerPortal:ReadyToEmbed` | The embed can start the portal: `window.appstleMembershipCustomerPortalInit` is a function. |
| `AppstleMembership:CustomerPortal:Embedded` | The portal's HTML is in the element, after each load of the portal. The portal then loads the customer's memberships, so they appear after this event. |

```javascript theme={null}
document.addEventListener(
  'AppstleMembership:CustomerPortal:Embedded',
  () => {
    console.log('The customer portal is on the page');
  }
);
```

On the demo store, a page with an `AppstleMembershipCustomerPortal` element recorded the events in this order:

1. `AppstleMembership:CustomerPortal:ReadyToEmbed`, with `window.appstleMembershipCustomerPortalInit` already a function.
2. `AppstleMembership:CustomerPortal:Embedded`, once the portal's HTML was in the element.

`ReadyToEmbed` fires while the page loads. `Embedded` fires each time the portal is loaded into an element, including the load that starts by itself when the page has an element with the id `AppstleMembershipCustomerPortal`. A listener that you add after an event has fired never sees it, so add your listeners early, for example in a script with `defer` or in the theme's `<head>`. For `ReadyToEmbed`, also check the function as shown in [Start the portal from your own code](#start-the-portal-from-your-own-code).

## Embed the customer portal on a page

Use the embed to show Appstle's customer portal inside a page of your store, such as `/pages/members`, instead of rebuilding the portal with the Storefront API.

> [!NOTE]
>
> This embeds the customer portal that Appstle serves through the app proxy, by default at `/apps/memberships`. The membership page inside Shopify's own customer account pages is a separate Shopify customer account extension, and you can't embed it elsewhere.

### Add the portal to a page

Add an element with the id `AppstleMembershipCustomerPortal` to the page. On a Shopify page, switch the editor to HTML view (the `<>` button) and paste:

```html theme={null}
<div id="AppstleMembershipCustomerPortal"></div>
```

When the Appstle script loads, it finds the element and fills it with the portal. You don't call anything. On the demo store the element received the portal inside an `iframe`, so don't depend on the markup inside the element.

A signed-in customer sees their memberships. A visitor who isn't signed in sees a form that asks for their email address to send them a new sign-in link. On the demo store, it showed the message "Your magic link has expired. Enter your email to get a new link." with an **Email address** field and an **Email Magic Link** button.

### Start the portal from your own code

Call `window.appstleMembershipCustomerPortalInit(selector)` when the element has a different id, or when your code adds it after the page loads. Call it after the element is in the page. The function loads the portal into every element that matches the CSS selector, so use a selector that matches one element, such as an id. Without a selector, it uses `#AppstleMembershipCustomerPortal`.

The function may not exist yet when your code runs. Check for it first, and when it isn't there yet, wait for the `ReadyToEmbed` event:

```javascript theme={null}
function startPortal() {
  window.appstleMembershipCustomerPortalInit('#my-portal');
}

if (typeof window.appstleMembershipCustomerPortalInit === 'function') {
  startPortal();
} else {
  document.addEventListener(
    'AppstleMembership:CustomerPortal:ReadyToEmbed',
    startPortal,
    { once: true }
  );
}
```

What the call does:

* When the portal's HTML is in the element, `Embedded` fires and the returned promise resolves, with no value.
* When the request for the portal fails, the error is logged to the browser console, `Embedded` doesn't fire and the promise still resolves. It never rejects.
* When no element matches the selector, the call does nothing and no event fires.
* Each call loads the portal again and replaces what is inside the element, so call it once per page view.

The function returns a promise or `undefined`, and the promise isn't always a native `Promise`. To wait for the portal, wrap the call in `Promise.resolve()`:

```javascript theme={null}
await Promise.resolve(
  window.appstleMembershipCustomerPortalInit('#my-portal')
);
```

If the element is in the page and the portal doesn't load, check **Member Portal Url** in the Memberships app, under **Settings** > **Shop Settings** > **General Settings**. The function loads the portal from that path, by default `apps/memberships`, so the path must open the portal on the store. When the setting isn't an app proxy path such as `apps/memberships`, the call does nothing and logs nothing.

## Further reading

> [card] [Sell from a custom page](https://developers.appstle.com/memberships/sell-from-a-custom-page.md)
>
> Add a membership to the cart from your own page or theme code.

> [card] [Storefront API authentication](https://developers.appstle.com/memberships/authentication.md#storefront-api-authentication)
>
> How Storefront API calls are authorized and limited.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.