1st/3rdパーティデータのアップロードチュートリアル

Piano DMP に 1st/3rd パーティデータをアップロードする

概要

ファースト及びサードパーティデータのアップロードを行うということはCxenseによって各ユーザーについてすでに収集されたデータに対して追加のユーザーデータを付加したいというご要望に基づきます。これは後に、ユーザーのグループをターゲットするのに使われるDMPのユーザーオーディエンスセグメントを作成できるようにするためです。主な用途の1つとしてあるのは広告のターゲティングです。

ファーストパーティデータは申込や会員特典を受ける登録プロセスの間にユーザー自身が入力したデータから主に派生したものです。この種の典型的なデータは年齢と性別です。サードパーティデータは通常、ソーシャルネットワークから（例えば、LinkedIn からそのユーザの専門性、Facebookの性的嗜好（"恋愛対象"））あるいはユーザーの年齢/性別/収入レベルなどを導き出して、ユーザーデータを取得することに特化したベンターから派生したものになります。

アップロードしたユーザーデータを役立てるためには、Piano Insight で計測しているユニークなユーザーIDと他のデータを紐づける必要があります。他のデータを生成するシステムでもユーザーを個別識別するためのIDを持っていますので、これら2つのIDを連携させなければなりません。この連携ができることによって、ユーザーに対してアップロードしたデータを適切に関連づけることができます。

お客様のケースに依存しますが、データのアップロードは一度のみ行うこともあれば、更新頻度の高いデータをお使いの場合は頻度を高く、最も多い例では24時間に一度実施することもあります。別の方法としてユーザーがページにアクセスやログインしている時点で都度それを行う方法もあります。以下ではまずID同期のステップを見た後に、その両方のアプローチを見ていきます。

定義

簡単に言えば、具体的に何も指定されていない場合1st パーティデータまたはユーザデータという言葉は、
1st パーティと3rd パーティの両方のユーザーデータのことを言います。IDを同期して、ユーザーデータをアップロードする方法は1st パーティでも3rd パーティでも同じです。

このチュートリアルでは「外部ID」という言葉と 「externalId」 という変数名が頻繁に使われます。この用語はPiano Insightのお客様が内部の顧客データベース（CRMシステム）で使われているID（会員IDなど）を指します。同じユーザーを識別するためにPiano Insightで使われるユニークIDは Cxense ID を呼ばれます。

前提 

アップロードをするためには以下へのアクセスが必要です。

• サイトID

• サイトが属するサイトグループへの更新権限を持つユーザー

• APIキー

• サイトグループのカスタマープリフィックス

IDの同期

IDの同期とは、お客様が持っているユニークIDとPiano InsightのブラウザをベースとしたユニークユーザーIDとを連携して同じユーザーと見なすための操作を指します。お客様が持っているユニークIDは通常CRMデータベースのユーザーテーブルなどで会員IDとして使われています。以下で同期方法を紹介していきます。

クライアントサイドのID同期

以下の図ではステップの1から3がIDの同期操作を示しています。ステップ4は次のセクションで説明する最終目的のための、ユーザーデータをアップロードする操作です。

上のステップ1は以下の拡張 Piano Insight トラッキングスクリプト の9行目に対応しています（拡張箇所は4〜8行目）。つまり、ピクセルリクエストがそのユーザーについて収集された情報とそのページへのアクセス情報を送信します。その情報に含まれるものが Piano Insight のユニークユーザIDです。ステップ2ではユーザーがサイトにログインし、このユーザの会員IDが確認可能な状態となります。上の図のステップ3が下記の5行目に対応しています。この時点から2つのIDが永久に結び付けられるようになり、それを南京錠の絵で表現しています。

<script>
	var cX = cX || {}; cX.callQueue = cX.callQueue || [];
	cX.callQueue.push(['setSiteId', 'サイトIDを代入']);
	cX.callQueue.push(['invoke', function() {
		if (typeof externalId !== "undefined") {
			cX.addExternalId({'id': '外部IDを代入', 'type': 'カスタマープリフィックスを代入'});
    	}
    }]);
	cX.callQueue.push(['sendPageViewEvent']);
</script>

外部IDの取得

現在ページに訪問しているユーザーに対して会員IDを取得するには主に3つのどれかになります。

• 何らかの理由で(あるいは他の名称で)既にグローバル変数として存在している

• Cookieに格納されている

• URLパラメータとして付与されている

Cookieから外部IDを取得する

最初のケースは単純です。上のコードをそのまま使うことができます。2番目にCookieが格納されたケースでは、以下の5行目で示されているように上のコードに1行コードを追加します。

<script>
	var cX = cX || {}; cX.callQueue = cX.callQueue || [];
	cX.callQueue.push(['setSiteId', 'サイトIDを代入']);
	cX.callQueue.push(['invoke', function() {
        var externalId = cX.getCookie("IDに相当するCookie名を代入");
		if (typeof externalId !== "undefined") {
			cX.addExternalId({'id': '外部IDを代入', 'type': 'カスタマープリフィックスを代入'});
    	}
    }]);
	cX.callQueue.push(['sendPageViewEvent']);
</script>

URLパラメータから外部IDを取得する

ユーザーIDを同期する方法として、以下の図で示されているように、メールのニュースレター内にあるランディングページのリンクをクリックさせることです。

ステップ1ではお客様は送信するためのニュースレターのコンテンツとそれをユーザーに送るためのEメールアドレスとその全てのユーザーに対応したIDをニュースレター配信に提供しています。次のステップでは登録された全てのユーザーに対してEメールを通じてニュースレターを配信しています。Eメール内にはランディングページへのリンクが含まれています。そのリンクはお客様のシステム内のユーザーID（例： nlid=1234) を保持したURLパラメータで拡張されています。上のPiano Insight スクリプトの5行目でニュースレターのリンクから外部ID(会員ID)を取得するために以下のように変更します。ステップ3では Piano Insightと会員IDが紐づいた状態でページビューイベントが発生しています。

		var externalId = cX.parseUrlArgs().nlid;

ページビューイベントを遅らせる

ページにアクセスしてすぐの状態では、処理タイミングの関係で外部ID(会員ID)が取得できないことがあります。これはページ訪問が開始された後の数百ミリ秒に行われますが、これを任意の時間に変えているケースもサイトによってはあります。このような場合に通常の形式でページビューイベントを発火すると、外部IDがまだ存在しておらず、Piano Insight に送られるデータの一部になりません。以下のように外部IDが有効になっている時に呼び出される関数にページビューイベントをラップすることによってこれを解決することができます。

<script>
	function sendLatePageViewEvent(externalId) {
        window.cX = window.cX || {}; cX.callQueue = cX.callQueue || [];
        cX.callQueue.push(['invoke', function() {
            cX.setSiteId('サイトIDを指定');
            cX.addExternalId({'id': externalId, 'type': 'カスタマープリフィックスを指定'});
            cX.sendPageViewEvent();
        }]);
    }
</script>
 
<script>
	// この行は外部IDが有効になった、少し後で呼び出されます
	sendLatePageViewEvent(externalId)
<script>

このアプローチによるリスクはもちろん、その呼び出しが遅すぎてページがユーザーに閉じられてしまい離脱する前にページビューイベントの発火ができない可能性があるということです。
これが起こると、ユーザーIDの同期に失敗するだけでなく、ページビューのレポートも取得できないことになります。

ページビューから独立したID同期

これまでの例ではデータをアップロードすることによって外部IDを追加することでページビューイベントをピギーバックしました。これは cX.addExternalId() 関数が全ての動作を行い、Persistedクエリを使ったり、JSONP機能を適用する必要がないので、IDを実装するのには最も簡単な方法です。しかし、このアプローチが常に可能であるとは限りません。特にサードパーティデータのベンダーの場合、ユーザーIDを同期するのとページビューを独立した方法にすることが理に適っています。これによって、お客様とベンダー側のコードとが動作するかどうかの調整をする必要がなくなります。以下はページビューとは独立したID同期の例です。

cX.callQueue.push(['invoke',function() {
   var persistedQueryId = "Persisted クエリID　を指定";
   var apiUrl = 'https://api.cxense.com/profile/user/external/link/update?callback={{callback}}'
                + '&persisted=' + encodeURIComponent(persistedQueryId)
                + '&json=' + encodeURIComponent(cX.JSON.stringify({ id: externalId, cxid: cX.getUserId() }));
   cX.jsonpRequest(apiUrl, function (data) {
        // Uncomment for debugging:
        //alert(cX.JSON.stringify(data))
   });
}]);

このアプローチではPersisted クエリIDが必要となり、Piano Insightから取得するか(過去に別の用途で取得したものを再利用しても動作しません）、 Persistedクエリ チュートリアルでご紹介しているようにご自身で作成していただきます。Persistedクエリを作成するのに必要な関数については /profile/user/external/link/update で説明しています。

サーバーサイドのID同期

クライアントサイドでユーザーの会員IDを知ることができない場合、すなわち 上のユーザーIDのようにコード内で変数の外部IDを付与できない場合、代わりに以下の図で示されているような方法をとることができます。

Piano Insight のトラッキングスクリプトでレポートされるデータに対して、顧客ID(変数 外部ID）を取得する代わりに、Piano Insight のユーザーIDを（上の図のステップ2で描かれている）お客様のバックエンドに渡されます。バックエンドは"cX_P"という名称のCookieの値として、ページのHTTPヘッダーからPiano Insight ユーザーIDを取得します（これは cx.js ライブラリ関数の cX.getUserId() によって返されるものと同じIDです）。

サーバーサイドはユーザーのCxense IDを保持したらすぐに、お客様は単一ユーザーを同期させる以下のような Python 3.x のサンプルスクリプトで示されているような機能を実行できます。以下のスクリプトは上の図のステップ3に対応しています。26行目で2つのIDがどのように結びつくかを確認できます。

_username   = "<Piano Insight のログインユーザーID>"
_secret     = "<Piano Insight のログインユーザーIDに紐づくAPIキー>"
_prefix     = "<カスタマープリフィックス>"
_cxUserId   = "<ユーザーのCxense ID>"
_externalId = "<お客様のシステムにおけるユーザーID>"
  
import json, datetime, hmac, hashlib, http.client
     
def cxApi(path, obj):
    date = datetime.datetime.utcnow().isoformat() + "Z"
    signature = hmac.new(_secret.encode('utf-8'), date.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
    headers = {"X-cXense-Authentication": "username=%s date=%s hmac-sha256-hex=%s" % (_username, date, signature)}
    connection = http.client.HTTPSConnection("api.cxense.com", 443)
    connection.request("POST", path, json.dumps(obj), headers)
    response = connection.getresponse()
    status = response.status
    responseObj = json.loads(response.read().decode('utf-8'))
    connection.close()
    return status, responseObj
   
def errorHandling(status, response, message):
    if status != 200:
        raise Exception("%s (http status = %s, error details: '%s')" % (message, status, response['error']))
  
def syncUserIds(cxUserId, externalId, prefix):
    status, response = cxApi('/profile/user/external/link/update', {"cxid":cxUserId, "id":externalId, "type":prefix})
    errorHandling(status, response, "Failed to sync user")
    return response
 
syncUserIds(_cxUserId, _externalId, _prefix) 

上のスクリプトは単なるサンプルです。Piano Insight APIを使ってスクリプトを書くためには、Piano Insight API チュートリアル をご確認ください。その時点でスクリプトを実行するのは非常に非効率的なので、特にバッチモードのセクションを確認してください。

上のスクリプトで実装されているものと同じ機能が cx.pyツール を使って以下のコマンドラインで実行できます。

cx.py /profile/user/external/link/update '{"cxid":"Cxense Cookie ID", "id":"外部ID", "type":"カスタマープリフィックス"}' 

データアップロード

上ではファーストまたはサードパーティユーザーデータを正常にアップロードするために必要となる2つのステップの1つを行いました。2つのシステム間（一方はPiano Insight、もう一方はお客様のCRMシステムまたはサードパーティベンダーのデータベース）でIDの同期が行われました。「２つのステップの最初」ではなく、「2つのステップのうちの1つ」がという言葉のチョイスに気がつきましたか？これは2つの操作を任意の順序で実行できるためです。

データをアップロードするための最も一般的な方法はまずCSVファイルとしてユーザーテーブルをCRMシステム/データベースから出力することです。そのファイルはアップロードを行うスクリプトの入力として使用されます。もちろんスクリプトはデータベースから直接データを読み込むこともできます。CSVでのアプローチがどれだけ一般的で汎用的であるかを考えるにあたり、以下ではCSVファイルの内容を読み込んでPiano DMPにアップロードする Pythonスクリプト を実装しています。アップロードするサンプルデータは以下のようなものです。

id,gender,age
1234,male,22
5678,female,39

データをアップロードするスクリプトはこちらです。

_username     = '<Piano Insight のログインユーザID>'
_secret       = '<Piano Insight のログインユーザIDに紐づくAPIキー>'
_prefix       = '<カスタマープリフィックス>'
_dataFile     = '<CSVデータのファイルパス>'
_delimiter    = '<データファイルの区切り文字>'
  
import json, datetime, hmac, hashlib, http.client
   
def cxApi(path, obj):
    date = datetime.datetime.utcnow().isoformat() + "Z"
    signature = hmac.new(_secret.encode('utf-8'), date.encode('utf-8'), digestmod=hashlib.sha256).hexdigest()
    headers = {"X-cXense-Authentication": "username=%s date=%s hmac-sha256-hex=%s" % (_username, date, signature)}
    connection = http.client.HTTPSConnection("api.cxense.com", 443)
    connection.request("POST", path, json.dumps(obj), headers)
    response = connection.getresponse()
    status = response.status
    responseObj = json.loads(response.read().decode('utf-8'))
    connection.close()
    return status, responseObj
  
def errorHandling(status, response, message):
    if status != 200:
        raise Exception("%s (http status = %s, error details: '%s')" % (message, status, response['error']))
         
def uploadDataAboutSingleUser(id, type, profile):
    status, response = cxApi('/profile/user/external/update', {"id":id, "type":type, "profile":profile})
    errorHandling(status, response, 'Unable to upload external user data')
    return response

def uploadAllUsersData(dataRows, columnNames):
    for userData in dataRows:
        profile = []
        for i in range(len(columnNames)):
            if columnNames[i] == 'id':
                userId = userData[i]
            else:
                profile.append({"group":_prefix + '-' + columnNames[i], "item":userData[i]})
        print(uploadDataAboutSingleUser(userId, _prefix, profile))

dataRows = [line.strip().split(_delimiter) for line in open(_dataFile, 'rb').read().decode('utf-8').split('\n') if len(line) > 0]
uploadAllUsersData(dataRows[1:], dataRows[0])

上のスクリプトはデータのアップロードの記述法の（完全に動作する）例です。しかしながら、簡単にするために、エラーハンドリングをせず、ユーザーを一人ずつアップロードする（非常に非効率）といったいくつかの前提（'ID'カラムと仮定）があります。Piano Insight APIを使ってスクリプトを書くには Piano Insight API チュートリアル をご確認ください。

データフォーマット

上のサンプルデータはとても単純なものでした。以下では様々なエンティティで使用できる文字を見ていきます。

• データをアップロードする時にカラム名を処理するために保持しているプレフィックスとダッシュを含めてカウントすると、

_{最大長が26ではなく30になります。 例: "xyz-gender"}

事前予約されたキーと値の組み合わせ

上のデータフォーマットにしたがう限り、2つの例外を除いていくつかのキーと値の組み合わせをアップロードできます。Cxenseは特定の値のセットのみが許された、2つの予約済みキー名を持っています。

上にあるリストは Piano Insight 機能に組み込まれてサポートされているため、性別と生まれ年については独自のキーと値の組み合わせではなく、これらを使うようにしなければなりません。

値の組み合わせに対するキーのリスト

上の例ではこちらで示されているように各々のキーに対して1つの値のみが扱われています。

profile = [{"group":"xyz-age", "item":"22"},{"group":"xyz-gender", "item":"male"}]

しかし、以下の例で示されているようにキーが幾つかの値を持つこともでき、次の例では同じユーザーが英語とスペイン語の両方がわかることを示す値をlanguageのキーに保持しています。

profile = [{"group":"xyz-age", "item":"22"},{"group":"xyz-gender", "item":"male"},{"group":"xyz-language", "item":"english"}, {"group":"xyz-language", "item":"spanish"}]

したがって同じキーに多くの値を追加しても問題ありません。それらはお互いを上書きしません。

プロファイルアイテムの最大数

プロファイルごとに40個を超えてオブジェクト/アイテムをアップロードすることはできません。アイテムごとにキーを指すのではなく、一意のキーと値の組み合わせを指しています。したがって、上の例で  xyz-language が2回現れている例では合計のアイテム数が4つでした（'xyz-age' が1回、'xyz-gender' が1回、'xyz-language' が2回）。しかし、40アイテムの上限を超えて、100アイテムまで可能になりました。但し、アカウントマネージャーに連絡を取って、prefix100 という機能をリクエストしてください。

複合的なアプローチ

これまで2つを別々の操作としてIDを同期すること、データをアップロードすることを行なってきました。
24時間またはスケジュールが決まった時点で一度に完全に独立したデータのアップロードを行なって、（もしログインされたなら）ユーザーがページに訪問する度にIDの同期を行います。しかし、2つを同時に行うことは可能です。以下のサンプルコードはページビューデータを送る際に同じコードブロック内でユーザーの性別と年齢をアップロードしています。

<script>
	var prefix = "カスタマープリフィックス";
    var profile = {上の Python サンプル例と同じ};
    var persistedQueryId = "PERSISTED クエリ ID";
	var throttleCookie        = "アップロードを管理するCookie名";
	var minTimeBetweenUpdates = 更新頻度の分数;

	var cX = cX || {}; cX.callQueue = cX.callQueue || [];
	cX.callQueue.push(['setSiteId', 'サイトID']);
	cX.callQueue.push(['invoke', function() {
		if (typeof externalId !== "undefined") {
			cX.addExternalId({'id': '外部ID', 'type': 'プリフィックス'});
    	}
    }]);
	cX.callQueue.push(['sendPageViewEvent']);
 
	cX.callQueue.push(['invoke', function() {
		if (!cX.getCookie(throttleCookie)) {
    		var apiUrl = 'https://api.cxense.com/profile/user/external/update?callback={{callback}}'
            		+ '&persisted=' + encodeURIComponent(persistedQueryId)
            		+ '&json=' + encodeURIComponent(cX.JSON.stringify({{"id":externalId, "type":prefix, "profile":profile});
    		cX.jsonpRequest(apiUrl, function(data) {
        		// Uncomment for debugging:
        		//alert(cX.JSON.stringify(data))
    		});
			cX.setCookie(throttleCookie, "throttle", minTimeBetweenUpdates / (24 * 60))
		}
	}])
</script>

throttle Cookieは Piano Insight サーバがユーザーデータのアップロードで過負荷になるのを避けるために使用します。例えば年齢や性別のようなユーザーデータは頻繁に変更されないため、変更の多いデータをアップロードしない限り、それぞれのアップロードごとで数時間、数日、数週間も経過することがあります。Piano Insightサーバーが特定のサイトから大量のトラフィックを受け取ると、保護プログラムが作動してブラックリストに登録されてしまいます。したがって、過負荷を避ける考慮をいただくことが非常に重要となります。

上のコードはユーザーデータにアクセスし、上のPythonプログラムのように同じユーザープロファイル変数を構築できると仮定しています（外部IDは1234だったとして）。

{'type': 'xyz', 'id': '1234', 'profile': [{'item': 'male', 'group': 'xyz-gender'}, {'item': '22', 'group': 'xyz-age'}]}

このコードはAPI機能の /profile/user/external/link/updateでPersistedクエリを作成する必要もあります。

検証とトラブルシューティング

全てが動作しているかをどう検証しますか？もし動作していないならその原因をどこから探し始めますか？以下の3点を確認していきましょう。

• 最終目的が達成されたか？

• IDの同期は行われたか？

• データアップロードは行われたか？

最初にチェックすることはデータをアップロードするという最終目的が達成されたかどうか、です。もしそうならトラブルシューティングは必要ありません。しかしそうでない場合、IDの同期またはデータのアップロードが失敗したかどうかを調べる必要があります。

最終目的は達成されたか？

ほとんどの場合アップロードされたユーザーデータの最終的な目的は、顧客を様々なユーザー特性（性別、年齢、職業など）でフィルタリングできるような、詳細なDMPのオーディエンスセグメントを有効にすることです。以下ではこのチュートリアルの最初の方でアップロードされたデータの確認方法とアップロードが成功したかを見ていきます。以下のようにアップロードされたデータをDMPのセグメント作成ウィザードのドロップダウンで再検索をするだけです。

ファーストまたはサードパーティデータを正常にアップロードする前には、「1stパーティデータ」オプションは左端にあるドロップダウンのリストの選択肢に表れません（3rdパーティデータも 「1stパーティデータ」のドロップダウン内にあります）。さらに、年齢データが正常にアップロードされる前には、二番目のドロップダウン内で選択する 「<カスタマープリフィックス>-age」という値がありません。特定の年齢として22や39といった値が正常にアップロードされる前には右側にドロップダウンのリストは現れません。 

つまりここにデータが現れなければ、データは正常にアップロードされたかがまだわかりません。これはデータが最初にアップロードされてからセグメント作成のドロップダウンのボックスに現れ始めるまでに時間がかかるためです。

IDの同期は行われたか？

DMPのセグメントが作成できなかったら、何に失敗したかを調査しなければなりません。IDの同期が失敗した可能性はあるでしょうか？

もしIDの同期が成功していれば、顧客の外部IDを使用してPiano Insightに収集されたユーザーデータと同じように、以下で示されているようなお客様にアップロードされたデータを取得できるはずです。これはもちろんこのテストで使用しているユーザーIDは実際にサイトに訪問したユーザーとで最終的には同期されることを前提としています（例えば、同期がログインページのみで発生する場合、以下のコマンドを実行する前にユーザーはしばらくの間ログインされていなければなりません）。

$ python cx.py /profile/user '{"type":"xyz", "id":"1234"}'
{
  "id": "1234",
  "type": "xyz",
  "profile": [
    {
      "item": "25",
      "groups": [
        {
          "group": "xyz-age",
          "weight": 2.0,
          "count": 1
        }
      ]
    },
    {
      "item": "male",
      "groups": [
        {
          "group": "xyz-gender",
          "weight": 2.0,
          "count": 1
        }
      ]
    },
    {
      "item": "wiki.cxense.com",
      "groups": [
        {
          "group": "cxe-site",
          "weight": 1.0,
          "count": 1
        }
      ]
    },
    {
      "item": "windows",
      "groups": [
        {
          "group": "device-os",
          "weight": 1.0,
          "count": 1
        }
      ]
    }
  ]
}

上のコマンドの出力では、データのアップロード（年齢(age)と性別(gender)）とPiano Insightのデータ収集（ユーザーが訪問したサイトのURLやユーザーのOS情報）が組み合わせられていることを確認できます。

もし上のコマンドが期待した出力を返さなかったら、Webページ内でエラーを探し始めなければなりません。この場合、追加された外部IDを含むページビューに関する全ての情報はPiano Insight に送られるピクセルリクエスト 内でURLクエリパラメータとして渡されます。したがって、ブラウザのデバッガー（デベロッパーツール等）でピクセルリクエストを探すことによって、外部IDが実際に送られているかどうかを確認できます。外部IDパラメーターの名前は eid0 で、ピクセルリクエストのパラメータ概要 としてリストされています。加えて、外部IDにはカスタマープリフィクスがパラメータ名 eit0 として送られます。このケースでは Google Chrome のデバッガーを使って、データが実際に送信している内容をどのように確認するか、以下の図で示しています。

データのアップロードは行われたか？

データが Piano Insightの画面上に表示されない場合に考えられるもう一つの問題は、データのアップロードそのものです。Piano Insight のデータを使って、アップロードしたデータから適当なIDを取得し確認してみましょう。以下ではPiano Insight の cx.pyツール を使って確認していきます。

$ python cx.py /profile/user/external/read '{"type":"xyz", "id":"1234"}'
{
  "data": [
    {
      "id": "1234",
      "type": "xyz",
      "profile": [
        {
          "group": "xyz-gender",
          "item": "male"
        },
        {
          "group": "xyz-age",
          "item": "22"
        }
      ]
    }
  ]
}

ユーザーIDを削除した後に同じコマンドを実行すると、ユーザーの全てのリストが表示されます。データ量があるため、出力は以下のようにリダイレクトした方が良いでしょう。

python cx.py /profile/user/external/read '{"type":"xyz"}' > users.json

Piano Insight内にデータがなければ、アップロードのプログラムに戻り、そこで何が間違っていたかを確認します。上のアップロードスクリプトでは何か失敗した時にエラーを出しており、そのエラーメッセージは問題の原因に関する情報を与えてくれます。 

データの品質と有用性

ほとんどの場合、アップロードされたユーザーデータの目的は、Piano DMPの粒度を高めることです。以前は「ロンドンのユーザー群」というセグメントを作成できましたが、適切なユーザーデータがアップロードされると、「エンジニアまたは医師であるロンドン出身の40歳より上の女性」というセグメントを作ることができるようになります。

しかし、データを持っているからといって、それがアップロードに適しているとは限らないということを心に留めておくことが重要です。以下では映画のタイトル「The Good, the Bad and the Ugly（邦題：続・夕陽のガンマン）」から着想を得て、候補となるデータがどうであるかをグループ分けしていきます。

The Good（良い）

以下のテーブルは意味のあるユーザーセグメントを作成する目的に適していそうな良いデータが示されています。

The Bad（悪い）

次のカテゴリーは悪いデータが以下の左の行のに示しており、最小限の努力で（プログラムで）右の行に示されるような良いデータに変換することができます。

データをオーディエンスセグメントを作成する人にとって有用なものにするには、データを限られた数のカテゴリに分類しなければなりません。上の例ではデータを変換または抽出をして、限られた数の選択肢に分類しました。

...and the Ugly(醜い)

最後のカテゴリではオーディエンスセグメントデータとしては役に立たないデータが格納されています。
なぜなら単一ユーザーのオーディエンスセグメントしか作成できないからです。

_{*このスペル間違いは悪いデータの例として、わざと行なっています}

最初の interests は自由入力（誰もこの価値を感じません）とスペル間違い（正しく書くのであれば "horse riding"(乗馬)）を含んでいます。次の3つ（mobile、email、credit card）はIDタイプのデータであり、実際に一人の人だけを対象とし、個人情報をこのように扱ってしまうこと自体が法律違反です。最後のユーザーの名前はおそらく一人以上の人をカバーしているものですが、有効な利用方法はあるでしょうか？
Chris という名前のコーヒーマグを販売するターゲット広告に使えますか？

Having Cxense do the Data Uploading

From the above description it should be clear that it is a very feasible thing for a customer to take care of their own 1st party data uploading and this is also what Cxense normally expects. However, if a customer for whatever reason is unable to implement their own data uploading, then they can pay Cxense to take care of it for them. Cxense has a configurable tool called MAD (acronym for Moves Any Data) that is used to upload or download various kind of data to and from Cxense and this is not limited to just user data, but applies to traffic data, user segments and even searchable documents (thus the name). The way MAD operates is that the customer uploads a csv (comma separated values) file with the user data to a FTP,  SFTP or Amazon S3 and then provide Cxense with the information required for having MAD download the data on a regular basis (normally once every 24 hours).

Data Source and Schedule

Below we see the part of the MAD configuration that relates to form where MAD is to download the data and according to what schedule. This is information the customer has to provide to Cxense. 

# Ftp/sftp
ftpServer           = '<FTP/SFTP IP OR FQDN>'
ftpDir              = '<FTP/SFTP DIR PATH>'
ftpUser             = '<FTP/SFTP USER>'
ftpPwd              = '<FTP/SFTP PASSWORD>'
ftpPort             = '<PORT NUMBER, DEFAULT: 22>'
ftpSecure           = '<True IF SFTP, False IF FTP, DEFAULT: True>'
ftpDeleteRemoteFile = '<True/False, DEFAULT: True>'
 
# Amazon S3
s3Bucket            = '<S3 BUCKET NAME>'
s3AccessKey         = '<S3 ACCESS KEY>'
s3SecretAccessKey   = '<S3 SECRET ACCESS KEY>'
s3Folder            = '<S3 KEY PREFIX, DEFAULT: None>'
s3Key               = '<S3 BUCKET KEY NAME, None (ALL KEYS)>'
s3DeleteRemoteFile  = '<True/False, DEFAULT: True>' 
 
# Scheduling
execTimes           = ['HH:MM']

Data Formats

The only data format so far supported is csv. However, csv data can be a lot of things. In the following we described the various variants of csv that MAD can be configured to handle. 

For increased readability we are in the following using spreadsheet screenshots to demonstrate the various formats like this one:

However, the actual data is a delimiter separated line of textual values. Hence, the actual content of for spreadsheet example above is something like this (depends on what delimiter that is being used, in this case a semicolon):

id;gender;byear;profession;language
1234;male;1979;teacher;english
5678;female;1982;nurse;spanish

MAD is highly configurable and support various csv data formats. In the following we will cover some of the option a customer have.

Fixed vs. Free Columns

MAD can be configured with a fixed column format or with a free column format. 

In case of fixed columns, a given column has to have the same data across all files. No column can be added or removed without MAD being reconfigured. In the example above, the five columns shown must always be present and in that same order (even though the cells may be empty). When using a fixed columns format, there is no need for a column heading line in the file. Hence, line 1 above can stay or be removed. The column headings will be "hard  coded" as a list (array) in the MAD configuration file as shown here:

inputKeys= [id', 'gender', 'byear', 'profession', 'language']

In the case of free columns, the position of the columns can be changed from file to file and columns can be dropped and added without any need for reconfiguration. The column heading line is mandatory. Hence, line 1 in the table above must always be present as it is this line MAD uses for mapping attribute names to attribute values. The free columns modus is set by the following MAD configuration:

inputKeys= 'firstline'

The column names used in the CSV data file does not need to be the attribute names that ends up being displayed in Cxense DMP. By providing Cxense with the mappings, the column names in the csv input file will be replaced before uploading. Below we see an example of an input file followed by the MAD mapping  configuration. 

inputKeys = {'id':'id', 'var1':'gender', 'var1':'byear', 'var1':'profession', 'var1':'language'}

The input data and the mapping table will together create the very same end result as the input data in the previous example above.

Internal Keys

MAD can also be configured to use a column independent format in which each data cell holds both the key and the value.

If the first column does not have an internal key, MAD will intepret the value to be the user id (one can also explicitly use id=1234 in the first or any other column). Below we see how to configure for this modus.

inputKeys         = 'internal'
internalDelimiter = '='

Again, the end result will be the very same one as in the two other examples above.

Multi-value Columns

Sometimes one has to deal with types of data for which a column may hold more than one value. The users in the example above are only registered with one language, but many people master two or more languages. How can such data be uploaded?

In the case of the fixed or free column formats one can add extra rows with the additional data. The rows must have the same user id as the original row and all rows with the same id must be grouped together (if not only the last (group of) row(s) for a particular user id will be uploaded).

mergerColumn = 'id'

Another alternative is to use an internal cell delimiter as shown here:

listSeperator = '|'

In the case of internal keys, it is just a matter of adding an extra column with the additional data as shown below. No additional configuration is required.

The formats shown here are the most common ones. MAD also support others less commonly used ones.

Last updated: January 24, 2022