ShipAid Shopify Widget

This is the repository for the ShipAid Shopify (and possibly others in future) widget. It uses the Lit web components library, so it is recommended to become familiar with it before contributing to this repository.

Using Lit provides a framework that allows us to build a reactive UI, using JSX-like syntax - no need to use JQuery etc. And it can easily be installed in a page by using the custom web component name:

Fallback Content

Overview

This widget provides an interface where a user can choose to add or remove ShipAid protection - this is actually a product in their store that can be added to cart. When the component is loaded, we immediately run a request to fetch the ShipAid protection product details from our API, as well as the customers current cart from the Shopify AJAX API. Once we have this data, we can check whether the customer currently has the ShipAid product in their cart, and show either the add or remove product buttons based on this.

We also emit various custom events when we add or remove the ShipAid product from the cart, so other developers can listen to these events, and update AJAX carts.

Installation

Add the script tag to the theme - if the theme has an ajax cart, you'll likely want to add this to the theme.liquid file, otherwise if the store has only a cart page (/cart), then you can add it to just that page, to save it being unecessarily loaded when it isn't needed. As we don't want to affect a stores speed at all, you should add it to the bottom of the page just before the ending body tag (), rather than inside the block.

Then add the widget element where needed:

  <p slot="loading">Loading ShipAid Protection</p>

Test Mode

Sometimes, a store won't have activated their subscription before you install the widget - in this case, the widget does not display (you will notice a message in the console reflecting this). So to force the widget to show while you are installing and testing it, you can add this query param to the page URL: shipaid-test. For example: https://some-store.myshopify.com/cart?shipaid-text

Slots

Slots, with the syntax slot="", can be used to customise the widgets content - for example, a merchant may want to add a custom subtitle, which can be done like so:

  <p slot="subtitle">Shipping protection is required to be able to return or refunds items.</p>

The default content will be replaced by any slot content. You can also add inline styles to the slots, if you need to change the font size/weight for example - but color changes should be handled by CSS variables:

<span style="font-weight: 500;" slot="title">Package Protection</span>

Props

This is a list of props that can be used to configure the widget:

Events

This is a list of the events emitted by the widget. You can listen to these events like so:

document.addEventListener('shipaid-protection-status', ({ detail }) => {
  console.log(detail.cart) // ShopifyCart
})

Methods

This is a list of public methods available on the widget HTMLElement that can be used to change protection settings. These can be used by querying the element:

const shipAidEl = document.querySelector('shipaid-widget')
if (shipAidEl) await shipAidEl.updateCart()

Styles

If you need to change any of the widget colors to suit a specific theme, there are various CSS variables you can use to do so. These should be added to the style attribute on the widget element:

Other variables can be found here (/widget/src/assets/styles.ts).

Translations

This widget also supports multiple languages, using the lit-translate plugin. The widget language can be configured using an attribute and would usally be static, but supports reactively swapping the language if a theme needs - i.e. if a user switches the language using a select option in the theme, then the widget language could be updated at the same time by selecting the widget element, and setting the lang attribute.

To create lang files, you should copy the default /lang/en.json file, and rename it to an ISO 639-1 code - for example cp /src/lang/en.json /src/lang/fs.json. You can then go through each key, and translate the existing text to the relevant language. This should be all you need to do - the widget automatically (and lazily, to save bundle size) imports the relevant lang file when it is specified. It will also fallback to the default en.json lang file if a certain language doesn't exist yet.

Contributing

Requirements

• Node v16+
• PNPM
• Development Shopify store (with the ShipAid app installed)
• ShipAid API development/staging instance

Development

You will need to make sure your development store has the ShipAid app installed, so the store and its protection product is added to the DB. You will also need to ensure the Shopify app you are testing this with has an app proxy added, and pointed towards an API instance.

pnpm install
pnpm run develop

Once the project is running, add the below to your development Shopify store theme.liquid:

And add the widget element where needed:

  <p>Loading ShipAid Protection</p>

Build

Once the project has been built, you can publish the project to NPM, and users can add the script to their store using a package CDN (I.e. Unpkg).

pnpm install
pnpm run lint
pnpm run build
pnpm publish