POST/activity (単独のアクティビティ)

ドキュメント

🚧
ユーザデータとアクティビティおよびModelクエリの一貫性
ユーザデータとアクティビティおよびModelクエリを関連付けるには、アクティビティおよびModelクエリに同じuserIdの値を含めてください。そうすることで、userIDと蓄積されたユーザデータをマッチングさせて、その情報に基づいて個別のリコメンデーションを最適化します。
下記のフィールドタイプは、LiftIgniterに送る際に送ることができるパラメータの、よくある使用例を示しています。 LiftIgniterはユーザのアクティビティに基づいてリコメンデーションを提供するため、ここで選択したパラメータは、Modelエンドポイントにも渡されます。
複数のアクティビティを一括して送る場合は、このページにあるドキュメントで、それぞれアクティビティで送るフィールドの情報を確認してください。アクティビティAPIに情報をラップ（wrap）してPOSTする方法については、/activity（複数のアクティビティ）のドキュメントを参照してください。

❗️
URLの代わりにIDをインベントリアイテムの識別に使用している場合
インベントリアイテムの識別にIDを使用している場合は、下記のパラメータを使用してください:
"url"を"id"に変える。
"clickUrl"を"clickId"に変える。

apiKey（必須）: このフィールドの値は、お客様を識別するキーです。このフィールドが存在しない場合や、間違った値を持つアクティビティは拒否されます。このフィールドがない場合は、アクティビティをPOSTすることはできません。

timestamp: このフィールドの値は、現在のUNIXタイムスタンプ（ミリ秒単位）を表します。文字列数は13文字列です。タイムスタンプが含まれていない場合は、我々がリクエストを受信した時点のタイムスタンプを使用します。イベントの発生より遅れてイベントを送る場合は、タイムスタンプの値を含めることを推奨します。

イベントタイプ

下記の一般的なイベントタイプをサポートしています。

pageviewは、ユーザがWebサイトまたはアプリ上のページを閲覧していることをマークするイベントです。これはイベントの種類の中で最も一般的なもので、ユーザのフローを構成する上での基本要素となります。

playは、動画やGIFの再生を開始したことをマークするイベントタイプです。Webページが読み込まれた際に、動画やGIFが自動再生されない場合は、このイベントを個別に送ることが重要です。

engagedは、ユーザがコンテンツにエンゲージしたことを示すイベントタイプです。例えば、動画のWebサイトにおいて、動画の50％以上が再生された場合に定義することができます。コンテンツのWebサイトおいては、記事の50％以上をスクロールしたユーザを定義することができます。

conversionは、トラックしたいイベント（商品の購入、アカウントの作成、メーリングリストへの登録など）に使用する一般的なイベントの名称です。

endedは、ユーザがコンテンツの利用を終えたことを示すカスタムイベントの種類です。動画の場合は、ユーザが最後まで動画を再生した場合を意味します。

Pageview activitiesは、ユーザが行っているアクティビティを認識するために必須の値です。他のものはオプションですので、個別のニーズやLiftIgniterと検討したKPIに応じて使用してください。

アプリへの組み込みにおいては、ユーザとのやり取りが一般的なWebフローと異なることがあります。そのような場合は、カスタムのイベントタイプを送信して、その詳細を事前にお知らせください。

pageview（ページ閲覧）

ページ閲覧はユーザの行動履歴において基本となるアクティビティです。このデータ（ユーザがWebページに至る際に参照したWebページを含む）をリアルタイムで送ることで、LiftIgniterはユーザが閲覧したアイテムにあわせてリコメンデーションをパーソナライズします。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "pageview",
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "title": "A Beautiful Sea"
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer" : "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "sourceWidgetName": "default-widget",
  "viewType": "new"
  "deviceType": "desktop"
  "os": "Win64"
  "ip": "168.0.0.1"
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0"
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661"
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"
}' https://api.petametrics.com/v1/activity | python -mjson.tool

Shown（表示）イベントとVisible（可視）イベント

Webページに表示したウィジェットについて、2つの特別なイベントを送信してください。

widget_shown（ウィジェットの表示）

LiftIgniterのリコメンデーションウィジェットをページに正常に表示すると、widget_shownのイベントが送信されます。 widget_shownイベントに含める必要がある3つの項目（url、timestamp、referrerなど一般的なものを除く）は、visibleItems（表示されたアイテムのJSON配列のリスト）、source（"LI"または"base"）、widgetName （ウィジェットの名前）です。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "widget_shown",
  "widgetName": "default-widget",
  "visibleItems": [list of all recommended items in widget as a JSON array],
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

widget_visible（ウィジェット可視）

widget_visibleのイベントは、widget_shownイベントに似ていますが、ウィジェットの表示と同時に送るのではなく、アイテムがユーザのviewport（可視領域）に入った際に送信します。

コンテキストによっては、これらのイベントを送信できない場合があります。これらのイベントの値がなくても組み込みを行うことは可能ですが、可能な限りこれらのイベントの値を送ることを推奨します。 widget_visibleが技術的に対応できない場合でない場合、widget_shownの値だけでも十分に機能します。これらのイベントのどちらも送信できない場合は、リコメンデーションのアルゴリズムと機械学習への影響範囲を把握するために、サポート部門にご相談いただくことをおすすめします。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "widget_visible",
  "widgetName": "default-widget",
  "visibleItems": [list of all recommended items visible to the user in the widget as a JSON array],
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

クリックイベント

クリックイベントを使用することで、データにおいて強力なリアルタイムの機械学習能力を付加することができます。これらは、シンプルなユーザ行動のModelを構築するためには必要ありませんが、より強力なModelを構築し、リアルタイムでアップデートを行う際に活用できます。

クリックイベントには2つの種類があります: .

widget_clickは、LiftIgniterによって提供されたリコメンデーションアイテムに対するクリックを指します（このイベントは、A/Bテストにおいて他のソースから提供されたリコメンデーションに対するクリックについても送ってください）

engaged_clickは、ウィジェットのクリックから発生した、ユーザがエンゲージしたことを示すイベントにおいて送ってください。

クリックイベントの送信における主な技術的課題は、ユーザとユーザとクリックイベントに対するページ閲覧のコンテキストを、クリックが発生したページの情報に含めることです。したがって、これらの情報をクライアント側またはサーバー上に保存する必要があります。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "widget_click",
  "widgetName": "default-widget",
  "visibleItems": [list of all recommended items in widget as a JSON array],
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "clickUrl": "http://www.dummydomain.com/a-lovely-beach.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "engaged_click",
  "widgetName": "default-widget",
  "visibleItems": [list of all recommended items in widget as a JSON array],
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "clickUrl": "http://www.dummydomain.com/a-lovely-beach.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

同様に、ユーザがURL AからURL Bをクリックした後、URL Bでエンゲージした場合に、関連するクリックイベントは下記のとおりです。

ユーザエンゲージメントイベント（オプション）

ユーザエンゲージメントのイベントには、"engaged_t"のパラメータを使用します。このフィールドではあらゆる文字列の値を使用することができ、なんらかのポジティブなエンゲージイベントが発生した時に送ります。ここで指定するエンゲージイベントの例は下記のとおりです:

イイねをした
コメントした
賛成票を投票した
特定の位置までスクロールした

ネガティブなエンゲージメント（反対票を投票した、Webページやアイテムの低評価をしたなど）はデフォルトではトラックしていません。もしこれらのエンゲージメントがアプリやWebサイトの使用において重要な意味を保つ場合は、LiftIgniterにご連絡ください。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "engaged",
  "engaged_t": "like"
  "widgetName": "default-widget",
  "visibleItems": [list of all recommended items in widget as a JSON array],
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

コンバージョン（オプション）

コンバージョンのイベントには、"conversion_t"のパラメータを使用します。このフィールドではあらゆる文字列の値を使用することができ、なんらかのコンバージョンイベントが発生した時に送ります。ここで指定するコンバージョンイベントの例は下記のとおりです:

ニュースレターを購読申込した
カートに商品を追加した
カートの商品を購入した
イベントにサインアップした

コンバージョンイベントを送ることで、Modelは自動的にCTRの向上と同時にコンバージョンの向上のための最適化を自動的に行います。

Eコマース向け
"conversion_t"に追加して、"price"の情報を含めることができます。これはデフォルトでは有効化されていませんが、この情報を使うことでより高単価のアイテムに対して最適化を行います。この機能を使用したい場合は、LiftIgniterにご連絡ください。

属性について::
コンバージョンイベントは、コンバージョンの発生に起因したウィジェットに紐付ける必要があります。例えば、ユーザがSessionのはじめウィジェットをクリックしてコンバー所にベントが発生する前にいくつかのページを回遊した場合などでは、widget_clickとコンバージョンの関連性はとても弱くなります。ユーザが商品のリコメンデーションをクリックしてから商品をカートに追加し、購入した場合では、この関連性が明確になります。

通常では、widget_clickはコンバージョンの直前に発生します。このコンバージョンは、そのウィジェットに対して属性をもたせることを推奨します。この他の属性のもたせ方については、様々な選択肢がありますが、コンバージョンはModelの構成においてとても強いシグナルを持っており、Modelの最適化に大きな役割をはたすことを認識してください。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "conversion",
  "conversion_t": "subscribed",
  "widgetName": "default-widget",
  "url" : "http://www.dummydomain.com/email-me.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/a-beautiful-sea.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "conversion",
  "conversion_t": "add-to-cart",
  "price": 29.99,
  "widgetName": "default-widget",
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

メディアの利用（オプション）

同様に、ユーザがURL AからURL Bをクリックした後、URL Bでエンゲージした場合に、関連するクリックイベントは下記のとおりです。

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "play",
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

curl -H "Content-Type: application/json" -d '{
  "apiKey" : "YOUR_API_KEY", // REPLACE WITH YOUR API KEY AND REMOVE THIS COMMENT
  "timestamp" : 1400464843310,
  "type" : "ended",
  "url" : "http://www.dummydomain.com/a-beautiful-sea.html",
  "source": "LI" or "base",
  "userId" : "de305d54-75b4-431b-adb2-eb6b9e546013",
  "referrer": "http://www.dummydomain.com/holiday-resorts.html",
  "referrerType": "direct",
  "deviceType": "desktop",
  "os": "Win64",
  "ip": "168.0.0.1",
  "userAgent": "Mozilla/5.0 (Windows NT 6.3; Win64; x64; rv:56.0) Gecko/20100101 Firefox/56.0",
  "pageviewId": "34219bae-e05d-4c6d-b964-d7d051be7661",
  "sessionId": "a95eeafe-d5bf-4064-85c1-eaf5710d67e3"  
}' https://api.petametrics.com/v1/activity | python -mjson.tool

Webサイトへの組み込みにおいて、クリックイベントとあわせて送る必要がある、前のページビューに関する追加フィールドは、ユーザのCookieやローカルのストレージに保存することができます。ローカルディスクは、より大量のデータを格納できるため、この使用に適していると考えられます。

🚧
データ送信の重要性
LiftIgniterのリコメンデーションエンジンは、これらすべてのデータを送ることを必須としていません。しかしながら、ガイドラインに基づいて送るデータの量が増えるほど、機械学習の精度が向上し、分析レポートの質を向上させることができます。
もし特定の送信できないデータがある場合は、そのデータの欠落によるリコメンデーションシステムへの影響や、提供できなくなる指標を理解していただくために、事前にサポートにご相談ください。

📘
個別のアクティビティに複数のイベントタイプをまとめる場合
個別のアクティビティに複数のイベントタイプをまとめて送ることができます。よくある例としては、動画サイトにおいてユーザがビデオをクリックし、その一部を見てから別のページに移動した場合に、
イベントが発生するごとにイベントタイプを送るのではなく、ユーザが動画の再生終了時に、関連するイベントをすべてまとめて個別のアクティビティとして送るようなケースがあります。

例:

複数のイベントをまとめて送る場合は、最初のイベントのタイムスタンプを送ってください。イベントは遅れて送信されるため、この場合は最初のイベントのタイムスタンプを使用することが重要です。

同じ情報を３つの異なるイベントとして送ることもできます。これは御社システム側のインフラの運用環境によって、イベントを発生するごとに送るか、後からまとめて送るかの選択をすることができます。

イベントタイプの方式以外で複数の個別アクティビティを送る場合は、/activity（複数のアクティビティ）のドキュメントを参照してください。

POST/activity (単独のアクティビティ)

🚧
ユーザデータとアクティビティおよびModelクエリの一貫性

❗️
URLの代わりにIDをインベントリアイテムの識別に使用している場合

イベントタイプ

pageview（ページ閲覧）

widget_shown（ウィジェットの表示）

widget_visible（ウィジェット可視）

クリックイベント

ユーザエンゲージメントイベント（オプション）

コンバージョン（オプション）

メディアの利用（オプション）

🚧
データ送信の重要性

📘
個別のアクティビティに複数のイベントタイプをまとめる場合

🚧ユーザデータとアクティビティおよびModelクエリの一貫性

❗️URLの代わりにIDをインベントリアイテムの識別に使用している場合

イベントタイプ

pageview（ページ閲覧）

widget_shown（ウィジェットの表示）

widget_visible（ウィジェット可視）

クリックイベント

ユーザエンゲージメントイベント（オプション）

コンバージョン（オプション）

メディアの利用（オプション）

🚧データ送信の重要性

📘個別のアクティビティに複数のイベントタイプをまとめる場合

🚧
ユーザデータとアクティビティおよびModelクエリの一貫性

❗️
URLの代わりにIDをインベントリアイテムの識別に使用している場合

🚧
データ送信の重要性

📘
個別のアクティビティに複数のイベントタイプをまとめる場合