API 文档

RAKUFUN SDK 提供简洁直观的 API，帮助您在电商站点中集成国际代购服务能力

setUIMode

设置 UI 展示模式，动态切换按钮或横幅样式

参数

参数名	类型	必填	说明
`mode`	`string`	是	UI 模式类型：`'button'` 或 `'banner'`

返回值

void - 无返回值

使用示例

步骤 1：引入 SDK

html

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

步骤 2：在 HTML 中添加容器

html

<!-- 按钮模式容器 -->
<div class="rakufun-sdk-embed-button"></div>

<!-- 横幅模式容器 -->
<div class="rakufun-sdk-embed-banner"></div>

步骤 3：在 JavaScript 中切换模式

javascript

// 切换到横幅模式
rakufun.setUIMode('banner');

// 切换到按钮模式
rakufun.setUIMode('button');

注意事项

使用前必须先引入 SDK
button 模式需要页面中存在 <div class="rakufun-sdk-embed-button"></div>
banner 模式需要页面中存在 <div class="rakufun-sdk-embed-banner"></div>
切换模式时会清理当前 UI 并重新初始化
会异步等待 IP 检测完成后再显示新模式的 UI

setUIProductData

为默认模式、浮动按钮或横幅 UI 预设商品数据，点击按钮时会自动使用该数据

参数

参数名	类型	必填	说明
`data`	`object`	是	商品数据对象，详见商品数据对象

返回值

void - 无返回值

使用示例

javascript

// 在页面加载时或商品数据准备好后，设置商品数据
window.addEventListener('load', () => {
  // 准备商品数据
  const productData = {
    title: document.querySelector('.product-name').textContent,
    price: document.querySelector('.price').textContent,
    images: [document.querySelector('.main-image').src],
    url: window.location.href,
    minQuantity: '1',
    maxStock: '100'
  };
  
  // 设置到 UI
  rakufun.setUIProductData(productData);
  
  // 现在用户点击浮动按钮时，会自动使用上面的数据
});

注意事项

使用前必须先引入 SDK
如果没有调用此方法就点击 UI 按钮，会提示"未设置商品数据，请调用 rakufun.setUIProductData(data)"
可以多次调用来更新商品数据

quickBuy

将商品添加到 Rakufun 购物车并自动打开结算页面。跳过内置 UI，使用您自己的设计和组件，仅调用 RAKUFUN 的一键购买 API。适合需要深度定制的场景

参数

参数名	类型	必填	说明
`productData`	`object`	是	商品数据对象，详见商品数据对象

返回值

Promise<void> - 返回 Promise，成功时 resolve，失败时 reject

使用示例

html

<!DOCTYPE html>
<html>
<head>
    <title>自定义购买按钮</title>
</head>
<body>
    <h1>精选商品</h1>
    <img src="product.jpg" alt="商品图片">
    <p class="price">¥26,800</p>
    
    <!-- 您的自定义按钮 -->
    <button id="my-buy-button" class="custom-btn">
        🛒 立即购买
    </button>

    <script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
    <script>
        document.getElementById('my-buy-button').addEventListener('click', async () => {
            try {
                await rakufun.quickBuy({
                    title: 'Bose QuietComfort 耳机',
                    price: '26800',
                    url: window.location.href,
                    images: ['product.jpg'],
                    description: '顶级降噪耳机',
                    minQuantity: '1',
                    maxStock: '50'
                });
            } catch (error) {
                console.error('购买失败:', error);
                alert('购买失败，请重试');
            }
        });
    </script>
</body>
</html>

注意事项

建议使用 try-catch 捕获错误
确保必填字段完整
调用成功后会自动跳转到 Rakufun 结算页面

isJapanUser

判断用户是否来自日本（同步方法）

参数

无

返回值

boolean - 如果用户来自日本返回 true，否则返回 false

使用示例

javascript

(async () => {
    await rakufun.initPromise; // 确保初始化完成
    await rakufun.detectUserRegion(); // 等待 IP 检测完成
    const isJapan = rakufun.isJapanUser(); // 同步调用
    if (isJapan) {
        console.log('用户来自日本');
    }
})();

注意事项

必须先等待 initPromise 完成才能获得准确结果
推荐使用异步方法 isJapanUserAsync()

isJapanUserAsync

判断用户是否来自日本（异步方法，推荐）

参数

无

返回值

Promise<boolean> - 返回 Promise，resolve 值为 true 表示用户来自日本，false 则不是

使用示例

javascript

// 直接使用异步方法（推荐）
(async () => {
    const isJapan = rakufun.isJapanUserAsync(); // 自动等待检测完成
    if (isJapan) {
        console.log('用户来自日本');
    }
})();

注意事项

推荐使用此方法，自动处理初始化等待
无需手动等待 initPromise

商品数据对象

基本信息

字段名	类型	必填	说明	示例
`url`	`string`	是	商品页面 URL	`"https://example.com/product/123"`
`title`	`string`	是	商品名称	`"Bose QuietComfort 耳机"`
`price`	`string`	是	商品价格（数字字符串）	`"19800"`
`images`	`string[]`	是	商品图片数组	`["img1.jpg", "img2.jpg"]`
`description`	`string`	否	商品详细描述	`"顶级降噪耳机"`

商品属性

字段名	类型	必填	说明	示例
`minQuantity`	`string`	是	最低起购数量	`"1"`
`maxStock`	`string`	是	最大库存数量	`"100"`
`condition`	`string`	否	商品状态	`"全新"` / `"二手"` / `"展示品"`
`brand`	`string`	否	品牌名称	`"Bose"`
`shippingInfo`	`string`	否	运费信息	`"500"`

物流信息

字段名	类型	必填	说明	示例
`deliveryTime`	`string`	否	预计配送时间	`"3-5 天"`
`precautions`	`string`	否	注意事项/附加说明	`"易碎品，请小心处理"`

规格参数

字段名	类型	必填	说明	示例
`productParameters`	`string`	否	商品参数（规格表等）	`"尺寸: 20x15x10cm"`

系统信息

字段名	类型	必填	说明	示例
`timestamp`	`string`	否	捕获时间戳（自动生成）	`"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"
};

API 文档 ​

setUIMode ​

参数 ​

返回值 ​

使用示例 ​

注意事项 ​

setUIProductData ​

参数 ​

返回值 ​

使用示例 ​

注意事项 ​

quickBuy ​

参数 ​

返回值 ​

使用示例 ​

注意事项 ​

isJapanUser ​

参数 ​

返回值 ​

使用示例 ​

注意事项 ​

isJapanUserAsync ​

参数 ​

返回值 ​

使用示例 ​

注意事项 ​

商品数据对象 ​

基本信息 ​

商品属性 ​

物流信息 ​

规格参数 ​

系统信息 ​

完整示例 ​

API 文档

setUIMode

参数

返回值

使用示例

注意事项

setUIProductData

参数

返回值

使用示例

注意事项

quickBuy

参数

返回值

使用示例

注意事项

isJapanUser

参数

返回值

使用示例

注意事项

isJapanUserAsync

参数

返回值

使用示例

注意事项

商品数据对象

基本信息

商品属性

物流信息

规格参数

系统信息

完整示例