イベントデータ
- 1 JavaScript API
- 1.1 スクリプト配置の代替案
- 1.2 同期・非同期の呼び出し
- 1.3 AJAXウェブアプリケーション
- 1.4 モバイルアプリケーション内からのイベント送信機能
- 1.5 オートリフレッシュチェック機能の無効化
- 1.6 ロケーションURLを上書きする方法
- 1.7 参照元URLを上書きする方法
- 1.8 外部ユーザID
- 2 HTTP API
Event data(例:いつページビューイベントが発生したかについての情報)は、2つの方法でPiano Insightのプラットフォームに送られます。
HTTP API: 送信に必要なパラメータをHTTPリクエストに追加して、統計情報更新のためPiano Insightに送信されます。
JavaScript API: Piano Insightのプラットフォームが、統計が更新された時にブラウザによって自動的に入手します。
JavaScript APIは情報の送信時にHTTP APIを使用します。通常、イベントデータを送信する場合にはJavaScript APIのご利用をお勧めします。
説明をシンプルにするため、以下のセクションでは従来からのページビューイベントについて記載します。カスタムパラメータもサポートしています。
ページビューイベントは、HTTP/HTTPSの標準ポートに対するアクセスのみをサポートしています。
非標準のポート番号を指定したURL(例:http://www.example.com:8000/)に対するPVイベントはサポートしていません。
JavaScript API
新規サイトが登録された際に、Piano Insightによって自動的にウェブサイト設置用のタグが生成されます。
タグの形式は以下のようになります。 サイトグループとサイトIDによりJavaScriptの内容は変化します。
<script type="text/javascript">
var cX = cX || {}; cX.callQueue = cX.callQueue || [];
cX.callQueue.push(['setSiteId', '1234']); // <-- ご自身のサイトIDを入力してください。
cX.callQueue.push(['sendPageViewEvent']);
</script>
<script type="text/javascript">
(function() { try { var scriptEl = document.createElement<script type="text/javascript">
(function(d,s,e,t){e=d.createElement(s);
e.type='text/java'+s;e.async='async';
e.src='https://cdn.cxense.com/cx.js';
t=d.getElementsByTagName(s)[0];t.parentNode.insertBefore(e,t);})(document,'script');
</script> |
前述のJavaScriptタグを配置する場所は、ページ先頭部を推奨しています。なるべく<head>~</head>タグ内に挿入してください。 |
注意点:
ページ内に挿入したJavaScriptタグは、cx.jsというスクリプトのラッパーになります。
cx.jsスクリプトは、クライアントによって非同期にロードされます。このため、ページロード時にクライアントに影響を及ぼしません。cx.jsスクリプトは世界各国のトラフィックの多いウェブサイトで使用され、2010年より継続的に改良を続けています。cx.jsスクリプトは大抵の場合ブラウザキャッシュ から使用されます(すなわちネットワークトラフィックは発生しません)。定期的に更新リクエストが送られますが、多くの場合スクリプトそのものが転送されることはありません(HTML応答コード304 "Not Modified"が返される場合)
これによりネットワークトラフィックやブラウザ(特にモバイル)への影響を最小限にしています。cx.jsスクリプトは、配信遅延を短くするためにコンテンツデリバリーネットワークを利用しています。
cx.jsスクリプトは、匿名ユーザIDの管理をし、どのページをどのユーザが読んだかまで認識するためにcookieをセットします。
prototype.js V1.6 を含むWebページでは cx.js スクリプトが動作しません。
V1.7(またはそれ以降)にアップグレードするか、またはV1.5(またはそれ以前)を使用すると動作します。cx.jsスクリプトはほとんど全てのブラウザをサポートしています:
IE5以上、全てのGoogle Chrome、Safari、Firefoxのバージョン。
また古くからある携帯電話の埋め込みブラウザ(Symbian、Blackberry)、ゲーム端末(Xbox、Playstationなど)、スマートテレビ、Opera Miniのようなインストリームコンバーターなど。
Cxense Advertisingにおいてもcx.jsを利用しています。詳細はこちら をご参照ください。 |
スクリプト配置の代替案
Piano Insightのタグは、出来るだけ<head>~</head>タグ内に設置するようにしてください。もし、<head>タグ内に置く事が出来ない時は、<body>~</body>内に設置しても動作可能です。
<body>~</body>内にタグを配置することはなるべく避けてください。可能な限り<head>セクション内に配置してください。 |
同期・非同期の呼び出し
JavaScript APIの全ての機能は同期もしくは非同期で呼び出すことができます。Piano Insightでは非同期でのリクエストを推奨しています。デフォルトで自動的に生成されたJavaScriptタグは非同期のリクエストを行います。以下2つのリクエストは同じ動作をしますが、タイミング(同期or非同期)が異なります。
var cX = cX || {}; cX.callQueue = cX.callQueue || [];
cX.callQueue.push(['setSiteId', '12345']); |
cX.setSiteId('12345'); |
以下注意点です。
非同期の場合には、cx.jsのロードは実行前か、リクエストがコールキューに追加された後のいずれのタイミングでも構いません。
同期でのリクエストには、実行前にcx.jsがロードされている必要があります。
AJAXウェブアプリケーション
AJAXアプリケーションではコンテンツが動的にロードされます。新しいページがロードされた時、ブラウザは通常のページをロードするシーケンスを実行しません。この方法でロードされたページは、initializePageとsendPageViewEventがそれぞれの論理的なページロードに対して呼び出すことによってJavaScript APIでトラッキングすることができます。AJAXアプリケーションでは、大抵の場合以下の例に見られるようにハッシュ引数によりロードされるコンテンツが読み込まれてセットされるスキームとなっているはずです。
こちら の実際に動いているサンプルも参照ください。 |
<!DOCTYPE html>
<html>
<head>
<title>Sample AJAX application with Piano Insight tracking</title>
<!-- This example uses jQuery, but the method can be used with any AJAX library. -->
<script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
<script type="text/javascript" src="https://cdn.cxense.com/cx.js"></script>
</head>
<body>
<!-- Page links. -->
<div>
<a href="#page=page1.html">Page1</a> |
<a href="#page=page2.html">Page2</a> |
<a href="#page=page3.html">Page3</a>
</div>
<!-- This div holds the page content for the individual pages. -->
<div id="pageContent" style="border: 1px solid black; margin-top: 15px; padding: 5px;">
</div>
<script type="text/javascript">
function loadPage() {
var hashArgs = cX.parseHashArgs();
$.ajax({
url: hashArgs.page,
success: function(pageContent, textStatus, jqXHR) {
document.getElementById('pageContent').innerHTML = pageContent;
// この新しいページのトラッキングを初期化
cX.initializePage();
// この新しいページでページビューイベントを送信:
cX.setSiteId('0'); // <- Replace with correct site id
cX.sendPageViewEvent();
}
});
}
// ハッシュが変更されるたびに新しいページをロード
$(window).on('hashchange', loadPage);
// 最初のページ読み込み
var hashArgs = cX.parseHashArgs();
if (!hashArgs.page) {
location.hash = '#page=page1.html';
} else {
// この場合、onHashChange は起動しないので、 loadPage() を明示的に呼び出す必要があります
loadPage();
}
</script>
</body>
</html> |
コンテンツレコメンデーションのクリックと同時にレポートする必要がある場合、
cX.sendSpaRecsClick(<clickUrl>, [<callback>]);という機能を使うことができます。
<!DOCTYPE html>
<html>
<head lang="en">
<meta charset="UTF-8">
<title></title>
</head>
<script type="text/javascript" src="https://cdn.cxense.com/cx.js"></script>
<body xmlns:tmp="javascript:">
<div id="spaTemplate" class="template">
<div class="headline">
<h2>Single Page Instrumentation Example</h2>
</div>
<!--%
var items = data.response.items;
for (var i = 0; i < items.length; i++) {
var item = items[i];
var clickUrl = item.click_url + '?cx_test=spaTest';
%-->
<div class="item" onclick="openArticlePage('{{item.url}}','{{clickUrl}}');">
<!--%
cX.renderContainedImage({
container: { width: 290, height:172},
image: {
src: item['dominantthumbnail'],
dimensions: 'dominantthumbnaildimensions'
},
tooWideStrategy: 'zoom',
tooTallStrategy: 'zoom',
tooWideFocusPoint: 0.5,
tooTallFocusPoint:0.5,
horizontalAlign: 'center',
verticalAlign: 'center',
scaleFactorMax: 2.0,
scaleFactorMin: 0.8
});
%-->
<h3>{{item.title}}</h3>
</div>
<!--%
}
%-->
</div>
<div id="spaTarget"></div>
<script type="text/javascript">
cX.setSiteId('1234567890');
cX.sendPageViewEvent();
function openArticlePage(loc, clickUrl) {
// 現在のページから離れる前にまずクリックURLをレポートします
cX.sendSpaRecsClick(clickUrl);
// ..
// 新しいページやhistory.pushState(..)などをロードするナビゲーションロジックを実行
// ..
// 通常通り、アナリティクスイベントをレポート
cX.initializePage();
cX.sendPageViewEvent();
}
cX.insertWidget({
widgetId : '70ee1cb56fa19asdasda061ed7fdea6fd',
templateElementId : 'spaTemplate',
targetElementId : 'spaTarget'
} );
</script>
</body>
</html>
|
モバイルアプリケーション内からのイベント送信機能
モバイルアプリケーション内からイベントを送信するにはいくつかの方法がありますが、どの方法を選択するかはモバイルアプリケーション自身がどのように構成されているのかに依存します。4つの主要なアプローチを紹介します:
モバイルウェブアプリケーション、すなわちアプリケーションが、モバイルデバイスの標準ブラウザ内で動作する場合です。モバイルウェブアプリケーションでの実装は、標準のウェブサイトでの実装と同じです。Piano InsightのJavaScriptタグをそのまま使用することが出来、ユーザプロファイルとコンテンツプロファイルは自動的に作成されます。
モバイルウェブアプリケーションに対するネイティブアプリケーションのラッパー、すなわち、アプリケーションはネイティブですが、実際にはアプリケーションに組み込まれたブラウザに被せた薄いラッパーです。上述の通り、全てのPiano InsightのJavaScriptタグはそのまま使用可能で、ユーザプロファイルとコンテンツプロファイルは自動的に作成されます。iPhoneとアンドロイドの両方のアプリケーションラッパーをビルドするシンプルなインテグレーション技術が利用可能です。例:PhoneGap
HTMLのレンダリングを行ったネイティブアプリケーションのラッパー、すなわちアプリケーションはネイティブですが、UIはローカルのリソースから与えられたHTMLを用いてレンダーされています。Piano InsightのJavaScriptタグが使われますが、アプリケーション開発者が考慮する必要のある事項が2点あります:
ネイティブアプリケーションはページのURLを持ちません。したがって、人工的にURLを作成すること、そしてこれらをロケーションオーバーライドメカニズムを使用してPiano Insightに送ることによりアドレスを指定することが必要となります。
Pianoのクローラーは、アプリケーションページのコンテンツにはアクセスできません。このためクローラーはコンテンツプロファイルあるいはユーザプロファイルを作成することができません。したがってコンテンツは別の方法でPiano Insightプラットフォームにフィードする必要があります。例えばウェブサーバー上にアプリケーションのページに相当するコンテンツを配置し、アプリのページに割り当てるURLにそのURLを参照させる、あるいはコンテンツをプッシュする、といった方法です。
ネイティブUIとレンダリングを持ったネイティブアプリケーション、すなわちアプリケーションは完全にネイティブでJavaScriptを実行しない場合です。このアプローチでは、Piano InsightのJavaScriptタグは使うことができませんが、アプリケーションがPiano Insight APIを使用することが可能です。このケースでもコンテンツはPianoからアクセス可能ではないので、ユーザプロファイルとコンテンツプロファイルを生成するためには前述のような方法でコンテンツをフィードする必要があります。様々なモバイルプラットフォームに対するネイティブSDKを利用される際には、Pianoサポートまでご相談ください。
アプリケーション開発者へのお奨めは#1または#2のアプローチです。どちらも実装とメンテナンスが容易です。特に#2のアプローチを推奨します: |
オートリフレッシュチェック機能の無効化
cx.jsは、オートリフレッシュのページではイベントを送信しないようチェック機能を設けています。Ajaxアプリケーションを利用してページをオートリフレッシュしてるページで、イベントを送信したい場合sendPageViewEventに[useAutoRefreshCheck:false]を追加して、このチェック機能を無効化できます。
cX.callQueue.push(['sendPageViewEvent', { useAutoRefreshCheck: false }]); |
cX.sendPageViewEvent( { useAutoRefreshCheck: false } ); |
ロケーションURLを上書きする方法
sendPageViewEventメソッドは実行されたページのURLを送信します。window.location.hrefの値を取得します(ブラウザのアドレスバーの値になります)。もし、そのページではないページのアドレスを送信したい場合にはsendPageViewEventに['location': '任意のURL']を追加することにより上書きすることができます。
cX.callQueue.push(['sendPageViewEvent', { 'location': 'https://www.corp.com/artId123.html' }]); |
cX.sendPageViewEvent({ 'location': 'https://www.corp.com/artId123.html' }); |
指定されたURLは有効なURLでなければいけません。URLが無効な場合には正常にイベントが送信/集計されない場合があります。 |
実際のURLと異なるURLでイベントを送信を行った場合、Piano Insightのレポートはアイテムを正しく解析出来なくなってしまう事がありえます。 |
参照元URLを上書きする方法
sendPageViewEvent は自動的に参照元URLをdocument.referrerの値にセットして送信します。このデフォルトの挙動を上書きする必要がある場合には、referrerパラメータをsendPageViewEventに明示的に追加することによって上書きが可能です。
cX.callQueue.push(['sendPageViewEvent', { 'referrer': 'https://www.corp.com/artId123.html' }]); |
cX.sendPageViewEvent({ 'referrer': 'https://www.corp.com/artId123.html' }); |
指定されたURLは有効なURLでなければいけません。URLが無効な場合には正常にイベントが送信/集計されない場合があります。 |
実際の参照元と同一でない参照元でreferrerパラメータを上書きすると、Insightのレポートが不正確なものとなります。
|
外部ユーザID
上述の通り、cx.jsスクリプトは、匿名ユーザIDを管理し、それぞれのイベントをユーザと紐付けます。
一方でお客様においては固有の方法でユーザに対してIDを付与している場合がありますので、それらをリンクすることができます。ウェブサイトにおいてユーザにログインを求める場合、そのユーザIDをキーにしてInsightのAPIを実行する、あるいはユーザの属性情報をPianoプラットフォームにアップロードしてそのユーザの情報を付加することもできます。さらにはユーザが異なるデバイスからログインした場合でも同一のユーザとして認識して扱うことも可能になります。
JavaScript APIは、どのユーザがイベントを生成したのかについての情報をイベントに付加するためにaddExternalIdメソッドを提供します。指定する外部ユーザIDは、cx.jsが使用しているユーザIDとサーバー側でリンクされます。外部ユーザIDは多くのフォームを取ることができます。典型的な例としては以下の通りです:
アプリケーション固有のログインID(CRMやEコマース、ニュースレターのデータベース等)
広告主向けのApple ID(IFA)
Facebook ID(をハッシュ化した値)
Google ID(をハッシュ化した値)
メールアドレス(をハッシュ化した値)
Pianoのポリシーとして、個人を特定する情報は収集・保持いたしません。したがって、ユーザIDはハッシュ関数で匿名化してください。
Name | Type | Required | Description |
|---|---|---|---|
id | String | Yes | Piano Insight クッキー(Cxense クッキー)と紐付ける外部ユーザID |
type | String | Yes | カスタマプリフィックス |
addExternalIdの使用例は以下の通りです。
cX.callQueue.push(['addExternalId', { 'id': 'subscriber14', 'type': 'xyz'}]); |
cX.addExternalId({ 'id': 'subscriber14', 'type': 'xyz'}); |
|
完全なタグの例は以下の通りです:
<!-- cXense script begin -->
<div id="cX-root" style="display:none"></div>
<script type="text/javascript">
var cX = cX || {}; cX.callQueue = cX.callQueue || [];
cX.callQueue.push(['addExternalId', { 'id': 'subscriber14', 'type': 'xyz'}]); // <-- カスタマプリフィックスを指定してください
cX.callQueue.push(['setSiteId', '1234']); // <-- 正しいサイトIDを入力してください。
cX.callQueue.push(['sendPageViewEvent']);
</script>
<script type="text/javascript">
(function(d,s,e,t){e=d.createElement(s);e.type='text/java'+s;e.async='async';
e.src='https+//cdn.cxense.com/cx.js';
t=d.getElementsByTagName(s)[0];t.parentNode.insertBefore(e,t);})(document,'script');
</script>
<!-- Cxense script end --> |
外部ユーザIDの指定はすべてのページビューのイベントに付与する必要はありません。例えば、ログイン後ユーザがアクセスするページに付与するだけで構いません。外部ユーザIDとcx.jsによって使用される内部のユーザIDとのリンクが少なくとも一度行われるとサーバ側で記憶されます。しかしながらサーバー側のマッピングが消去された場合には、リンクの情報が失われます(例えば、キャパシティの理由で、長い間アクセスがないと見受けられるユーザのマッピングは消去されます)。リンクのオペレーションは少なくとも1ヶ月に一度、出来ればそれ以上の頻度で行ってください(これによりサーバー側がアクティブ・非アクティブのIDを正しく識別することができます)。
HTTP API
このAPIの使用にはPianoの明示的な同意が必要です。ご要望の際には弊社までご連絡ください。 |
cx.jsスクリプトは上述の通り様々なデータを収集し、この情報をエンコードするURLを作成し、Piano Insightのプラットフォームにサーバへの標準のHTTPリクエストを作成することによって送り返します。
このHTTP APIはまた直接クライアントによって呼び出すことができます。このURLでは現在のところ以下のパラメータをエンコードしています:
パラメーター | 必須 | サンプル値 | 内容 |
|---|---|---|---|
| Yes | 1 | どのバージョンのAPIにターゲットリクエストしているのかを示すパラメーター。 |
| Yes | pgv | どのタイプのイベントなのかを示すパラメーター。値:pgvはページビューイベントを意味します。 |
| No | 0 | Piano InsightのアカウントID |
| Yes | 1234567890123 | Piano InsightのサイトID |
| Yes | ページのURL。構文的に正しいURLでないといけません。そうでない場合、イベントは破棄されます。 | |
| No | 参照しているページのURL | |
| No | Piano InsightのゴールID。将来的にファネル機能のために使用する予定です。 | |
| No | ページ名 | |
| No | 1473837694457 | クライアントの現地時間 |
| No | -120 | クライアントのタイムゾーン |
| No | 1920x1080 | 解像度。フォーマットは "res=<width>x<height>" です。例:"res=1024x768" |
| No | 1395x282 | ブラウザのウィンドウサイズの初期値。フォーマットは "wsz=<width>x<height>" です。例:"wsz=544x365" |
| No | 24 | デバイスの色の濃度。通常はブラウザの window.screen.colorDepth から読み込みます。 |
| No | 1 | デバイスのピクセルの割合(物理ピクセルと仮想ピクセルとの割合)。通常ブラウザの window.devicePixelRatio から読み込みます。 |
| Yes | it2kwr95mv0uxmh3 | キャッシュ無効化の目的とページビューリクエストを一意的に識別するための乱数。 |
| No | 0 | Javaが利用可能かどうかを示すパラメーター。 |
| No | en-US | クライアントのブラウザの言語 |
| No | it2kw3ldnxjc | Piano Insightのサイト固有のセッションcookie。最低16文字以上です。使用可能な文字列: A-Z, a-z, 0-9, "_", "-", "+", "." |
| Yes | if1211191dpr | Piano Insightのサイト固有の永続的なクッキー。ユーザを識別するための乱数を含みます。長さは16〜40文字です。使用可能な文字列: A-Z, a-z, 0-9, "_", "-", "+", "." |
| No | cx:pbad80kwtao0l1qyfh5vv7q7:2vaqowu49edjp | 他のID(ckp など)に関連してユーザを一意に識別するグローバルID |
| No | UTF-8 | ドキュメントの文字セット |
| No | 1 | Flashが利用可能かどうかを示すパラメーター。 |
| No | Shockwave Flash 22.0 r0 | フラッシュのバージョン |
| No | 0 | その端末のユーザーがサイト上で新規であることを示します。cX.getUserId()によってIDが作成され、ブラウザのストレージに保存されたことを示します。ピクセルリクエストでこのフィールドを使用する際には土曜の意味合いにされることを推奨します。新しいIDが作成され、それが保存される場合、このフィールドは1になります。したがって "new=1" は新しいユーザを意味します。値:0あるいは1。 |
cp_<name> | No | 追加したいカスタムパラメータとして、"cp_" という接頭辞と同時に name と value をURLパラメータに追加することによって、カスタムパラメータを "name=value" で設定します。例えば "premiumPage: true" を設定したいなら、 URLパラメータに "cp_premiumPage=true" を追加します。カスタムパラメータの設定に関する詳細はこちらのsetCustomParametersをご確認ください。 パラメータ名には貴社のカスタマープリフィックスの利用を推奨します。例えばカスタマープリフィックスが "xyz" の場合は URLパラメータに "cp_xyz-premiumPage=true" を追加します。 | |
cp_u_<name> | No | 追加したいユーザプロファイルパラメータとして、"cp_u_" という接頭辞と同時に name と value をURLパラメータに追加することによって、ユーザプロファイルパラメータを "name=value"で設定します。 | |
| No | 外部ユーザーIDをPianoユーザーに紐づけるために使用される、1つ目の外部ユーザーIDの値。最大64文字まで可能です。 | |
| No |
| 外部ユーザーIDをPianoユーザーに紐づけるために使用される、1つ目の外部ユーザーのIDのtypeの値。最大10文字まで可能です。 |
| No |
| 2つ目のオプションの外部ユーザIDの値。 |
| No |
| 2つ目のオプションの外部ユーザIDのタイプ。 |
| No |
| その場所の時間 |
| No |
| その場所の地域 |
| No |
| その場所の経度 |
amo | No | 1473634205 (for | そのWebページが 'article:modified_time' プロパティでメタタグを持っていたら、そのコンテンツが解析されて、秒に変換されます。 |
con | No* | y, pv, segment | カンマ区切りで以下のような値を保持します y - 必須。このイベントが取得された場合にセットされ、ユーザの同意がある時のみ処理されます。 pv - ユーザの興味関心事項とプロファイルを理解するためにページビュー、DMPイベント、ブラウジングの傾向を収集します。 recs - コンテンツレコメンドのパーソナライズし、ユーザの興味関心とブラウジングの傾向を基にコンテンツを提案します。 segment - オーディエンスのセグメント、特定のオーディエンスセグメントにユーザを含めるためにブラウジングの傾向と 1st パーティデータを処理します。 ad - 広告のターゲティングはブラウジングの傾向とオーディエンスセグメントを基にしています。 device - 端末データを記録し、プロファイリングに使用します geo - IPアドレスによるジオロケーションの検索が可能で、ページビューからジオロケーションパラメーター(plat、plon)を受け付けることができます。 |
| No* | 2 | "device" と "geo" フラグを尊重しています。cv は "consent version" を意味し、"2" を指定すると、バージョン2を使用します。 |
altm | No |
| 前のページのスクリプト開始時間 (After-the-fact reporting) |
arnd | No |
| 前のページのページビューID(rnd) (After-the-fact reporting) |
aatm | No |
| ユーザがページ上でアクティブだった時間 (After-the-fact reporting) |
axtl | No |
| 前のページで使用した exit リンク (After-the-fact reporting) |
awsz | No |
| 前のページを表示している時のウィンドウサイズ (After-the-fact reporting) |
amvw | No |
| 前のページを表示している時の最大ビューポートスペース (After-the-fact reporting) |
ascp | No |
| 前のページのスクロールの深さ(ピクセル単位) (After-the-fact reporting) |