API Reference
This page describes every SDK method and product information field in detail, for when you need to look something up. If this is your first integration, start with Getting Started and UI Modes.
All methods are called on the global rakufun object, and must come after the line that includes the SDK:
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>Methods at a Glance
| Method | What it does | Used in |
|---|---|---|
| setUIProductData | Tells the SDK which product this is | Default, button, banner |
| setUIMode | Switches to button mode or banner mode | Button, banner |
| setUICartHandler | Runs your function after the user clicks to buy, before RAKUFUN opens | Button, banner |
| quickBuy | Starts a purchase from your own button | Custom |
| disableAutoUI | Doesn't show the SDK's bottom panel | Custom |
| enableDebug | Shows the interface when testing from Japan | All modes (testing only) |
setUIProductData
Tells the SDK which product the current page is about. When the user clicks the purchase button in the SDK's interface, this information is passed to the RAKUFUN product page.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
data | object | Yes | Product information, see Product Information Fields for the fields |
Return Value
None.
Example
This example reads the product name, price, and image from the page and passes them to the SDK:
window.addEventListener('load', () => {
rakufun.setUIProductData({
url: window.location.href,
title: document.querySelector('.product-name').textContent,
price: document.querySelector('.price').textContent.replace(/[^\d.]/g, ''), // Remove ¥ and commas, keep digits only
images: [document.querySelector('.main-image').src],
minQuantity: '1',
maxStock: '100'
});
});Notes
- If the purchase button is clicked before this method is called, the message "未设置商品数据,请调用 rakufun.setUIProductData(data)" (no product data set) is shown
- You can call it multiple times to update the product information (for example when the user picks another color or size). Each call replaces the previous information entirely, nothing is merged, so always pass all the fields
setUIMode
Switches the style of the SDK's interface. Without calling it, you get the default mode (a purchase panel at the bottom of the page). You only need to call it to switch to button mode or banner mode.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
mode | string | Yes | 'default': bottom panel (used when not called)'button': a purchase button where you choose'banner': a banner where you choose |
Return Value
boolean: true if the switch succeeded, false for any value other than the three above.
Example
<!-- 1. Put an empty div where you want the button -->
<div class="rakufun-sdk-embed-button"></div>
<!-- 2. Include the SDK, then switch to button mode -->
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
rakufun.setUIMode('button');
</script>Banner mode works the same way: change the div's class name to rakufun-sdk-embed-banner and call rakufun.setUIMode('banner').
Notes
- Button mode needs
<div class="rakufun-sdk-embed-button"></div>on the page, and banner mode needs<div class="rakufun-sdk-embed-banner"></div>. You can place more than one on the same page - After switching to button mode or banner mode, the bottom panel is no longer shown
setUICartHandler
Sets a function that runs after the user clicks the SDK's purchase button and before RAKUFUN opens, for example to show a confirmation dialog first. It only takes effect in button mode and banner mode.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
handler | function | Yes | Receives the product information set by setUIProductData. The purchase continues only if it returns true. Can be an async function |
Example
rakufun.setUICartHandler(async (product) => {
return confirm(`Confirm purchase of ${product.title}?`);
});Notes
- The purchase continues only if the function returns
true. Any other return value (including1andundefined), or an error in the function, cancels it - This setting has no effect in the default mode
quickBuy
Starts a purchase from your own button (custom mode). When called, the SDK saves the product information and opens the RAKUFUN product page in a new tab.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
productData | object | Yes | Product information, see Product Information Fields for the fields |
Return Value
Promise<object>, use await to get the result. quickBuy never throws; both success and failure are reported through the return value:
- Success:
{ success: true, url, message, data } - Failure:
{ success: false, message, error }, wheremessageis the reason
Example
<button id="my-buy-button">Buy Now</button>
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
rakufun.disableAutoUI(); // Don't show the SDK's bottom panel
document.getElementById('my-buy-button').addEventListener('click', async () => {
const result = await rakufun.quickBuy({
url: window.location.href,
title: 'Bose QuietComfort Headphones',
price: '26800',
images: ['https://example.com/product.jpg'],
description: 'Premium noise-canceling headphones'
});
if (!result.success) {
console.error('Purchase failed:', result.message);
alert('Purchase failed, please try again');
}
});
</script>Notes
- No try/catch needed; check
result.successto see whether it succeeded - The SDK doesn't check which fields are missing, so pass them as completely as you can
- Call it when the user clicks, otherwise the browser may block the new tab
- On success, the current page does not navigate away
- When you only use your own button, also call
disableAutoUI(), otherwise the SDK's purchase panel will still appear at the bottom of the page
disableAutoUI
Doesn't show the SDK's bottom panel. Required when using custom mode.
Example
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
rakufun.disableAutoUI();
</script>Notes
- Put it right after the line that includes the SDK. If it's called too late, the panel may already be showing
enableDebug
For testing from Japan. The SDK hides its interface by default for Japanese IPs. After calling this, the interface is shown and a RAKUFUN SDK DEBUG MODE badge appears in the top-right corner of the page.
Example
rakufun.enableDebug();Notes
- For testing only. Remember to remove this line after testing
Product Information Fields
The product information passed to setUIProductData and quickBuy uses the fields below. All values are strings (images is an array of strings).
Basic Information
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
url | string | Recommended | Address of the current product page | "https://example.com/product/123" |
title | string | Recommended | Product name | "Bose QuietComfort Headphones" |
price | string | Recommended | Price, digits only, no ¥ or commas | "19800" |
images | string[] | Recommended | Product image addresses, more than one is fine | ["img1.jpg", "img2.jpg"] |
description | string | No | Description, truncated beyond 2000 characters | "Premium noise-canceling headphones" |
Product Attributes
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
minQuantity | string | No | Minimum order quantity, defaults to 1 | "1" |
maxStock | string | No | Maximum stock quantity, defaults to 99 | "100" |
condition | string | No | Product condition | "New" / "Used" / "Display item" |
brand | string | No | Brand | "Bose" |
shippingInfo | string | No | Shipping information | "500" |
Logistics Information
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
deliveryTime | string | No | Estimated delivery time | "3-5 days" |
precautions | string | No | Precautions | "Fragile, handle with care" |
Specifications
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
productParameters | string | No | Specifications | "Size: 20x15x10cm" |
Generated Automatically
| Field | Type | Required | Description | Example |
|---|---|---|---|---|
timestamp | string | Don't pass | Generated by the SDK | "2024-11-06T12:00:00Z" |
Complete Example
const productData = {
// Recommended
url: "https://example.com/product/123",
title: "Bose QuietComfort Headphones",
price: "26800",
images: ["https://example.com/img1.jpg", "https://example.com/img2.jpg"],
// Optional
minQuantity: "1",
maxStock: "50",
description: "Premium noise-canceling headphones with exceptional sound quality",
condition: "New",
brand: "Bose",
shippingInfo: "Free shipping",
deliveryTime: "3-5 business days",
precautions: "Please check the packaging upon delivery",
productParameters: "Color: Black\nWeight: 240g\nConnection: Bluetooth 5.1"
};