@束波/web-sdk
Beam SDK使品牌在共享价值之上与用户连接,而不是交易折扣,以建立更强的忠诚. 我们的一体化是通过允许用户(a) 选择一个非营利机构,在该机构中,该品牌将从一套管理好的选项中捐出部分购买权,并(b) 跟踪其累积影响,按顺序排列,以实现可量化的目标.
Beam负责所有的非营利管理和合规、影响跟踪、UI的造型和动态宣传.
学习更多: bam-impact.com (原始内容存档于2018-09-29)
Beam Web SDK 提供了一组网络组件和针对框架的包装 将Beam组件纳入电子商务网站.
安装
@beamimpact/web-sdk 国家防范机制或通过CDN提供.
光盘N
大部分电子商务应用都会将Beam装入CDN.
包含要在页面上方使用的组件的脚本 :
<script
type="module"
crossorigin
src="https://sdk.beamimpact.com/web-sdk/v1.36.1/dist/components/community-impact.js"
></script>
版本数
替换
v1.36.1与 关于国家预防机制的最新版本
type="module"需要正确解析捆绑- 此脚本将注册 Beam 自定义元素, 因此可以在页面的任意位置使用
- 您可能需要调整您的页面内容安全政策, 以允许从 Beamimpact.com 获取脚本和图像 .
国家预防机制
npm install @beamimpact/web-sdk
导入您的应用程序 JavaScript 中的组件 :
import { BeamCommunityImpact } from "@beamimpact/web-sdk/dist/components"; // Native web component
import { BeamCommunityImpact } from "@beamimpact/web-sdk/dist/react"; // React component
使用束
Web 组件
Beam 网络组件是自定义元素,因此可以用于 HTML :
<beam-impact-overview chainId="1000"></beam-impact-overview>
因为它们是标准的 HTML 元素,Beam 组件可以具有像 class, (中文(简体) ), style,以及 data-attributes。 。 。 .
还可以使用 Javascript 创建组件 :
const component = document.createElement("beam-select-nonprofit");
component.chainId = 1000;
component.apiKey = "abc123";
const parent = document.querySelector("#sidebar-cart .footer");
parent.appendChild(component);
元素还可以有在脚本加载前出现或无法解析的孩子:
<beam-impact-overview chainId="1000"> Fallback or loading content </beam-impact-overview>
反应
Beam为网络组件提供了反应包装.
关键差异:事件处理器召回被曝光为Beam事件,组件使用 JSX友好大写格式.
import { BeamSelectNonprofit } from "@beamimpact/web-sdk/dist/react";
import { events } from "@beamimpact/web-sdk/dist/integrations/utils";
<BeamSelectNonprofit
apiKey={"abc-123"}
chainId={1000}
onNonprofitSelect={(event: events.BeamNonprofitSelectEvent) => {
const { selectedNonprofitId, nonprofitName } = event.detail;
// do something
}}
/>;
服务器端渲染
(i,下一个JS)
Beam组件在本地Storage和cookie中运行客户端并保存数据(如用户的非营利选择).
使用 下一个/动态 至懒惰 组件在客户端而不是服务器上同步.
"use client";
import dynamic from "next/dynamic";
const BeamSelectNonprofit = dynamic(() => import("@beamimpact/web-sdk/dist/react/select-nonprofit"), {
loading: () => null,
ssr: false,
});
调试模式
添加数据 debug 属性到组件,以显示发生错误时 DOM 中的错误状态。 否则,检查一下
控制台日志.
<beam-impact-overview chainId="1000" debug></beam-impact-overview>
组件选项
所有部件所需的道具:
apiKey- Beam API 键
可选道具 :
baseUrl- (由Beam提供) - 用于 dev或中转 API 的 URLlang- 说吧en, (中文(简体) ),fr等 (中文(简体) ). Beam 支持的翻译目标的语言代码
束-社区影响
为每个非盈利组织展示有品牌支持的影响力进步卡,品牌影响力页等.
<beam-community-impact apiKey="abc123" chainId="1" cardStyle="image | icon"></beam-community-impact>
chainId= Beam 客户身份证cardStyle=:image或者说icon- 用于撞击卡的视觉风格
梁-累积-影响
在非营利筹资目标方面显示出总的影响,例如“清除了9 000磅海洋垃圾”
<beam-cumulative-impact apiKey="abc123" chainId="1"></beam-cumulative-impact>
chainId= Beam 客户身份证
梁选非盈利
集成到推车中的组件,让用户在退货时支持非营利组织.
<beam-select-nonprofit apiKey="abc-123" storeId="1"> Select a nonprofit </beam-select-nonprofit>
storeId= 网站的Beam ID,即欧盟或美国在线商店(可选) - 用于向用户显示相关的非营利性countryCode打开postalCode= 如果storeId不提供,而是可以提供地点信息(可选)cart= 通常由推车整合自动设置(见下文),推车属性允许自定义 根据推车中的物品显示的非盈利
活动
document.addEventListener("beamnonprofitselect", (evt) => {
const { selectedNonprofitId, selectionId, nonprofitName } = evt.detail;
// ...
});
事件类型
选择非营利构成部分和采购后构成部分
- 事件 :
beamnonprofitselect - 说明 : 当终端用户在 Beam 组件中选择一个非营利时, 当前一个选择被自动恢复时, 发送
选择非营利部分
-
事件 :
beamcartchange -
说明 : 当Beam发现推车内装物有变化时,当首次将物品添加到推车中时,即予确认
-
事件 :
beamnonprofitselectionremoved -
说明 : 在非盈利性选择被取消或由于非盈利性群体变动而取消时被允许入境
Statsig / A/B 实验
- 事件 :
beamstatsiginitialized - 说明 : 当Statsig完成为本届会议指定实验变体时即予以确认。 包含
showBeam(是否应当显示组件)和stableId(Statsig会议Id).
采购后构成部分
- 事件 :
beamordercreated - 说明 : 首次向Beam登记命令时发出通知,但重复访问、页面刷新等时不发出通知.
后购梁
用于登记交易和使交易 beam-impact-overview 或者说
beam-redeem-transaction 组件,取决于用户在购买之前是否进行了选择.
<script src="https://sdk.beamimpact.com/web-sdk/v1.36.1/dist/components/post-purchase.js"></script>
<beam-post-purchase apiKey="abc123"></beam-post-purchase>
const component = document.createElement("beam-post-purchase");
// Config values:
component.apiKey = "abc123"; // Required
component.storeId = 100; // Beam Store ID
component.countryCode = "GB"; // 2-letter country code for order
component.postalCode = "11111"; // String - postalCode in country-specific format
component.orderId = String(10101); // partner provides ID
component.email = "[email protected]"; // user email
component.cartTotal = 100.01; // Cart total before tax
component.currencyCode = "USD"; // "CAD" etc.
component.cart = {
schema: {
source: "shopify",
},
content: {
items: [{ sku: "PRODUCT-100" }],
},
}; // see OpenAPI spec for cart formats
component.discountCodes = ["PROMO10", "CLEARANCE_50"]; // discount / promo codes
component.lang = "en"; // en | fr Language
component.domain = "example.com"; // [Optional] Base domain of the store, if subdomains for store and checkout differ
component.debug = false; // boolean
活动
document.addEventListener("beamnonprofitselect", (evt) => {
const { selectedNonprofitId, nonprofitName } = evt.detail;
// ...
});
自定义内部组件
使用 beam-post-purchase::part(impact-overview) 或者说 beam-post-purchase::part(redeem-transaction) 应用 CSS.
一体化
墨盒整合
把Beam和你的推车结合起来,就可以根据推车内的物品定制现有的非营利性物品.
import { updateCart } from "https://sdk.beamimpact.com/web-sdk/v1.36.1/dist/integrations/cart.js";
// on cart change
const cart = {
cartId: "cart_100", // external cart ID (from partner site, optional)
subtotal: 90,
itemCount: 1,
currencyCode: "USD",
content: {
items: [
{ remoteProductIdentifier: "sku-123", localAmount: 50 },
{ remoteProductIdentifier: "sku-456", localAmount: 40 },
],
},
};
const beamConfig = {
apiKey: "abc-123",
storeId: 123,
domain: "my-tld.com", // optional, domain or subdomain to set cookies on
baseUrl: "", // optional, Beam API url (staging or production)
};
await updateCart(beamConfig, cart);
购买
这个 registerCartIntegration() 函数将 Beam 非营利选择组件与 Shopify 拖车相融合
允许将非营利ID和选择Id的Beam元数据添加到顺序中,因为用户通过
检查出行,并跟踪行车符和行车值用于Beam ROI计算.
添加事件跟踪脚本到主版式 :
<script type="module" async crossorigin>
import { registerCartIntegration } from "https://sdk.beamimpact.com/web-sdk/v1.36.0/dist/integrations/shopify.esm.js";
registerCartIntegration({
apiKey: "abc123",
storeId: 100,
chainId: 10,
});
</script>
后购脚本 :
import { showBeamOrderPageWidgets } from "https://sdk.beamimpact.com/web-sdk/v1.36.0/dist/integrations/shopify.esm.js";
await showBeamOrderPageWidgets({
apiKey: beam.apiKey,
chainId: beam.chainId,
storeId: beam.storeId,
orderId, // From Liquid
email, // From Liquid
cartTotal, // From Liquid
cart, // Cart line items
currencyCode, // From Liquid
countryCode, // From Liquid
postalCode, // From Liquid
parentSelector: ".step__sections", // CSS selector
lang: "en", // From Liquid
baseUrl: beam.baseUrl,
debug: false,
});
同意驱动的拆解:
如果用户撤回跟踪同意, unregisterCartIntegration() 停止听众设置
registerCartIntegration() 并可以在同一个呼叫中可选择地擦去Beam的本地存储/cookie. 这是选入——
SDK不看 同意信号本身, 所以这必须连接到你自己的同意横幅/流量.
import { unregisterCartIntegration } from "https://sdk.beamimpact.com/web-sdk/v1.36.0/dist/integrations/shopify.esm.js";
await unregisterCartIntegration(
{ apiKey: "abc123", storeId: 100, chainId: 10 },
{ clearStorage: true }, // also clear Beam's localStorage/cookies; defaults to false
);
用户
一些公用事业被曝光,使得与现有应用程序的整合更容易.
waitForElement返回选择器出现时解析的保证.errors包含 Beam 自定义错误类.events包含 Beam 自定义事件类/事件名.clearBeamStorage清除所有与 Beam 相关的本地密钥和给定配置的 cookie; 有用 独立同意驱动的重置不附带条件unregisterCartIntegration。 。 。 .
import { clearBeamStorage } from "https://sdk.beamimpact.com/web-sdk/v1.36.1/dist/integrations/utils.js";
clearBeamStorage({ apiKey: "abc123", domain: "my-store.com" });
import { waitForElement, errors, events } from "https://sdk.beamimpact.com/web-sdk/v1.36.1/dist/integrations/utils.js";
try {
const parentElement = await waitForElement("#my-selector", { timeout: 1000 });
parentElement.appendChild(component);
} catch (err) {
if (err instanceof errors.BeamError) {
/* do something */
}
}
window.addEventListener(BeamNonprofitSelectEvent.eventName, async (event) => {});
一体化
Statsig A/B 测试
Beam与Statsig有一个A/B测试的预建集成.
import { StatsigPlugin } from "@beamimpact/web-sdk/dist/integrations/statsig";
import { init, getConfig } from "@beamimpact/web-sdk/dist/integrations/beam";
const beam = await init({
apiKey: "",
chainId: 1,
storeId: 1,
domain: "my-store.com", // in case site uses subdomains for different pages
plugins: [new StatsigPlugin({ statsigApiKey: "" })],
});
初始化 Statsig 插件将自动日志 statsig_init, (中文(简体) ), cart_created,以及 order_created 事件.
要手动日志附加事件 :
beam.plugins.statsig.logEvent(eventName, eventValue, metadataObject);
A/B测试的设置是Async. 等待Beam A/B测试设置在其他脚本中准备:
const beam = getConfig();
// Wait for promise to resolve
await beam.readyPromise; // resolves when plugins are all ready
// OR use event listeners
if (beam.status !== "ready") {
beam.addEventListener("beamstatuschange", (event) => {
const status = event.detail.status;
if (status === "ready") doSomething(beam);
else if (status === "error") handleError(event.detail.error);
});
}
可见度
一旦初始化,所有Beam组件都有 display: none 除非用户被分配到显示Beam的 A/B 测试组.
要隐藏额外元素, 添加 CSS 类Name beam-sync-visibility 给他们。 这个等级的元素会
自动拥有 display: none 如果用户不能看到Beam.
要访问JavaScript中的实验状态:
import { getConfig } from "@beamimpact/web-sdk/dist/integrations/beam";
getConfig().plugins.statsig.experiments.shouldShowBeam; // boolean