Upgrade Guide

From time to time, you may want or need to upgrade your Beam widget versions to take advantage of the latest features, performance improvements, and fixes available. Beam takes backwards compatibility seriously, and we do our best to ensure that later versions of Beam widgets can be easily upgraded to from older versions. In most cases, this is as simple as updating the version number referenced in the Beam widget scripts on your site.

info

The latest version of Beam’s widgets is latest

For example, the Select Nonprofit widget below is using version v1.20.0, as you will see “v1.20.0” in the <script src=""> URL.

info

Older installations may use production-beam-wigets.beamimpact.com instead of sdk.beamimpact.com in the URL; they both point to the same server. You can use either but make sure all scripts use the same domain.

<script
  type="module"
  async
  crossorigin
  data-em-disable
  data-categories="analytics"
  src="https://sdk.beamimpact.com/web-sdk/v1.20.0/dist/components/select-nonprofit.esm.js"
></script>

<div data-beam-widget="select-nonprofit" data-cart-empty="true">
  <beam-select-nonprofit
    apiKey="abc-123"
    chainId="1"
    storeId="1"
    lang="en"
    postalCode=""
    baseUrl="https://api.beamimpact.com"
  ></beam-select-nonprofit>
</div>

To perform an upgrade of the widget above, change “v1.20.0” to the version number you are looking to upgrade to, and save the file. That’s it!

In some cases, the version number is embedded within the widget scripts themselves. For example, the cart setup code below is using version v1.19.1, as you will see “v1.19.1” in the import { ... } from "https://... URL.

<script type="module" async crossorigin>
  import { registerCartIntegration } from "https://sdk.beamimpact.com/web-sdk/v1.19.1/dist/integrations/shopify.esm.js";
  import { events } from "https://sdk.beamimpact.com/web-sdk/v1.19.1/dist/integrations/utils.esm.js";
  ...
</script>

To perform an upgrade of the script above, change “v1.19.1” to the version number you are looking to upgrade to, and save the file. Done!

---

Where to upgrade widgets

A quick way to find all Beam version references in your site’s code is to search your code for any references to beamimpact.com. The version number is found in the URL whenever this domain is used. Simply update the version number in all of these URLs!

Additionally, the following checklist can be used as a starting point. It is designed for a standard integration with Beam. Depending on your implementation you may have more, or less, areas of your site that the Beam widget scripts are included.

• Beam Cart Setup
  • You may see this in a file such as beam-cart-setup.liquid, beam-cart-setup.js, beam-cart-contents.liquid
• Beam Select Nonprofit
  • You’ll usually have a <script> to update in your main site template such as theme.liquid or template.html
  • There are also version number references in the widget’s integration scripts, which can be found in a file such as beam-select-nonprofit.liquid or beam-select-nonprofit.js
• Beam Post Purchase
  • In most cases, this code is added to the Thank You or Order Confirmation page of your site.
  • For Shopify specifically, look in the Additional Scripts section of your Order status page in your Shopify Checkout settings. If you are using a different application for managing your thank you page such as Rebuy, Upscribe, Recharge, or anything similar, look for the Beam Post Purchase code in the scripts area for your chosen application.
• Beam Community Impact
  • You’ll usually find this in your brand’s impact or about us pages, either in a page.template or in the page’s source code.
  • You may also find this in a file called beam-community-impact.liquid if you use Shopify
• Beam Cumulative Impact
  • You’ll usually find this in your brand’s impact or about us pages, either in a page.template or in the page’s source code.
  • You may also find this in a file called beam-cumulative-impact.liquid if you use Shopify

---

Validating the upgrade was successful

To make sure that your Beam widget upgrade was successful, you will likely want to perform one or more of these quick checks:

1. Ensure that you can select a nonprofit in your cart.
   1. When you refresh the page, the nonprofit you selected should still be selected.
2. Open the Community Impact and Cumulative Impact pages (if you have them) and make sure that both widgets load correctly.
3. Place a test order (if you are able to do so), and ensure that the Beam Post Purchase widgets are working correctly.
   1. If you selected a nonprofit in the cart, the Beam Post Purchase widget should show you the impact your purchase made towards that nonprofit’s goals.
   2. If you did not select a nonprofit in the cart, the Beam Post Purchase widget should show you a list of nonprofits to donate a portion of the purchase towards.
   3. Make sure to cancel your order if it was only a test!