ウィジェット・デザイン

1. 概要

• ウィジェット・デザインは、取引先サイトにコードを1行追加するだけで自動的に表示される連携方式です。

• ウィジェット・デザイン内でユーザーが商品をクリックして詳細ページへ遷移しようとする際、その動作を取引先が希望する方法(独自のページ遷移ロジックなど)で直接連携できるよう、「イベント発生時に自動的に実行される関数(コールバック)」を提供します。

---

2. 連携方法

2-1. クイックスタート

• 以下のコード断片(スニペット)をページに貼り付けると、このコードが実際のウィジェットプログラム(メインスクリプト)を自動的に読み込み(ローダー)、初期化まで行います。

<script>
  (function (w, d, s, l) {
    w[l] = w[l] || { q: [] };
    if (!w[l].init) {
      w[l].init = function (c) {
        w[l].q.push({ c: c });
      };
    }
    var f = d.getElementsByTagName(s)[0];
    var j = d.createElement(s);
    j.async = true;
    j.setAttribute('data-vendor-id', 'YOUR_VENDOR_ID');
    j.src = 'https://cdn.genser.ai/dist/genser-discovery-loader-jp.min.js';
    f.parentNode.insertBefore(j, f);
  })(window, document, 'script', 'genserDiscovery');

  window.genserDiscovery.init({
    vendorId: 'YOUR_VENDOR_ID',
    environment: 'web',
    onUrlOpen: function (payload, context) {
      var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
      if (!url) return { ok: false, reason: 'url_not_found' };
      window.location.href = url;
      return { ok: true, url: url };
    },
  });
</script>

2-2. init(config)

• 役割: この関数を呼び出すことで、ウィジェットが実際に画面に表示され、動作を開始します。

• 関数名: window.genserDiscovery.init

• 戻り値: 実行結果を非同期で通知する値(Promise)

• パラメーター

オプション	型	必須	説明
vendorId	string	必須	取引先識別ID
onUrlOpen	function	推奨	商品詳細/外部遷移イベント処理コールバック(3章参照)
environment	'web' | 'webview'	-	実行環境。未指定の場合は自動検出
onReady	function	-	UIレンダリング完了後に1回呼び出し
onError	function	-	初期化・読み込み失敗時にエラーオブジェクトとともに呼び出し

2-3. コールバック名(エイリアス)

遷移処理コールバックは以下のいずれかの名前で指定でき、複数指定した場合は上から優先的に適用されます。

onOpen > openCallback > onUrlOpen > onProductOpenDetail > onProductDetail > productDetailCallback

onUrlOpenを標準として使用することを推奨します。

2-4. environment自動検出

environmentを指定しない場合、SDKが実行環境を自動的に検出します。ネイティブWebView(ブリッジが存在する)環境ではwebview、それ以外ではwebとして動作します。通常のWeb連携ではenvironment: 'web'を明示することを推奨します。

2-5. ウィジェットタイプ(デフォルト / カスタム)

ウィジェットタイプは管理画面で設定し、2つの方式があります。

• デフォルト: 追加のスクリプト作業なしで、SDKが提供するオーバーレイのトリガーをそのまま使用します。

• カスタム: SDKが提供するデフォルトウィジェット要素の代わりに、取引先が独自に作成した要素(ボタンなど)をトリガーとして使用します。この場合、該当要素のクリックイベントにopen()を、閉じる動作が必要な箇所にはclose()を直接連携する必要があります。

document.querySelector('#my-custom-trigger').addEventListener('click', function () {
  window.genserDiscovery.open();
});

document.querySelector('#my-custom-close-button').addEventListener('click', function () {
  window.genserDiscovery.close();
});

ウィジェットタイプをカスタムに設定した場合、open()/close()を連携しないとオーバーレイが開閉しません。open()/close()の詳細仕様は[5. APIリファレンス]を参照してください。

---

3. イベント処理方法

ユーザーがウィジェット内で商品をクリックした際、そのクリックを自社サイトが検知して反応できるようにする方法は2つあります: コールバック方式(イベント発生時に自動実行される関数をinit()にあらかじめ登録するonUrlOpen)と購読方式(必要なイベントだけを個別に登録して受け取るon/off)。

product.openDetailイベントがポップアップ(モーダル)を経由して発生するか、クリックと同時に発生するかは、管理画面の[その他表示設定 > 商品カード > PDP表示方法]の設定によって異なります。

イベント名	説明
product.openDetail	商品詳細ページへの遷移リクエスト

3-1. onUrlOpen(コールバック方式)

onUrlOpen(payload, context)

コールバックの引数はpayload、contextの2つです。 イベントタイプが必要な場合はcontext.message.typeで確認します。

引数	説明
payload	クリックされた商品の情報と遷移先URLが含まれるデータ
context	このイベントに応答(返信)できる経路となるオブジェクト(元のメッセージはcontext.message、応答関数はcontext.reply)

payloadフィールド

フィールド	型	説明
productSku	string	商品SKU
pcUrl	string	PC遷移URL
mobileUrl	string | null	モバイル遷移URL
fallbackUrl	string	既定のfallback URL
source	string	イベント発生箇所(例: product-card)
utmParams	object	(任意)URLクエリにマージするUTMパラメーター

例

{
  "productSku": "3370616",
  "pcUrl": "https://shop.example.jp/product/3370616",
  "mobileUrl": null,
  "fallbackUrl": "https://shop.example.jp/product/3370616",
  "source": "product-card"
}

URL優先順位

遷移先URLは以下の順序で選択することを推奨します。(SDKの既定処理も同じ順序を使用します。)

優先順位	フィールド
1	payload.pcUrl
2	payload.mobileUrl
3	payload.fallbackUrl

推奨例

function handleUrlOpen(payload, context) {
  var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
  if (!url) {
    return { ok: false, reason: 'url_not_found' };
  }
  window.location.href = url;
  return { ok: true, url: url };
}

window.genserDiscovery.init({
  vendorId: 'YOUR_VENDOR_ID',
  environment: 'web',
  onUrlOpen: handleUrlOpen,
});

3-2. on / off(購読方式)

init()にコールバックを登録する代わりに、必要なイベントが発生するたびに実行する処理を個別にあらかじめ登録(購読)しておくこともできます。

window.genserDiscovery.on('product.openDetail', function (payload, context) {
  var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
  if (!url) {
    context.reply('product.openDetail.result', { ok: false, reason: 'url_not_found' });
    return;
  }
  window.location.href = url;
  context.reply('product.openDetail.result', { ok: true, url: url });
});

on()は戻り値が自動的に返信されません。

on()で購読したハンドラーは戻り値が自動的に返信されないため、必ずcontext.reply('<イベント名>.result', { … })で直接結果を返信する必要があります。(一方、initのonUrlOpenは戻り値が自動的に返信されます。(3-1参照))

購読解除

window.genserDiscovery.off('product.openDetail', handler); // 特定のハンドラーのみ解除
window.genserDiscovery.off('product.openDetail');          // 該当タイプを全て解除

---

4. 環境別の注意事項

4-1. SPA

SPA(ページ遷移時にリロードせず画面の一部だけが切り替わる方式)では、アプリ初回起動時に1回だけスニペットを読み込み、init()を呼び出します。以降のルーティング(ページ遷移)時にinit()を繰り返し呼び出さないでください。

4-2. JSP

JSP(ページ遷移のたびに画面全体がリロードされる方式)はページ遷移のたびに画面全体がリロードされるため、ページテンプレートにスニペットとinit()を一緒に組み込みます。

<script>
  window.genserDiscovery.init({
    vendorId: '<%= vendorId %>',
    environment: 'web',
    onUrlOpen: handleUrlOpen,
  });
</script>

---

5. APIリファレンス

window.genserDiscoveryが提供する主なメソッドです。

メソッド	戻り値	説明
init(config)	Promise	初期化。オプションは2章参照
on(type, handler)	-	イベント購読(3-2参照)
off(type, handler?)	-	イベント購読解除
open()	-	ミニオーバーレイを開く。active状態でのみ動作し、開いている状態で再度呼び出しても動作しません
close()	-	ミニオーバーレイを閉じる。閉じている状態で再度呼び出しても動作しません
toggle()	-	オーバーレイの開閉トグル
changeLanguage(lang)	boolean	iframeを再読み込みせずにアプリの言語を変更。対応するlang値(ko, en, ja)

toggle、changeLanguageなどは、メインスクリプトの読み込みおよびレンダリング完了後に動作します。open()/close()にはパラメーターと戻り値がなく、ウィジェットタイプ(デフォルト/カスタム)にかかわらず使用できます。

---

6. 記述例

コードの記述例を示します。

<script>
  (function (w, d, s, l) {
    w[l] = w[l] || { q: [] };
    if (!w[l].init) {
      w[l].init = function (c) {
        w[l].q.push({ c: c });
      };
    }
    var f = d.getElementsByTagName(s)[0];
    var j = d.createElement(s);
    j.async = true;
    j.setAttribute('data-vendor-id', 'YOUR_VENDOR_ID');
    j.src = 'https://cdn.genser.ai/dist/genser-discovery-loader-jp.min.js';
    f.parentNode.insertBefore(j, f);
  })(window, document, 'script', 'genserDiscovery');

  function handleUrlOpen(payload, context) {
    var url = payload.pcUrl || payload.mobileUrl || payload.fallbackUrl;
    if (!url) {
      return { ok: false, reason: 'url_not_found' };
    }
    window.location.href = url;
    return { ok: true, url: url };
  }

  window.genserDiscovery.init({
    vendorId: 'YOUR_VENDOR_ID',
    environment: 'web',
    onUrlOpen: handleUrlOpen,
    onReady: function () {
      console.log('genser discovery mini ready');
    },
    onError: function (err) {
      console.error('genser discovery mini init failed', err);
    },
  });
</script>

---

7. 注意事項

1. ローダーファイル名はgenser-discovery-loader-jp.min.jsを使用してください。

2. vendorIdは取引先識別値であり、任意に変更するとデータ集計に影響を与える可能性があります。

3. SPA環境ではinit()の重複呼び出しを避けてください。

4. on()購読方式を使用する場合は、必ずcontext.reply(...)で結果を返信してください。

   返信しない場合、応答待ち状態のまま残ることがあります。