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 商品页。
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | object | 是 | 商品信息,字段见 商品信息字段 |
返回值
无。
示例
下面的例子从页面上读取商品名称、价格和图片,再交给 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 界面的样式。不调用时就是默认模式(页面底部的购买面板),只有想换成按钮模式或横幅模式时才需要调用。
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode | string | 是 | '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 之前执行,比如先弹一个确认框。只在按钮模式和横幅模式下生效。
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
handler | function | 是 | 会收到 setUIProductData 设置的商品信息。返回 true 才会继续购买。可以是 async 函数 |
示例
javascript
rakufun.setUICartHandler(async (product) => {
return confirm(`确认购买 ${product.title}?`);
});注意事项
- 只有返回
true才会继续购买。返回其他值(包括1、undefined),或者函数执行出错,都会取消 - 默认模式下这个设置不生效
quickBuy
用您自己的按钮发起购买(自定义模式)。调用后,SDK 会保存商品信息,并在新标签页打开 RAKUFUN 商品页。
参数
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
productData | object | 是 | 商品信息,字段见 商品信息字段 |
返回值
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 是字符串数组)。
基本信息
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
url | string | 建议 | 当前商品页的地址 | "https://example.com/product/123" |
title | string | 建议 | 商品名称 | "Bose QuietComfort 耳机" |
price | string | 建议 | 价格,只写数字,不要带 ¥ 或逗号 | "19800" |
images | string[] | 建议 | 商品图片地址,可以传多张 | ["img1.jpg", "img2.jpg"] |
description | string | 否 | 商品描述,超过 2000 字符会被截断 | "顶级降噪耳机" |
商品属性
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
minQuantity | string | 否 | 最低起购数量,不传默认 1 | "1" |
maxStock | string | 否 | 最大库存数量,不传默认 99 | "100" |
condition | string | 否 | 商品状态 | "全新" / "二手" / "展示品" |
brand | string | 否 | 品牌 | "Bose" |
shippingInfo | string | 否 | 运费信息 | "500" |
物流信息
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
deliveryTime | string | 否 | 预计配送时间 | "3-5 天" |
precautions | string | 否 | 注意事项 | "易碎品,请小心处理" |
规格参数
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
productParameters | string | 否 | 规格参数 | "尺寸: 20x15x10cm" |
自动生成
| 字段名 | 类型 | 必填 | 说明 | 示例 |
|---|---|---|---|---|
timestamp | string | 不用传 | 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"
};