機能 (Capabilities)

機能は、ウェブサイトが追加の機能を提供するために実装する統合フックです。例えば、Fanplayrの「おすすめ商品」ウィジェット内にカートに追加ボタンを有効にするために、商品をショッピングカートに追加する処理を行う関数を定義する、といった用途があります。

利用可能な機能

機能	説明
addProductToCart	おすすめ商品ウィジェットの「カートに追加」ボタン
applyToCart	割引/オファーウィジェットの「オファー適用」ボタン
sessionOffer	Fanplayrが訪問者にオファーを提示した際にストアに通知する

機能は、Fanplayrスクリプトのロード後に発火するfanplayr_readyコールバック内で、fanplayr.platform.capabilitiesオブジェクトに登録されます。

window.fanplayr_ready = function () {
  // ここに機能を登録します
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    /* ... */
  };
  window.fanplayr.platform.capabilities.sessionOffer = function (event) {
    /* ... */
  };
};

---

商品をカートに追加する

addProductToCart機能により、Fanplayrのおすすめ商品ウィジェットは、訪問者がページを離れることなく商品を直接カートに追加できるようになります。

ハンドラーのシグネチャ

interface AddProductEvent {
  /** Fanplayrカタログで定義された商品ID */
  id: string
  /** 商品に定義された任意のカスタムデータ */
  customData?: Record<string, any>
}

fanplayr.platform.capabilities.addProductToCart = (event: AddProductEvent) => void | Promise<void>

ハンドラーは、Fanplayrカタログからの商品idを含むAddProductEventオブジェクトを受け取ります。Promiseを返すことがサポートされており、Fanplayrはウィジェットのボタンを再度有効にする前にPromiseが解決されるのを待ち、重複送信を防ぎます。数量などの追加のカートパラメータは、ハンドラーが責任を持って処理します。

基本的な例

公開する前に

これはあくまで例です。fetch呼び出し全体を、お客様のストア独自のカートAPIロジックに置き換える必要があります。

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.addProductToCart = function (product) {
    // ここをストアの実際のカートAPIに置き換えてください:
    return fetch('/api/cart/add', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ productId: product.id })
    });
  };
};

customDataの使用

Fanplayrカタログの商品にカスタム属性（例: バリアントID、SKU、内部参照など）を定義した場合、それらはproduct.customDataで利用でき、カートAPIに渡すことができます。

---

オファーをカートに適用する

applyToCart機能により、Fanplayrのオファーおよび割引ウィジェットは、クーポンやプロモーションコードを訪問者のカートに直接適用できます。

商品をカートに追加する機能とは異なります

この機能は、商品ではなく、割引/オファーの_コード_（例: FREESHIP）を処理します。商品のおすすめを統合したい場合は、商品をカートに追加するを参照してください。

この機能を実装するには、シンプルなURLリダイレクト方式と、より複雑な統合のためのカスタムハンドラーの2つの方法があります。

オプション1 — URLリダイレクト

ユーザー追跡設定の一部としてapplyToCartUrlを提供します。オファーコードを挿入する場所には%cプレースホルダーを含めます。

{
  type: 'st',
  accountKey: '7e43c8cddccade2b95ee5286ba89758a',
  applyToCartUrl: 'https://example.com/applyOffer.php?code=%c',
  data: {
    // ユーザー追跡データ
  }
}

訪問者がオファーを有効にすると、Fanplayrは%cをオファーコード（例: FREESHIP）に置き換えてブラウザをこのURLにリダイレクトし、次のようになります。

https://example.com/applyOffer.php?code=FREESHIP

その後、エンドポイントは次のことを行う必要があります。

1. 指定されたオファーコードをカートに適用します。
2. ユーザーをカートページにリダイレクトします。
3. ベストプラクティス: コードを適用できない場合は、その理由を説明する有益なメッセージを表示します。

オプション2 — カスタムハンドラー

コードの適用にクライアントサイドのロジック（例: JavaScriptカートAPIの呼び出し）が必要な場合は、代わりにハンドラー関数を登録します。

ハンドラーのシグネチャ

interface AddOfferEvent {
  /** 適用するオファー/クーポンコード */
  code: string
}

fanplayr.platform.capabilities.applyToCart = (event: AddOfferEvent) => void | Promise<void>

基本的な例

公開する前に

これはあくまで例です。ハンドラーの本体全体を、お客様のストア独自のオファーコード適用ロジックに置き換える必要があります。

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event) {
    // ここを、オファーコードをカートに適用するストアのロジックに置き換えてください
    console.warn('Fanplayr: applyToCart capability is not implemented');
  };
};

非同期の例

Promiseを返すと、Fanplayrはそれが解決されるのを待ってからウィジェットUIを再度有効にし、リクエストが処理中の間にハンドラーが複数回トリガーされるのを防ぎます。

公開する前に

これはあくまで例です。fetch呼び出し全体を、お客様のストア独自のカートAPIロジックに置き換える必要があります。

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = async function (event) {
    // ここをストアの実際のカートAPIに置き換えてください:
    await fetch('/api/apply-code-to-cart', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};

レガシー: 完了コールバック

この機能の以前のバージョンでは、Promiseの代わりに、2番目の引数としてオプションのdoneFnコールバックがサポートされていました。これは下位互換性のために依然としてサポートされていますが、新しい実装では上記のPromiseアプローチが推奨されます。

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.applyToCart = function (event, doneFn) {
    $.ajax({
      type: 'GET',
      url: '/api/apply-code-to-cart',
      data: { code: event.code },
      complete: function () {
        doneFn();
      }
    });
  };
};

---

セッションオファー

sessionOffer機能は、Fanplayrのセッションオファー機能の一部であり、不正なユーザーがFanplayrセッション外で割引コードを請求するのを防ぐのに役立ちます。

Fanplayrが訪問者にオファーを提示すると、そのオファーコードを使ってsessionOfferハンドラーを呼び出します。ハンドラーは、コードが訪問者のセッション中に有効であることをマークする責任があり、これによりストアはカートに適用する前にそのコードを検証できます。

URLベースの代替

JavaScriptハンドラーではなく、サーバーサイドのアプローチを希望する場合は、ユーザー追跡設定でsessionOfferUrlを提供することもできます。セッションオファーで詳細を確認してください。

ハンドラーのシグネチャ

interface SessionOfferEvent {
  /** 訪問者に提示されているオファーコード */
  code: string
}

fanplayr.platform.capabilities.sessionOffer = (event: SessionOfferEvent) => void | Promise<void>

Promiseを返すことがサポートされています。Promiseが拒否された場合、Fanplayrはセッションオファーが失敗したとみなし、後の呼び出しで再試行する可能性があります。Promiseが解決された場合、またはPromiseが返されなかった場合、オファーは正常に登録されたと見なされます。

例

公開する前に

これはあくまで例です。ハンドラーの本体を、お客様のストア独自の、オファーコードを現在のセッションで有効とマークするロジックに置き換える必要があります。

window.fanplayr_ready = function () {
  window.fanplayr.platform.capabilities.sessionOffer = async function (event) {
    // ここを、現在の訪問者セッションに対してコードを有効とマークするストアのロジックに置き換えてください:
    await fetch('/api/session-offers/allow', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ code: event.code })
    });
  };
};