カスタムパラメータ

イベントデータをCxenseプラットフォームに送信するにはJavaScriptまたはHTTP APIを使用します。イベントについての追加情報、すなわちイベントそのものが発生した際のそれ以外のイベント情報はカスタムパラメータを使用して表現できます。例えば、「registered」と名付けたカスタムパラメータに「true」という値を付与することで、ページビューイベントが登録済のユーザによって行われたかどうかの情報を追加することができます。

一つのページビューイベントに対して、同じ名前のカスタムパラメータを複数与えることはできません。もし一つのパラメータに複数の値が与えられた場合、最後の値のみが保存されて集計に使用されます。例えば、目的がページビューあたりのクリック数をカウントすることであれば、mouseという名前のパラメータにclickという値を与えるのではなく、mouseClickedという名前のパラメータにクリック数を値として与えることができます。JavaScript APIを使ったユーザプロファイルやリターゲティングのカスタムパラメータの場合、配列を用いてそのパラメータに複数値をセットすることができます。しかしその場合でもCxense Insightはそれを一つのカスタムパラメータとして扱います

パラメータが持てる値の種類は、少ない数のユニークな文字列の組み合わせ、または整数のいずれかに限定されます。
パラメータ値が数値である場合にはその合計が計算されます。

使用可能文字: 現在パラメータ名としてはアルファベットと数字文字のみ使用可能です。
加えて、ダッシュ（-）とアンダースコア(_)も区切り文字として使用可能です。さらに最初の文字に数字を使うことはできません。
サイズ: パラメータ名の最大長は20文字です。パラメータ名が20文字を超える場合は20文字までに切り詰められます。パラメータ値の最大長は256文字です。256文字を超えるパラメータ値を送った場合にはそのパラメータは受け付けられません。setCustomParametersにパラメータ値を渡す際にあらかじめ256文字までに切り詰めておいてください。
COUNT: グループは20個、1グループあたりの値の種類は100個まで集計されてストレージに格納されます。
注：この制限はGUI/APIにて直近31日（またはLTS契約期間）以内）よりも以前のデータを取得しようとした時のみに適用されます。直近31日（またはLTS契約期間）以内の場合、グループ数や各グループ内の値の種類に制限はありません。

JavaScript API

イベントデータをJavascript APIを用いて送信する方法およびその例をこちらでご参照ください。以下の例はその知識を前提としています。

カスタムパラメータは、setCustomParametersコマンドを用いてcX.callQueueにpushすることによってページビューイベントに加えられます。例えばページビューイベントを、登録ユーザによって発生したことを付記してCxenseプラットフォームに通知するには、以下の例のように行うことができます：

cX.callQueue.push(['setCustomParameters', { 'registered': 'true' }]);

すべてのカスタムパラメータをsendPageViewEventコマンドよりも前に追加することを推奨します。
これにより確実に一つのHTTPコネクションですべてのパラメータを送信します。ページビューイベントを送信した後に追加したパラメータは失われてしまいます。ページロードの際にすべてのパラメータデータを有効にする最適な方法は次の通りです。

// サイトIDを設定します
cX.callQueue.push(['setSiteId', '1234']);
 
// カスタムパラメータを設定します
cX.callQueue.push(['setCustomParameters', { 'registered': 'true', 'level': '42' }]);
 
// 全てのカスタムパラメータが追加された後に、ページビューイベントを送信する準備ができました
cX.callQueue.push(['sendPageViewEvent']);

カスタムパラメータをコールキューに追加するJavaScriptのメソッドは複数あり、目的により使い分けます：

メソッド名	説明
`setCustomParameters`	通常のカスタムパラメータをセットします。
`setUserProfileParameters`	そのページを訪れたユーザの興味プロファイル(interest profile)に追加すべきカスタムパラメータをセットします。この仕組みは、ターゲティング広告やレポートを目的として、ユーザを "mark" したり、"tag" することに使われます。この機能は Cxense Conversion Engine と Cxense Advertising に関連して利用される時のみに使われるもので、それ以外のCxense製品での効果はありません。
`setRetargetingParameters`	Cxense Advertisingのリターゲティングマッチングテンプレートで使用するためのカスタムパラメータをセットします。

パラメータ名の先頭に u_ を付与した方法はまだサポートされていますが、将来廃止される可能性があるため推奨しません。Cxense Advertisingで利用したい場合には、代わりにsetUserProfileParametersメソッドを使用してください。

ユーザとリターゲティングパラメータの場合、一つのパラメータに同時に複数値を設定できると便利な場合があります。これは値の配列を使用することで実現できます。配列内の各値は長さの制限があり、配列のエントリー数は最大10までです。10個以上の値が配列にある場合に、使われた10個の値は undefined となります。

// サイトIDを設定します
cX.callQueue.push(['setSiteId', '1234']);
 
//カスタムパラメータの"interests"というグループに、ユーザーのプロファイルとして"books"、"science"、"cars" をセットします。
cX.callQueue.push(['setUserProfileParameters', { 'interests':['books', 'science', 'cars'] }]);
 
// 全てのカスタムパラメータが追加されたので、ページビューイベントを送信する準備ができました。
cX.callQueue.push(['sendPageViewEvent']);

セッションアノテーション

JavaScriptより、セッション内のイベントの自動アノテーションを開始・終了することが出来ます。アノテーションの開始とはそれ以降のすべてのイベントに対して指定したカスタムパラメータが自動的に付与されるということです。
※自動的に付与されるのはブラウザの同一タブ内での遷移に限られます。ユーザが別タブでページを開いた場合には付与されません。

アノテーションを停止すると、イベントへのカスタムパラメータ自動付加が停止します。

セッションアノテーションの使用例には以下のような場合があります：

そのユーザ訪問の元を追跡したい場合。例えばこのセッションはギフトカードのオファーによって開始した、のような場合

訪問者パスを追跡したい場合

// このセッションの以降すべてのイベントにカスタムパラメータ "a: 1" と "b: 'c'" の自動追加を開始：
cX.callQueue.push(['startSessionAnnotation', { a: 1, b: 'c' }]);
cX.callQueue.push(['sendPageViewEvent']);

どの時点でもさらに追加のアノテーションを加えることができます。新しいキーのアノテーションは既存のものにマージされ、同じキーのものは上書きされます：

// "b: 'c' のアノテーションを変更し、"d: 'f'" のアノテーションをこのセッションの以降のイベントに追加：
cX.callQueue.push(['startSessionAnnotation', { b: 'e', d: 'f' }]);
cX.callQueue.push(['sendPageViewEvent']);

さらに、どの時点でもカスタムパラメータのアノテーションを停止することができます：

// "b: 'e'" のアノテーションの停止；キー名”b”と値"e"の両方にマッチ：
cX.callQueue.push(['stopSessionAnnotation', { b: 'e'}]);
cX.callQueue.push(['sendPageViewEvent']);

あるいはすべての値の停止：

// "b"のアノテーションの停止； キー名"b"のマッチのみ：
cX.callQueue.push(['stopSessionAnnotation', { b: null}]);
cX.callQueue.push(['sendPageViewEvent']);

このページビューに対してアノテーションを保持したいが、それを以ってアノテーションを停止する場合、stopSessionAnnotationをsendPageViewEventの次の行に置きます：

// 次のページビューイベント以降で"b"のアノテーションを停止
cX.callQueue.push(['sendPageViewEvent']);
cX.callQueue.push(['stopSessionAnnotation', { b: null}]);

最後に、すべてのアノテーションを停止できます：

// すべてのアノテーションの停止：
cX.callQueue.push(['stopAllSessionAnnotations');
cX.callQueue.push(['sendPageViewEvent']);

URL API

ページビューが特定の参照元から発生した場合だけにカスタムパラメータを付与したい場合もあるでしょう。例えばある外部リンクがクリックされた時にだけカスタムパラメータを付与したい、といったケースです。
一つの方法として、対象のランディングページにJavaScriptを追加し、上記JavaScript APIを用いて、
特定の条件に合致した場合のみカスタムパラメータをセットすることです。これで動作はしますが、カスタムでJavaScriptロジックを追加するのは扱いが容易ではありません。そこで、もっと便利な代替案として、外部リンクに特定のURLパラメータが付いているかどうかによってカスタムパラメータを定義することができます。

cx_で始まるすべてのURLパラメータはカスタムパラメータとして扱われます。
Cxenseスクリプトがページに存在しており、リンクがそのようなURLパラメータを含んでいる場合、
それらはそのリンクのページビューに対するカスタムパラメータとして解釈されます。

http://www.example.com/foo?cx_registered=true&cx_level=42

ハッシュパラメータ、すなわち # 文字の後に続くパラメータもサポートされます。競合する場合にはハッシュパラメータがURLパラメータを上書きします。

HTTP API

このAPIは廃止予定であり、近い将来別のものに置き換わります。
CxenseプラットフォームにHTTPを用いてカスタムパラメータを送信する必要がある場合には、Cxenseサポートにコンタクトしてください。

カスタムパラメータは cp_ で始まるパラメータ名によって追加できます。例えば registered というカスタムパラメータをtrueの値で送信する場合には cp_registered=true とします。現状pgvイベントタイムのみがサポートされており、各リクエストは typ=pgv およびすべての必須パラメータが含まれていなくてはなりません。

GET /Repo/rep.html?ver=1&typ=pgv&sid=1234&ckp=user12345&rnd=0.52254374988082919&loc=http%3A//example.com/app%3Fa%3Db%26c%3D&cp_registered=true&cp_level=42 HTTP/1.0
Host: comcluster.cxense.com
X-Forwarded-For: 173.203.85.136
User-Agent: ExampleBrowser v1.0

Last updated: January 24, 2022