Skip to content

API 文档 ​

本页是 SDK 每个方法和商品信息字段的详细说明,用来查细节。第一次接入的话,建议先看 快速开始 和 UI 模式。

所有方法都通过全局对象 rakufun 调用,并且要写在引入 SDK 的那一行后面:

html
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>

方法一览 ​

方法作用用在哪种模式
setUIProductData告诉 SDK 当前是什么商品默认、按钮、横幅
setUIMode切换到按钮模式或横幅模式按钮、横幅
setUICartHandler用户点击购买后、打开 RAKUFUN 之前先执行您的函数按钮、横幅
quickBuy用您自己的按钮发起购买自定义
disableAutoUI不显示 SDK 自带的底部面板自定义
enableDebug在日本测试时让界面显示出来所有模式(仅测试用)

setUIProductData ​

告诉 SDK 当前页面是什么商品。用户点击 SDK 界面里的购买按钮时,会把这份信息带到 RAKUFUN 商品页。

参数 ​

参数名类型必填说明
dataobject是商品信息,字段见 商品信息字段

返回值 ​

无。

示例 ​

下面的例子从页面上读取商品名称、价格和图片,再交给 SDK:

javascript
window.addEventListener('load', () => {
  rakufun.setUIProductData({
    url: window.location.href,
    title: document.querySelector('.product-name').textContent,
    price: document.querySelector('.price').textContent.replace(/[^\d.]/g, ''), // 去掉 ¥ 和逗号,只留数字
    images: [document.querySelector('.main-image').src],
    minQuantity: '1',
    maxStock: '100'
  });
});

注意事项 ​

  • 没有调用这个方法就点击购买按钮,会提示「未设置商品数据,请调用 rakufun.setUIProductData(data)」
  • 可以多次调用来更新商品信息(比如用户切换了颜色或尺寸)。每次调用都会整个替换上一次的信息,不会合并,所以每次都要传完整的字段

setUIMode ​

切换 SDK 界面的样式。不调用时就是默认模式(页面底部的购买面板),只有想换成按钮模式或横幅模式时才需要调用。

参数 ​

参数名类型必填说明
modestring是'default':底部面板(不调用时就是这个)
'button':放在指定位置的购买按钮
'banner':放在指定位置的横幅

返回值 ​

boolean:切换成功返回 true,传入上面三个以外的值返回 false。

示例 ​

html
<!-- 1. 在想显示按钮的位置放一个空的 div -->
<div class="rakufun-sdk-embed-button"></div>

<!-- 2. 引入 SDK,然后切换到按钮模式 -->
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
  rakufun.setUIMode('button');
</script>

横幅模式写法一样:div 的类名换成 rakufun-sdk-embed-banner,调用 rakufun.setUIMode('banner')。

注意事项 ​

  • 按钮模式需要页面里有 <div class="rakufun-sdk-embed-button"></div>,横幅模式需要 <div class="rakufun-sdk-embed-banner"></div>,同一个页面可以放多个
  • 切换到按钮模式或横幅模式后,底部面板就不再显示

setUICartHandler ​

设置一个函数,在用户点击 SDK 的购买按钮后、打开 RAKUFUN 之前执行,比如先弹一个确认框。只在按钮模式和横幅模式下生效。

参数 ​

参数名类型必填说明
handlerfunction是会收到 setUIProductData 设置的商品信息。返回 true 才会继续购买。可以是 async 函数

示例 ​

javascript
rakufun.setUICartHandler(async (product) => {
  return confirm(`确认购买 ${product.title}?`);
});

注意事项 ​

  • 只有返回 true 才会继续购买。返回其他值(包括 1、undefined),或者函数执行出错,都会取消
  • 默认模式下这个设置不生效

quickBuy ​

用您自己的按钮发起购买(自定义模式)。调用后,SDK 会保存商品信息,并在新标签页打开 RAKUFUN 商品页。

参数 ​

参数名类型必填说明
productDataobject是商品信息,字段见 商品信息字段

返回值 ​

Promise<object>,用 await 拿到结果。quickBuy 不会抛出异常,成功和失败都通过返回值告诉您:

  • 成功:{ success: true, url, message, data }
  • 失败:{ success: false, message, error },message 是失败原因

示例 ​

html
<button id="my-buy-button">立即购买</button>

<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
  rakufun.disableAutoUI(); // 不显示 SDK 自带的底部面板

  document.getElementById('my-buy-button').addEventListener('click', async () => {
    const result = await rakufun.quickBuy({
      url: window.location.href,
      title: 'Bose QuietComfort 耳机',
      price: '26800',
      images: ['https://example.com/product.jpg'],
      description: '顶级降噪耳机'
    });
    if (!result.success) {
      console.error('购买失败:', result.message);
      alert('购买失败,请重试');
    }
  });
</script>

注意事项 ​

  • 不需要写 try/catch,看 result.success 判断成功与否
  • SDK 不会检查缺了哪些字段,请尽量传完整
  • 要在用户点击时调用,否则浏览器可能会拦截新标签页
  • 成功后当前页面不会跳走
  • 只用自己的按钮时,记得同时调用 disableAutoUI(),否则页面底部还会出现 SDK 的购买面板

disableAutoUI ​

不显示 SDK 自带的底部面板。用自定义模式时必须调用。

示例 ​

html
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
  rakufun.disableAutoUI();
</script>

注意事项 ​

  • 写在引入 SDK 那一行的紧后面。调用得太晚的话,面板可能已经显示出来了

enableDebug ​

在日本测试时使用。日本 IP 下 SDK 默认不显示界面,调用后会显示出来,页面右上角会出现 RAKUFUN SDK DEBUG MODE 标记。

示例 ​

javascript
rakufun.enableDebug();

注意事项 ​

  • 只用于测试,测试完记得删掉这行

商品信息字段 ​

setUIProductData 和 quickBuy 接收的商品信息,都是下面这些字段。所有字段的值都用字符串(images 是字符串数组)。

基本信息 ​

字段名类型必填说明示例
urlstring建议当前商品页的地址"https://example.com/product/123"
titlestring建议商品名称"Bose QuietComfort 耳机"
pricestring建议价格,只写数字,不要带 ¥ 或逗号"19800"
imagesstring[]建议商品图片地址,可以传多张["img1.jpg", "img2.jpg"]
descriptionstring否商品描述,超过 2000 字符会被截断"顶级降噪耳机"

商品属性 ​

字段名类型必填说明示例
minQuantitystring否最低起购数量,不传默认 1"1"
maxStockstring否最大库存数量,不传默认 99"100"
conditionstring否商品状态"全新" / "二手" / "展示品"
brandstring否品牌"Bose"
shippingInfostring否运费信息"500"

物流信息 ​

字段名类型必填说明示例
deliveryTimestring否预计配送时间"3-5 天"
precautionsstring否注意事项"易碎品,请小心处理"

规格参数 ​

字段名类型必填说明示例
productParametersstring否规格参数"尺寸: 20x15x10cm"

自动生成 ​

字段名类型必填说明示例
timestampstring不用传SDK 自动生成"2024-11-06T12:00:00Z"

完整示例 ​

javascript
const productData = {
  // 建议传入
  url: "https://example.com/product/123",
  title: "Bose QuietComfort 耳机",
  price: "26800",
  images: ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],

  // 可选
  minQuantity: "1",
  maxStock: "50",
  description: "顶级降噪耳机,提供卓越音质",
  condition: "全新",
  brand: "Bose",
  shippingInfo: "免运费",
  deliveryTime: "3-5 个工作日",
  precautions: "请在签收时检查包装完整性",
  productParameters: "颜色: 黑色\n重量: 240g\n连接方式: 蓝牙 5.1"
};

基于 MIT 许可证发布