指南

用一个 script 标签为网站添加 eSIM 小组件

Atli 小组件把完整的旅行 eSIM 商店和你的合作伙伴代码装进一个 script 标签。内容包括如何设置、调整样式、追踪销售,以及在 Sandbox 中测试。

浏览器中的一个网页,文章下方嵌入了列出目的地和价格的 Atli eSIM 小组件,旁边是拿着套餐卡片的带翅膀的蓝色 Atli 吉祥物

Atli 小组件让你只用一个 script 标签,就能在网站上添加完整的旅行 eSIM 商店。访客无需离开你的页面,就能搜索目的地、比较套餐、完成付款并获取 eSIM 二维码。脚本中已包含你的合作伙伴代码,用于将符合条件的购买计入你的账户。

嵌入不花钱,也不需要构建步骤。商品目录、支付和 eSIM 交付都由 Atli 负责。安装只需要一个容器和一个 script 标签。

这个页面上运行的就是真实的小组件:

把小组件加到页面上

在 partners.heyatli.com 登录,打开 集成。嵌入式小组件 卡片会显示适用于你网站的代码,其中已经带上你的合作伙伴代码。自定义 会打开位于 partners.heyatli.com/zh/dev/atli-widget 的小组件生成器,你可以在那里修改每一项设置,再重新复制代码。

partners.heyatli.com 集成页面上的“嵌入式小组件”卡片,显示适用于你网站的代码,以及“预览”和“自定义”按钮

如果你想直接添加代码,把 YOUR_CODE 换成你的合作伙伴代码:

HTML
<div id="heyatli-esim-checkout-container"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#heyatli-esim-checkout-container"
  data-referral="YOUR_CODE"
  defer
></script>

把它粘贴到页面 HTML 中商店应该出现的位置。小组件会占满容器的宽度,高度随显示的内容自动增长,不需要设置高度。如果省略 <div> 和 data-target,它会直接出现在 script 标签后面。

这个脚本约 17 KB,不需要安装任何其他东西。它会在来自 embed.heyatli.com 的 iframe 里加载商店,这个 iframe 读不到你的页面,也读不到页面的 Cookie 和存储。银行卡信息填在 iframe 里的 Stripe 支付表单中。

直接打开某个目的地

对于介绍特定国家的页面,你可以设置小组件显示该目的地的套餐。这段代码用于一篇德语指南,打开时直接显示日本,并以欧元标价:

HTML
<div id="japan-esim"></div>
<script
  src="https://embed.heyatli.com/embed.js"
  data-atli-widget
  data-target="#japan-esim"
  data-referral="YOUR_CODE"
  data-destination="jp"
  data-lang="de"
  data-lang-priority="widget"
  data-currency="EUR"
  defer
></script>
以德语和欧元价格打开日本页面的 Atli 小组件,列出 5 到 30 天的无限流量套餐,每个套餐都有 eSIM kaufen 按钮

data-destination 可以是两个字母的国家代码(jp)、小组件任一支持语言中的国家名称(Japan、日本)、区域(europe、south_east_asia)或套餐 ID。套餐 ID 会直接打开该套餐的结账页面。只有找到有效匹配时,小组件才会打开对应的目的地。否则会显示默认首页。无论哪种情况,访客都还能搜索所有目的地。

data-favorites 会用你自选的最多 32 个目的地填充 热门 标签页,并按你列出的顺序排列。例如:data-favorites="jp, kr, tw, asia"。

小组件设置

所有设置都是可选的。在 script 标签里,每项设置都是一个 data- 属性。在 JavaScript 里则用同名的驼峰写法:data-lang-priority 变成 langPriority。

属性作用
data-referral你的合作伙伴代码。购买的新客户会关联到你。
data-destination直接打开某个目的地或套餐。
data-favorites为 热门 标签页指定最多 32 个目的地,用逗号分隔。
data-lang小组件的语言。不设置时使用访客浏览器的语言。
data-lang-priority设为 widget 时,即使访客选了别的语言,也保持你设定的语言,并隐藏语言菜单。
data-currency价格和付款使用的货币。默认是 USD。
data-currency-priority设为 widget 时,即使访客选了别的货币,也保持你设定的货币。
data-themelight 或 dark。不设置时跟随访客设备的设置。
data-theme-priority设为 widget 时保持你设定的主题,并隐藏主题设置。
data-css你为小组件准备的样式表的 https:// 地址。
data-boot直接打开访客自己的某个页面:esims、credits、vouchers、refer、settings、payment-methods、groups 或 profile。esim 会打开分享 eSIM 的安装页面,不需要账户;要安装哪张 eSIM,由你在 data-lpa 里填写的代码决定。
data-anonymous-cards设为 true 时,未登录的访客也能在这个浏览器里保存银行卡。默认关闭。
data-stripe-link设为 false 时,从支付表单中去掉 Stripe Link。
data-analytics设为 off 时,小组件不再加载自己的分析工具。
data-consent填 all、analytics 或 none,与你的 Cookie 横幅收集到的同意选项保持一致。
data-env设为 staging 时,小组件在 Atli 的 Sandbox 上运行。正式页面上不要加。

小组件支持 15 种语言:en 英语、pt 葡萄牙语、es 西班牙语、fr 法语、it 意大利语、de 德语、pl 波兰语、ru 俄语、zh 中文、ko 韩语、ja 日语、id 印尼语、vi 越南语、ms 马来语和 ar 阿拉伯语。计价货币可选 AUD、CAD、EUR、GBP、HKD、JPY、KRW、SGD、TWD、USD 和 VND。不支持的值会被忽略。例如,data-currency="EUROS" 会按默认的 USD 计价。

在单页应用中添加小组件

script 标签会在页面加载时初始化小组件,但不会自动响应应用中的路由变化。在 React、Vue、Next.js 或任何不刷新就切换页面的应用里,在 HTML 中加载一次脚本,再从你的代码里挂载小组件:

HTML
<script src="https://embed.heyatli.com/embed.js"></script>
JavaScript
const widget = HeyAtli.init({
  target: '#esim',
  referral: 'YOUR_CODE',
  destination: 'jp',
  lang: 'de',
  currency: 'EUR',
});

// Change settings later without rebuilding the frame
widget.update({ destination: 'th' });

// Remove it when the page goes away
widget.destroy();

target 可以是 CSS 选择器,也可以是一个元素。update() 会把你传入的内容合并到当前设置里,不会重新加载 iframe。在 React 里,把小组件放进一个 effect 就行:

JSX
import { useEffect, useRef } from 'react';

export function EsimStore({ destination }) {
  const ref = useRef(null);

  useEffect(() => {
    const widget = window.HeyAtli.init({
      target: ref.current,
      referral: 'YOUR_CODE',
      destination,
    });
    return () => widget.destroy();
  }, [destination]);

  return <div ref={ref} />;
}

开发环境下,React 的严格模式会把每个 effect 运行一次、清理掉,再运行一次。在清理函数里加上 destroy(),以免出现重复的小组件实例。

用 CSS 调整小组件样式

给 data-css 填上你网站上某个样式表的完整 https:// 地址。小组件在 iframe 里先加载自己的样式,再加载你的样式表,所以普通选择器不用 !important 也能生效。如果文件加载失败,小组件会保持默认外观。

有一行是你改不了的。每个页面最后都有一行 由 Atli 提供支持 | 客服 页脚,你的样式表既不能改它的样式,也不能把它藏起来。如果样式表把它隐藏、调淡、裁掉或遮住,这个样式表就会被丢弃,小组件在这次访问余下的时间里恢复默认外观,浏览器控制台会说明原因。

先从小组件的 CSS 变量入手。访客看到的可能是浅色主题,也可能是深色主题,所以两套变量都要设置:

CSS
.atli-widget {
  --atli-font-family: 'Inter', system-ui, sans-serif;
  --atli-color-accent: #0f766e;
  --atli-color-accent-hover: #115e59;
  --atli-color-accent-text: #ffffff;
  --atli-radius-md: 6px;
}

.atli-widget[data-theme='dark'] {
  --atli-color-accent: #2dd4bf;
  --atli-color-accent-hover: #5eead4;
  --atli-color-accent-text: #042f2e;
}

sunset.css 和 mono.css 是完整的示例,覆盖了所有常用变量,并附有注释。银行卡输入框位于 Stripe 自己的 iframe 里,任何样式表都碰不到。小组件生成支付表单时,会改为把你的强调色、文字色、表面色、字体和圆角半径交给 Stripe。

Atli 小组件中同一个日本页面的四种样式:默认浅色外观、深色主题、带橙色按钮和衬线字体的 sunset.css,以及使用等宽字体和灰色按钮的 mono.css

通过 CSS 自定义,你可以让小组件与网站的品牌风格保持一致。如果需要完全掌控界面,可以使用 Atli API,不过这需要额外的开发工作。

用小组件事件追踪购买

小组件会发出事件,你的网站可以用这些事件追踪访客的操作和购买。要把购买数据发送到你的分析工具,就用 HeyAtli.init() 挂载小组件,并监听 purchase.completed。这个处理函数会以 GA4 的电子商务格式,把每笔购买交给 Google Tag Manager:

JavaScript
const widget = HeyAtli.init({ target: '#esim', referral: 'YOUR_CODE' });

widget.on('purchase.completed', function (detail) {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({ ecommerce: null });
  window.dataLayer.push({
    event: 'purchase',
    ecommerce: {
      transaction_id: detail.transactionId,
      value: detail.value,
      currency: detail.currency,
      items: detail.items,
    },
  });
});

items 本身就是 GA4 的商品格式,所以可以原样放进 dataLayer。value 以货币的主单位计,写作 12.99 而不是 1299。第一次 push 会清空上一个 ecommerce 对象,Google 建议在每个电子商务事件之前都这样做。

其他事件包括 checkout.opened、payment.started 和 payment.failed。处理函数会收到 (detail, info),info.action 是事件名,所以 widget.on('*', handler) 可以把所有事件一起转发。要在浏览器控制台里记录每个事件,可以在 init() 里加上 debug: true,或者在 script 标签上加上 data-debug="true"。

事件只会发送到 Atli 白名单上的域名。heyatli.com 和 localhost 都在白名单上,所以你可以在自己的电脑上开发。这也是为什么在 localhost 上好好的处理函数,到了正式网站上可能就收不到事件了。请写信给 [email protected],把你的域名加进去。即使无法追踪事件,小组件仍可正常处理购买。

在 Sandbox 中测试

加上 data-env="staging",或在 HeyAtli.init() 里写 env: 'staging',小组件就会在 Atli 的 Sandbox 上运行。角落里会出现“沙盒”标签,测试横幅上会淡淡地显示你的合作伙伴代码,方便你确认页面已经读到了它。付款时用 Stripe 的测试卡 4242 4242 4242 4242,有效期填任意未来日期,安全码随意填写。Sandbox 账户和正式账户是分开的。Sandbox 的 eSIM 来自测试运营商,无法安装到手机上,Sandbox 上的销售也永远不计分成。

小组件默认使用生产环境。发布前请删掉 data-env="staging",因为 Sandbox 只接受测试付款。

小组件销售如何计入你名下

在小组件里购买的访客,会在登录或付款时关联到你,除非在此之前已经有别的合作伙伴的代码或更早的购买。小组件会在访客的浏览器里记住你的代码 72 小时,所以第二天回来购买的人照样算你的。首次购买之后,关联就是永久的,同一个 Atli 账户以后的购买也都算你的。

价格和 Atli 商店里一样,你的代码带的折扣会在结账时显示。收益和结算请看 Atli 推广联盟的分成方式。

常见问题

Atli 小组件收费吗?
不收费。嵌入是免费的,收款和 eSIM 交付由 Atli 负责。访客买了什么,你就从中拿到收入分成。
我需要自己的 Stripe 账户吗?
不需要。小组件在自己的 iframe 里通过 Atli 的 Stripe 账户收款,所以银行卡信息根本不会经过你的网站。买家银行卡账单上显示的是 Atli 的名字。
访客能直接从小组件安装 eSIM 吗?
能。付款后,访客会收到 eSIM 二维码、iPhone 和 Android 的安装链接,以及手动安装所需的信息。手机上的具体步骤,可以看我们的 iPhone 和 Android 安装指南。
能把小组件限制在我写到的国家吗?
部分可以。data-destination 让它直接打开某个目的地,data-favorites 用你自选的最多 32 个目的地填充 热门 标签页。访客仍然可以搜索完整的目录。
小组件会拖慢我的页面吗?
加载时不会。加载器约 17 KB,商店本身要等 iframe 接近页面的可见区域时才会加载。如果小组件位于文章末尾附近,它的内容会在访客接近该部分时加载。
一个页面上能放两个小组件吗?
可以。给每个小组件各自的容器和 script 标签,或者为每个容器分别调用一次 HeyAtli.init()。