APIリファレンス
本ページでは、SDKの各メソッドと商品情報のフィールドについて詳しく説明します。詳細を確認したいときにご利用ください。初めて導入する場合は、先にクイックスタートとUIモードをご覧ください。
各機能は rakufun オブジェクトのメソッドとして提供されます。どのメソッドも、SDKを読み込む行より後で呼び出してください。
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>メソッド一覧
| メソッド | 役割 | 使用するモード |
|---|---|---|
| setUIProductData | 表示中の商品の情報をSDKに設定する | デフォルト、ボタン、バナー |
| setUIMode | ボタンモードまたはバナーモードに切り替える | ボタン、バナー |
| setUICartHandler | 購入ボタンのクリック後、RAKUFUNを開く前に独自の関数を実行する | ボタン、バナー |
| quickBuy | 独自のボタンから購入処理を開始する | カスタム |
| disableAutoUI | SDK標準の画面下部パネルを表示しない | カスタム |
| enableDebug | 日本国内でテストする際にUIを表示する | すべてのモード(テスト専用) |
setUIProductData
表示中のページがどの商品かをSDKに設定します。ユーザーがSDKのUIの購入ボタンをクリックすると、設定した商品情報がRAKUFUNの商品ページに引き渡されます。
引数
| 引数名 | 型 | 必須 | 説明 |
|---|---|---|---|
data | object | 必須 | 商品情報。フィールドは商品情報フィールドを参照してください |
戻り値
なし
使用例
ページから商品名・価格・画像を読み取り、SDKに設定する例です。
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のUIの表示モードを切り替えます。呼び出さない場合はデフォルトモード(画面下部の購入パネル)になります。ボタンモードまたはバナーモードを使用する場合のみ、このメソッドを呼び出してください。
引数
| 引数名 | 型 | 必須 | 説明 |
|---|---|---|---|
mode | string | 必須 | 'default':画面下部パネル(呼び出さない場合はこのモード)'button':指定位置に表示する購入ボタン'banner':指定位置に表示するバナー |
戻り値
boolean:切り替えに成功した場合は true、上記3つ以外の値を指定した場合は false を返します。
使用例
<!-- 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 関数も使用できます |
使用例
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に失敗理由が入ります
使用例
<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標準の画面下部パネルを表示しないようにします。カスタムモードでは必ず呼び出してください。
使用例
<script src="https://sdk.rakufun.com/rakufun-universal.min.js"></script>
<script>
rakufun.disableAutoUI();
</script>注意事項
- SDKを読み込む行の直後に記述してください。呼び出しが遅すぎると、パネルがすでに表示されている場合があります
enableDebug
日本国内でテストする際に使用します。日本国内のIPアドレスでは初期設定でUIが表示されませんが、呼び出すと表示され、画面右上に RAKUFUN SDK DEBUG MODE と表示されます。
使用例
rakufun.enableDebug();注意事項
- テスト専用です。テスト後は必ずこの行を削除してください
商品情報フィールド
setUIProductData と quickBuy に渡す商品情報には、以下のフィールドを使用します。値はすべて文字列で指定します(images は文字列の配列)。
基本情報
| プロパティ名 | 型 | 必須 | 説明 | 例 |
|---|---|---|---|---|
url | string | 推奨 | 商品ページのURL | "https://example.com/product/123" |
title | string | 推奨 | 商品名 | "Bose QuietComfort ヘッドホン" |
price | string | 推奨 | 商品価格。数字のみで指定し、¥ やカンマは含めないでください | "19800" |
images | string[] | 推奨 | 商品画像のURLの配列(複数指定可) | ["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 | 任意 | 商品の仕様情報 | "サイズ:20×15×10cm" |
自動生成
| プロパティ名 | 型 | 必須 | 説明 | 例 |
|---|---|---|---|---|
timestamp | string | 指定不要 | SDKが自動生成 | "2024-11-06T12:00:00Z" |
完全な設定例
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接続方式:Bluetooth 5.1"
};