Setup

1. Install Beam Web SDK

npmjs.com/package/@beamimpact/web-sdk/

npm install @beamimpact/web-sdk

2. Gather your Beam IDs and credentials

Most of Beam’s widgets and code implementations reference specific identifiers and credentials that will be necessary to communicate with the Beam system. Please ensure that you have all of these values readily available as you begin your implementation, and reach out to us if you need them!

Required

API Key

• This is the Beam SDK API Key used to communicate with Beam’s backend system. This is provided by Beam during initial setup, and will look similar to abc123.xyz456

Chain ID

• This is a number that uniquely identifies your overall brand in Beam’s system. This is provided by Beam during initial setup

Store ID or Postal Code + Country Code

• Store ID is a number that uniquely identifies individual locations, stores, websites, or a similar grouping of user activity to provide a particular set of nonprofits for selection to the user
• If your Beam configuration includes multiple stores, storeId should be omitted and postalCode and countryCode provided instead.

Widget Version

• (Latest version: latest) See SDK Versions for more information on versioning.

Optional

Domain

• The “top domain” of your site (i.e., mystore.com), which is used to set cookies that can be read across subdomains. This is used to preserve nonprofit selections and AB test assignments if your storefront and checkout flows are on different subdomains like www.mystore.com, checkout.mystore.com.

Statsig Client API Key

• This is an optional api key that is provided by Beam if the integration will be using A/B tests. This key is used to communicate with Statsig’s backend system, and will look similar to client-abc123xyz456

Base Url

• This value can be used to point the widgets to Beam’s Staging environment, if needed. In most cases, Beam will provide a testing API key for you rather than using a separate environment. The staging URL is https://api-staging.beamimpact.com.
• The default value for baseUrl is https://api.beamimpact.com. You do not need to provide it unless you are using a different URL.

3. Add the base Beam code files

💡 There are multiple, valid ways to integrate Beam widgets into your codebase. This guide will show adding Beam in a self-contained directory, assumed to be at: src/app/components/beam

Add the base files for Beam constants configuration, cart tracking, and Statsig (if applicable) to your app, which will enable easy integration of the Beam widgets into your cart and community impact pages.

1. Add the Beam constants file
2. Add the Beam cart tracking file

3. Add the Select Nonprofit widget to the cart

The nonprofit selection widget is where the user is registered, and is where the user can choose a nonprofit for their transaction. For the transaction after a user chooses a nonprofit, a donation will be recorded as owed to that nonprofit. All recorded donations will separately be fulfilled in aggregate on a quarterly basis by the Finance team.

Beam Select Nonprofit

4. Add the Post Purchase experience

On any thank you page after a customer has completed an order, the Beam Post Purchase experience can be easily integrated. If a user has already selected a nonprofit in the cart for that order, the thank you page will show the Impact Overview widget. If a customer has not selected a nonprofit, the customer will see the option to select a nonprofit using the Select Nonprofit widget. Once the customer clicks “Submit”, the transaction will be updated in Beam’s system with the user’s nonprofit selection and the thank you page will then show the Impact Overview widget.

Beam Post Purchase

5. Add the Community Impact widget

Beam’s Community Impact is typically added to a page on a partner’s site that highlights the brand’s giving initiatives, an “About Us” page, or anywhere that the partner would like to showcase their community’s impact towards nonprofit goals.

Beam Community Impact

6. Add the Cumulative Impact widget

Beam’s Cumulative Impact widget displays overall impact made by the partner’s community across all of a partner’s nonprofit goals with a text-based summary of each goal’s completion progress. This is similar to the Community Impact widget, differing in that it displays goal completion in number values rather than progress bars. It is highly recommended by the Beam team, and is in Beam’s best practices, to place the Community Impact widget and Cumulative Impact widgets on the same page, with the Community Impact widget above the Cumulative Impact widget.

Note that the Cumulative Impact widget will not display impact information for nonprofit goals which have not yet been funded enough to show a whole number of progress towards the goal. For example: a nonprofit goal of cleaning 100 pounds of plastic from the ocean must be funded at least 1% in order to display 1 pound of plastic cleaned from the ocean. For this reason, it is recommended by the Beam team to wait to implement the Cumulative Impact widget until your community has been given enough time to fund some of your partnered nonprofit’s goals. Often, our partners layer in the Cumulative Impact widget during an impact focused marketing push.

Beam Cumulative Impact

7. Integrate order verification

Beam has built a set of transaction verification APIs that will help ensure that all transactions captured by the Beam system are accurate and complete. This is a necessary component to ensure that our partners have the most precise reports and invoices possible.

Beam Order Verification API

8. Other implementation considerations

• Do your Beam widgets use any custom fonts?

  Please see: Working With Custom Fonts