Dcart API¶

概要¶

Discount API は、Shopify ストアのディスカウントコードとギフトカードを管理する包括的な仕組みを提供します。この API を使うと、割引をプログラムから適用し、節約額を計算し、ストアフロントに割引機能を組み込めます。

はじめに¶

基本設定¶

Discount API は、アプリの読み込み時に自動的に初期化されます。グローバルの dcartAPI オブジェクトを使って、すぐに利用を開始できます。

// Wait for the API to be ready
window.addEventListener('DCART:appApi.initialized', function() {
  // API is now ready to use
  console.log('Discount API ready');
});

主な機能¶

ディスカウントコードの適用¶

apply() メソッドを使うと、顧客のディスカウントコードを有効にできます。

ディスカウントコードを1つ適用する:

dcartAPI.apply('SAVE20')
  .then(() => {
      console.log('Discount applied successfully');
  })
  .catch((error) => {
      console.error('Failed to apply discount:', error);
  });

複数のディスカウントコードを適用する:

dcartAPI.apply(['SAVE20', 'FREESHIP'])
  .then(() => {
    console.log('All discounts applied successfully');
  });

注: ディスカウントコードは自動的に小文字に変換され、前後の空白が削除されます。

ディスカウントコードの削除¶

remove() メソッドを使うと、有効なディスカウントコードを削除できます。

特定のディスカウントコードを削除する:

dcartAPI.remove('SAVE20')
  .then(() => {
    console.log('Discount removed successfully');
  });

有効なディスカウントコードをすべて削除する:

dcartAPI.remove()
  .then(() => {
    console.log('All discounts removed');
  });

ギフトカードの管理¶

適用済みのギフトカードを、その一意の ID を使って削除します。

dcartAPI.removeGiftCard('giftcard_id_here')
  .then(() => {
    console.log('Gift card removed successfully');
  });

割引の計算¶

カートに適用せずに、割引の計算結果をプレビューします。

const discountCodes = ['SAVE20', 'FREESHIP'];
const cartItems = [
  { id: 123, quantity: 2, price: 2500 },
  { id: 456, quantity: 1, price: 1000 }
];

dcartAPI.calculate(discountCodes, cartItems)
  .then((discountData) => {
    console.log('Calculated savings:', discountData);
    // discountData contains totals, savings, and applied discounts
  });

イベントシステム¶

Discount API は、割引のアクティビティを追跡し、独自のコードと連携するための包括的なイベントシステムを提供します。

イベントの購読¶

window.addEventListener('DCART:appApi.initialized', function() {
  // Subscribe to discount events
  dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
    console.log('Discount was applied:', data);
  });
});

利用可能なイベント¶

`dcartAPI.Events.Discount.Calculated`¶

割引の計算が完了したとき、または再計算されたときに発生します。

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  console.log('Discount calculated:', discountData);
  // Update UI with new totals
  updateCartTotals(discountData);
});

用途:

独自の合計金額の表示を更新する
カートの概要を更新する
分析イベントを発生させる

`dcartAPI.Events.Discount.Apply`¶

適用ボタンがクリックされたときに、割引が処理される前に発生します。

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Apply, function(data) {
  console.log('User clicked apply button');
  // Show loading indicator
  showLoadingSpinner();
});

用途:

読み込み中の状態を表示する
送信前にディスカウントコードを検証する
ユーザーの操作を追跡する

`dcartAPI.Events.Discount.Applied`¶

ディスカウントコードがカートに正常に適用されたときに発生します。

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  console.log('Discount successfully applied:', data);
  // Show success message
  showSuccessMessage('Discount applied!');
  // Track conversion
  gtag('event', 'discount_applied', { discount_code: data.code });
});

用途:

成功メッセージを表示する
カートの表示を更新する
ディスカウントの適用が成功したことを追跡する
プロモーションのワークフローを開始する

`dcartAPI.Events.Discount.Removed`¶

ディスカウントコードがカートから削除されたときに発生します。

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Removed, function(data) {
  console.log('Discount removed:', data);
  // Update UI to reflect removal
  removeDiscountFromDisplay(data.code);
});

用途:

カートの表示を更新する
プロモーションのメッセージを削除する
ディスカウントの削除を追跡する
プロモーションの状態をリセットする

イベント連携の完全な例¶

(function() {
  window.addEventListener('DCART:appApi.initialized', function() {
  // Track all discount interactions
  dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Apply, function() {
  // User started applying discount
  document.querySelector('.discount-form').classList.add('loading');
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  // Discount successfully applied
  document.querySelector('.discount-form').classList.remove('loading');
  showNotification('Discount applied: ' + data.code, 'success');

  // Track in analytics
  if (typeof gtag !== 'undefined') {
    gtag('event', 'discount_applied', {
      discount_code: data.code,
      discount_amount: data.amount
    });
  }
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  // Update custom total displays
  const savings = discountData.originalTotal - discountData.total;
  if (savings > 0) {
    document.querySelector('.savings-display').textContent =
      'You saved $' + (savings / 100).toFixed(2);
  }
});

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Removed, function(data) {
  // Handle discount removal
  showNotification('Discount removed: ' + data.code, 'info');
  document.querySelector('.savings-display').textContent = '';
});
  });
})();

エラー処理¶

ディスカウントの操作では、必ず適切なエラー処理を実装してください。

// Handle specific error types
dcartAPI.apply('INVALID_CODE') .then(() => { console.log('Success'); })
  .catch((error) => {
    console.error('Error applying discount:', error);
    if (error.message.includes('expired')) {
       showErrorMessage('This discount code has expired');
    } else if (error.message.includes('invalid')) {
       showErrorMessage('Invalid discount code');
    } else {
       showErrorMessage('Unable to apply discount. Please try again.');
    }
});

ベストプラクティス¶

パフォーマンスの考慮事項¶

一括処理 : 複数のコードを適用する場合は、配列を渡して apply() を1回だけ呼び出します
イベントのスロットリング : 割引の計算が連続して発生する場合は、デバウンスして性能の問題を防ぎます
エラーからの回復 : ネットワークの障害に備えて、再試行のロジックを実装します

ユーザー体験¶

読み込み中の状態 : ディスカウントの操作中は、必ず読み込み中のインジケーターを表示します
わかりやすいフィードバック : ディスカウントを適用または削除したら、すぐにフィードバックを表示します
検証 : 可能であれば、サーバーへのリクエストを減らすために、ディスカウントコードをクライアント側で検証します

連携のガイドライン¶

イベントの順序 : API の初期化後にイベントを購読します
メモリ管理 : コンポーネントが破棄されたときに、イベントの購読を解除します
フォールバック処理 : API が利用できない場合に備えて、フォールバックを実装します

よくある用途¶

URL のディスカウントを自動適用する¶

// Check URL for discount parameters and auto-apply
const urlParams = new URLSearchParams(window.location.search);
const discountCode = urlParams.get('discount');

if (discountCode) {
  window.addEventListener('DCART:appApi.initialized', function() {
    dcartAPI.apply(discountCode);
  });
}

プロモーションのカウントダウンとの連携¶

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Applied, function(data) {
  // Start countdown timer for time-sensitive discounts
  if (data.expiresAt) {
    startCountdownTimer(data.expiresAt);
  }
});

A/B テストとの連携¶

dcartAPI.eventBus.subscribe(dcartAPI.Events.Discount.Calculated, function(discountData) {
  // Track discount effectiveness for A/B testing
  analytics.track('discount_calculated', {
    test_variant: getTestVariant(),
    discount_amount: discountData.totalSavings,
    cart_total: discountData.total
  });
});

API リファレンス¶

メソッド¶

`apply(codes: string | string[]): Promise`¶

1つ以上のディスカウントコードをカートに適用します。

パラメーター:

codes: 単一のディスカウントコードの文字列、またはディスカウントコードの配列

戻り値: コードが適用されたときに解決される Promise

`remove(code?: string): Promise`¶

特定のディスカウントコードを削除します。コードを指定しない場合は、すべてのコードを削除します。

パラメーター:

code（省略可）: 削除するディスカウントコード。省略した場合は、すべてのコードを削除します

戻り値: コードが削除されたときに解決される Promise

`removeGiftCard(id: string): Promise`¶

カートからギフトカードを削除します。

パラメーター:

id: 削除するギフトカードの ID

戻り値: ギフトカードが削除されたときに解決される Promise

`calculate(codes: string[], items: any[]): Promise`¶

ディスカウントコードを適用せずに、割引額を計算します。

パラメーター:

codes: 計算するディスカウントコードの配列
items: 計算の対象となるカート商品の配列

戻り値: 割引の計算データとともに解決される Promise

`setCustomConfig(config: Record): void`¶

カスタム設定のオプションを設定します。

パラメーター:

config: カスタム設定を含む設定オブジェクト

`cloneAndInjectInfo(targetSelector: string): void`¶

割引の情報を対象の要素にクローンします。

パラメーター:

targetSelector: 対象の要素の CSS セレクター

イベント¶

イベント	説明
`Discount.Calculated`	割引の計算が完了
`Discount.Apply`	適用ボタンがクリックされた
`Discount.Applied`	ディスカウントが正常に適用された
`Discount.Removed`	カートからディスカウントが削除された

トラブルシューティング¶

よくある問題¶

ディスカウントが適用されない

指定したディスカウントコードが有効で、アクティブであることを確認します
カートが最低要件を満たしているか確認します
API が正しく初期化されていることを確認します

イベントが発生しない

イベントの購読が API の初期化後に行われていることを確認します
コンソールに JavaScript のエラーがないか確認します
イベント名のスペルが正しいか確認します

合計金額が更新されない

合計金額のセレクターが正しく設定されているか確認します
カスタム設定で、必要な要素が除外されていないか確認します
合計金額を計算する時点で、ページの要素が存在することを確認します

お困りですか？ support@syncu.be までご連絡ください。

Dcart API¶

概要¶

はじめに¶

基本設定¶

主な機能¶

ディスカウントコードの適用¶

ディスカウントコードの削除¶

ギフトカードの管理¶

割引の計算¶

イベントシステム¶

イベントの購読¶

利用可能なイベント¶

dcartAPI.Events.Discount.Calculated¶

dcartAPI.Events.Discount.Apply¶

dcartAPI.Events.Discount.Applied¶

dcartAPI.Events.Discount.Removed¶

イベント連携の完全な例¶

エラー処理¶

ベストプラクティス¶

パフォーマンスの考慮事項¶

ユーザー体験¶

連携のガイドライン¶

よくある用途¶

URL のディスカウントを自動適用する¶

プロモーションのカウントダウンとの連携¶

A/B テストとの連携¶

API リファレンス¶

メソッド¶

apply(codes: string | string[]): Promise¶

remove(code?: string): Promise¶

removeGiftCard(id: string): Promise¶

calculate(codes: string[], items: any[]): Promise¶

setCustomConfig(config: Record): void¶

cloneAndInjectInfo(targetSelector: string): void¶

イベント¶

トラブルシューティング¶

よくある問題¶

`dcartAPI.Events.Discount.Calculated`¶

`dcartAPI.Events.Discount.Apply`¶

`dcartAPI.Events.Discount.Applied`¶

`dcartAPI.Events.Discount.Removed`¶

`apply(codes: string | string[]): Promise`¶

`remove(code?: string): Promise`¶

`removeGiftCard(id: string): Promise`¶

`calculate(codes: string[], items: any[]): Promise`¶

`setCustomConfig(config: Record): void`¶

`cloneAndInjectInfo(targetSelector: string): void`¶