CCEモジュールのレンダリング

CCEモジュールのレンダリング: プレゼンテーションとクリックトラッキング

CCE は Piano Content のテンプレートとスタイルオブジェクトを利用しています。したがって、Cxense Content API に記載の /widget API のプレゼンテーションクラスはCCEにも適用されます。

使用方法

1. 必ずターゲットとなるDIVタグのIDが必要です。そのDIVに直接表示するメッセージがない場合でも、CCEのコードはテンプレート（非表示）をそのDIVに挿入しようとします。

2. DOMにテンプレートオブジェクトが挿入されるので、テンプレートが不正なHTMLでは無いことやテンプレート自身には表示される内容が無いことが重要です。したがって、tmp: ネームスペースを class, id, image の src アトリビュートなどに使用してください。テンプレートが実行されるとすべての tmp: は削除されます。

3. クリックトラッキングのためにイベントリスナーを登録していますので、jqueryのクリックハンドラー等を用いるとトラッキングやレンダリングの動作と干渉してしまいます。クリックを捕捉するには必ず cx クリックトラッカーを使用し、付随して実行する処理がある場合にはコールバックを使用してください。

4. ウィジェットがページに挿入されるまでの一連の流れ:

   1. cX.CCE.run() 呼び出し

      1. 内部的に /public/widget/data が呼ばれる

   2. APIからの応答が返ると、テンプレートがテンプレートDIVに挿入される

      1. カスタムコードが実行される。結果のデータに基づいて実行されるコードは関数として定義し、テンプレートから呼び出すようにする。

   3. テンプレートコードがAPIデータをコンテキスト（通常は items の配列に対してループ処理）として実行され、結果が同じ親DIV内に挿入される

      1. カスタム関数をテンプレート内から実行することが可能ですが、もし生成中のDOMにアクセスする場合には関数を window.requestAnimationFrame でラップしテンプレートが完了してDOMが更新されてから実行するようにします。

   4. 親ページにもCCEウィジェットが挿入された際に実行すべきコードがある場合、cX.CCE.run()の3つ目のパラメータにコールバック関数を指定すれば、すべてのレンダリングとDOMの更新が完了した際にその関数が実行されます。

クリックトラッキング

テンプレートとスタイル で示されているように、clickTracker ヘルパー関数はアンカー要素で使用する必要があります。以下サンプルです。

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item)}}" tmp:href="{{item.url}}" tmp:target="_top">
      <!--%
      cX.renderContainedImage({
        container: { width: 321, height: 160 },
        image: { src: item.dominantthumbnail, dimensions: item.dominantthumbnaildimensions }
      });
      %-->
      <h3>{{item.title}}</h3>
    </a>
  </div>
  <!--%
}
%-->

ターゲットURLにURLパラメータを追加する場合、キーと値の組み合わせをヘルパー関数に渡すことができます。

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  var param = {'key1': 'value1'};
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item, undefined, param)}}" tmp:href="{{item.url}}" tmp:target="_top">
[...]

ユーザがリンクをクリックする際のユーザがリダイレクトされるパラメータは以下のようになります。

https://www.example.com/article/cxense_announces_new_product_offerings.html?key1=value1#cxrecs_s

上のサンプルURLのようなアンカー要素をクリックすると、まずクリックトラッキング用のURLに遷移し、すぐにレコメンド記事にリダイレクトされます。リダイレクトしたくない（が、クリックのトラッキングはしたい）場合、2つめのパラメータでコールバックをもつ、clickTrackerを使用します:

<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
  var item = items[i];
  %-->
  <div class="item">
    <a tmp:id="{{cX.CCE.clickTracker(item, onClick)}}" tmp:href="{{item.url}}" tmp:target="_top">
[...]

次にCCEの "Presentation & display"内のカスタムJavaScript内に以下のコールバック関数を記述します。

function onClick(item) {
  window.location.href = item.url;
}

パーソナライズコンテンツをウェブページへ追加

コンテンツのページへの追加は cX.CCE.run() を呼び出すことにより行われます。このメソッドの呼び出しには少なくともウィジェットIDとターゲットのDIVを指定します。

    cX.CCE.run({
        widgetId: '189f829ad43b558e45cfd2a2ae9e618721f8696a',
        targetElementId : 'cx-frame-target'
});

このメソッドに指定するオブジェクトは cX.insertWidget() のパラメータの多くをサポートしています。同様に2番めのオブジェクトとして追加のcontextを指定することもサポートしています。さらに、前述の通り3番目のパラメータとしてコールバック関数を指定することもできます。

cX.CCE.callQueue.push(['setVisibilityField',"timeSome"]);

コンテンツをiframe内に表示

デフォルトではコンテンツは親ページのDOMに直接挿入されます。iframe内にコンテンツを表示するには、cX.CCE.run() に以下の追加パラメータを指定します：

• renderTemplateUrl: 'auto'

• ウィジェットの初期幅・高さ (width, height) を指定

• resizeToContentSize を true または false に設定

  • false: コンテンツのサイズにかかわらず指定の初期サイズを保持。コンテンツのサイズは変わらず、ページ内の要素が移動することはありませんが、コンテンツが大きい場合は端が切れたり、小さい場合には周囲に空白ができることがあり得ます。

  • true: 表示されるコンテンツのサイズに合わせてiframeをリサイズ。コンテンツが表示されるとページ内の要素が移動するかもしれませんが、ページ内の他の要素に対してフィットします。

例:

    cX.CCE.run({
        widgetId: '189f829ad43b558e45cfd2a2ae9e618721f8696a',
        targetElementId : 'cx-frame-target'

        renderTemplateUrl: 'auto',
        width: 650,
        height: 1000
        resizeToContentSize: false,
    });

Last updated: January 25, 2022