1.0.0 • Published 4 years ago

tracking-ebay-test v1.0.0

Weekly downloads
-
License
-
Repository
github
Last release
4 years ago

tracking-ebay

Build Status Dependency Status Code Coverage

NOTE for Marko V3+

You also need to install tracking-marko-ebay module to support Marko V3+ compatible taglib.

Changelog

See CHANGELOG.MD

Overview

This module provides support for user tracking in eBay Node.js applications. This includes the following

Client-side tracking:

  • Natural search tracking - tracking of entries to eBay via search engine searches.
  • Roversync tracking - synchronization of cross-site guid
  • Direction destination tracking - Tracking of page, module, link flows
  • Impression tracking - Tracking page flows
  • IdMap Tracking - Mapping of users between partners and eBay for off-site targeting
  • SiteCatalyst Tracking - Client-side tracking based on 1% sampling

Server-side tracking:

  • Sojourner tracking of global flags and tags that are common for all pages; default page-level tracking
  • Application Sojourner tracking - application-specific tags, flags, or modules, Sojourner data logging.
  • Guid generation and setting of appropriate cookies.

Installation

Install the module into your project:

npm install tracking-ebay --save

Enable the tracking-ebay middleware and other required middleware (order matters):

app.use(require('commons-ebay/middleware')(...));
app.use(require('cookies-ebay/middleware')(...));
app.use(require('tracking-ebay/middleware')(...));

The above is for the case where you explicitly wire them up. For most Unified Node.js apps, the infrastructure will take care of wiring them up in the proper order for you via config/middleware.json.

Usage

Configuring Tracking

By default, a route with a page name/ID will be tracked if the tracking-ebay middleware is executed for the request. Tracking can be optionally configured on a per-route basis by updating the routes.json file as shown below:

routes.json:

[
    {
        "path": "GET /my-page",
        "handler": "require:./src/pages/my-page",
        "pagename": "MyPage",
        "tracking": {
            "enabled": true, // enable/disable tracking for this route (defaults to true)
            "flagsEnabled": false, // enable/disable logging of application flags to Sojourner (defaults to false)
            "siteCatalystPageName": "", // The name to use for site catalyst tracking (defaults to "pagename")
            "isLowVolume": false, // Configure if this command is low volume to control reporting in
                                  // http://ewa.vip (defaults to false)
            "appliationId": "sc-test-page" // application ID for external clients (see soj tag 'app')
        }
    }
]

Note: Debug tracking page info will be written to the page source in case you set request header:

X-EBAY-PAGE-INFO: true.

Enable Client-side Tracking

Marko:

<html>
    <head>
    </head>
    <body>
        ...
	<lasso-body/>
        <tracking-cookies />
        <tracking-images />
        <tracking-module id="334" />
        <tracking-body /> <!-- outputs tracking JS code -->
    </body>
</html>

Note : You need to add above tracking tags after <lasso-body/>.

Experience service case

In experience service use-case the tracking-body tag should be synchronized with the experience service response. So instead of the above example, one would need to use the following:

<await(dummy from data.experienceServiceData)>
	<tracking-cookies/>
	<tracking-images/>
	<tracking-body />
</await>

Experience service FAQs:

  • Q: I got tracking error stating Experience service flow has been detected, tracking-body tag should be rendered once experience service response is received to make sure psi is correct, please see https://github.corp.ebay.com/nodejs/tracking-ebay#experience-service-case or due to experience service error the ciid was not passed back.

    A: There are a few possible root cause:

    • ciid is missing in response headers from experience service; possible causes - QA outage in case you get it in QA, especially when it has been ok before. Pulsar tracking is not enabled on Experience service or not used.
    • ciid is present but is executed before the response from experiece service comes. In that case you need to use async marko feature to wait for it before rendering tracking header.

Tracking Module Impressions

req.ebay.tracking.trackModuleImpression(9999);

Link Tracking

Marko:

<tracking-helper var="tracking" />

<div id="debug" _sp="${tracking.spTag().moduleId(2611).linkId(3376)}">
    <ul>
        <li>
            <a href='/foo' >Test Link 1</a>
        </li>
        <li>
            <a href='/bar' >Test Link 2</a>
        </li>
    </ul>
</div>

Client side tracking requires one to enable tracking in optimizer in config.json file and add special dependency:

App Lasso configuration (config.json, development.json, staging.json etc):

    "lasso": {
        "plugins": [
            ...
            "tracking-ebay/optimizer/plugin",
            ...
        ],
        ...
    },

Tracking Application Tags

//track single-value tag
req.ebay.tracking.trackTag('ddm', '1'); // ddm is sojourner name for DEFAULT_DISPLAY_MODE in AR

//track multi-value tag with single value at a time
req.ebay.tracking.trackVectorTag('ddm', '1');

//track multi-value tag with multiple values at a time
req.ebay.tracking.trackVectorTag('ddm', ['1','2']);

Tracking Application-specific Flags

Important: "flagsEnabled: true" in middleware param.

//track flag, (req, bitpos)
req.ebay.tracking.trackFlag(1); // it goes to application flag set attached to current page, as bit 1

Tracking with Commerce OS Services

var headers = { ... };

req.ebay.tracking.addTrackingHeadersForRequest(headers);

function onResponse(res) {
    req.ebay.tracking.handleResponseHeaders(res.headers);
}

Client-side Event Tracking

var trknvp = {"sid":"p1234.m567.l9090","itemId":"34555674442" }; // put the raw sojourner tag and value
$(document).trigger('rover', trknvp) ;

Marko V3 Upgrade

Install tracking-marko-ebay module to support Marko V3+ compatible taglib.

https://github.corp.ebay.com/nodejs/tracking-marko-ebay

Advanced

Registering Modules, Tags, Flags, etc.

Please use http://go/arui

Shortcut to create tracking assets: https://www.aruitool.stratus.ebay.com/aruitoolweb/createPage

ATTENTION: You have to manually insert every new page, module, tag, flag, etc in QA DB

Copied from http://raptor/portal/1.6.0/learn/topics/Tracking#Tracking-MetadataSetup

Go to http://tools/datools/srishivananda/cgi-bin/Query.cgi

Select TrackingMetadataHost in Database dropdown

Mark "auto commit"

run below query with your own metadata information. The numeric ids(page id, module id, etc) of all assets do not matter, make them unique is the only requirement.

--PAGE metadata, page name SellerOtherItemRaptor has to match your new page page.
insert into trk_page values(2046732, 'SellerOtherItemRaptor', 'ksenji@ebay.com', 'Raptor Seller Other Item Page', 3, 0, 1, 'Asset Repository', sysdate, sysdate,'',0,'',0);

--PAGE/FLAGSET metadata
insert into trk_page_flagset values(466, 2046732, 26, sysdate, sysdate, 'Kishore Senji', 'ksenji@ebay.com', 3);

--PROPERTY/tag metadata, sQr should match your sojourner key.
insert trk_property values(639, 'KEYWORD', 'kkanth@ebay.com', ' The search keyword used.', 'sQr','java.lang.String', '','',3,'Asset Repository', sysdate,sysdate);

--MODULE metadata
insert into trk_module values(6, 'text_ad', 'rghosh@ebay.com','Text ad display',3,'Asset Repository', sysdate,sysdate);

--FLAG metadata, 100 has to match the bit position of new flag
insert into trk_flag values (123456,26,'flagbitnmae', 100, 'flag for 100 bit position desc', 3, 'AssetRepository', sysdate,sysdate);

Tracking 2.0

One tracking Event per Request Module - RequestScopeTracker

RequestScopeTracker is used in the model that all the tasks in the request can collaborate to add tracking payload. As the request complets, the tracking event will be published by sending events to Collection Service . The model can be depicted as show in the diagram. request-scope-tracker

Here is the usage with codes.

var tracker = req.ebay.tracking.getRequestScopeTracker();
//"et": "TOPN:TSA:1.0",
var eventAction = "TOPN";
var eventFamily = "TSA";
var version = "1.0";
//set Event type
tracker.setEventType(eventAction, eventFamily,  version);
//add paypload
tracker.addData('rmaqe', 37);
tracker.addData('kwd', 'nike');
tracker.addData('prdi', 1234);
var itemsList = [10, 20, 30];
tracker.addData('itms', itemsList);
//set event flag
//EventFlag is relevant to the eventType
tracker.setEventFlag(0, true);

Asynchronous Self contained Tasks and Tracking - PulsarEventTracker

With PulsarEventTracker, tracking events can be published from the self-contained tasks individually. The model can be depicted as show in the diagram. pulsar-event-tracker

Here is the code usage example.

var tracker = req.ebay.tracking.getPulsarEventTracker();
var eventAction = "TSTV";
var eventFamily = "TVW";
var version = "1.0";
tracker.setEventType(eventAction, eventFamily,  version);
tracker.addData('rmaqe', 37);
tracker.addData('kwrd', 'nike');
tracker.addData('prdi', 123);
var items = [10, 20, 30];
tracker.addData('itms', items);
//flush the event to publish
tracker.flush();

Colloborative Tasks and Self-Contained Tasks

You can mix the usages with both RequestCopeTracker and the PulsarEventTracker. The model can be depicted as shown in the diagram. mix-tracker

Preconditions

Please contact Tracking team to add Pulsar Metadata for your project and register your application in Tracking Repository. Here is the example of tracking Pulsar Metadata for app (Web) applications in production. http://pmsvc.ebay.com/pmsvc/resourceInstance/findAll/app Here is the examples in QA. http://phx5qa01c-9b44.stratus.phx.qa.ebay.com:8080/pmsvc/resourceInstance/findAll/app An important thing is to add the rampUp property as the sampling rate (0-100) for tracking.

<property>
<name>rampUp</name>
<value>100</value>
</property>

Advanced Usage for Tracking 2.0

Tracking 2.0 is based on the rest service. Please refer the following document for service specification. https://wiki.vip.corp.ebay.com/display/TRACKING/Pulsar%20Collection%20Service%20DOC Or you can check the saved pdf file

For the usage of corresponding Raptor Tracking Client Library with Raptor-Java Stack, you can check: https://github.corp.ebay.com/Tracking/RaptorTrackingClientLibrary/blob/master/docs/README.md

SOJ Channel Testing

#Experience Service Tracking in NodeJS

Summary

Tracking Web Pages has fundamentally changed from tracking the Web Page requests to a centralized way of tracking the Experience Service Operation. Reason behind this change is to aggregate the tracking by the Service Operation rather than by the consumers, in this case is a Web Page, Native App etc.

To accomplish Tracking in NodeJS, you might want to few steps.

Step 1 : Application Specific

Add the Experience Service application name in the NodeJs applications index.js

Index.js : The file where you start listening on a port 8080 | any when you application server starts.

Example:

var express = require('express');
var kraken = require('kraken-js');
var brogan = require('brogan-ebay');

var options = {
    onconfig: function (config, cb) {
        cb(null, config);
    },
    experienceService: 'search-experience-svc' /** This is sample name **/
};

app = express();
app.use(kraken(brogan(app, options)));

The reason for this entry is we dont want NodeJS application wait for the 1st Request to fetch the Application MetaData. This will ensure application load the application meta data for experienceService also.

Step 2 : Request Specific

Identify Experience Service OperationId and add it to the Routes.json file.

Example: Routes.json

[{
     "path": "GET /keywords/:keywords",
     "handler": "require:./src/pages/search-results",
     "pageName": "KeywordSearch",
     "expSvcOperation":"KeywordSearch" /**KeyWorkdSearch is sample registered Experience Service Operation Name **/
 }
 ]

The reason for this entry is , NodeJs application will get the Experience Service OperationId from the Route matching with the application meta-data setup in the previous step.

Step 3 : Keep the framework modules latest.

Install the latest NodeJS Platform modules

brogan-ebay

This NPM Module blends the KrakenJS to Ebay

commons-ebay

This NPM Module is a Middleware sets up the Ebay Request Context

tracking-ebay

This NPM Module provides integrates tracking features to the application.

Pulsar JS to handle Module View/Actn Events

PulsarJS will be enabled when the client applications use the back-end ExperienceService, PulsarJS will be added to the page flow through the standard TAAS and Tracking Tags.

Application teams dont need additional code.

Initiating Pulsar JS From Web Application

var trackingData ={ "eventFamily": "REXP", "eventAction": "ACTN",
"flushImmediately": false, "eventProperty": { "sid": "p2050450.m569" } };

$(document).trigger('pulsar', trackingData);

Experience Service Tracking

Tracking Web Pages has fundamentally changed from tracking the Web Page requests to a centralized way of tracking the Experience Service Operation. Reason behind this change is to aggregate the tracking by the Service Operation rather than by the consumers, in this case is a Web Page, Native App etc.

Changes

  • Provide ability to track the Web Request by the Experience Service OperationId

  • Use the CIID value provided by the TAAS service as the Page Impression.

  • Send the tracking correlation session to the down stream services as HTTP Request Headers.

Usage

Install the latest NodeJS Platform modules

brogan-ebay

This NPM Module blends the KrakenJS to Ebay

commons-ebay

This NPM Module is a Middleware sets up the Ebay Request Context

tracking-ebay

This NPM Module provides integrates tracking features to the application.

Configuration

Configure the target Experience Service to be used along with the Web App

Example of Configuring through code.

Every applications' index.js || app.js uses brogan-ebay to bridge KrakenJS with the Ebay NodeJs applications

 var express = require('express');
 var kraken = require('kraken-js');
 var brogan = require('brogan-ebay');

 var options = {
     onconfig: function (config, cb) {
         cb(null, config);
     },
     experienceService: 'freedom' // <<< Note: this is experience service application name, not web app name
 };

 app = express();
 app.use(kraken(brogan(app, options)));

PS: All the application code is currently doing the above, only change is to add 'experienceService' attribute to the Options Object.

Configuring multiple experience service targets

It is highly likely your application might be needed to communicate with multiple Experience Services

Example:

 var express = require('express');
 var kraken = require('kraken-js');
 var brogan = require('brogan-ebay');

 var options = {
     onconfig: function (config, cb) {
         cb(null, config);
     },
     experienceService: ['uss','search-exp', 'vi-exp']
 };

 app = express();
 app.use(kraken(brogan(app, options)));

Request Route Management

Every web request will be invoking a specific Experience Service Operation to fetch data and other entities. The routes should be aware of the target experience service and service operation name per Request Url.

To identify the experience service operation, you should add the target experience service attribute the Routes.json on the relevant Request Routes.

Example
Route using a default experience service.
[
 {
     "path": "GET /keywords/:keywords",
     "handler": "require:./src/pages/search-results",
     "pageName": "KeywordSearch",
     "expSvcOperation":"KeywordSearch"
 }
]
Route using with Experience Service Name & Operation
[
 {
     "path": "GET /item/info/:id",
     "handler": "require:./src/pages/item",
     "pageName": "ItemInfo",
     "expSvcOperation":"vi-exp:ItemInfo" // `vi-exp` is the Experience Service Name and ItemInfo is the Operation
 }
]

Note: here we set experience service operation name with experience service application name as a namespace. This is useful when one has multiple experience services and this allows to indetified which service operation name belongs to.

Click Tracking data

Sample Experience Service JSON

{
   ...
  "action": {
    "type": "NAV",
    "URL"
    "tracking": {
      "flushImmediately": false, // ask analytics team
      "eventProperty": {
        "sid": "p2050450.m567.l1",
        "trkp": "itm%3A170007634567%7Ccatid%3A1234"
      }
   ...

With the above response from experience service, the application team needs the following

 1.pick the "sid" and put the value into "_sp" attribute.
 2.pick the "trkp" and add to the url as "_trkparms"
trackingsojournertaas
appmeta-ebayasyncbit-setcommons-ebayenvironment-ebayheader-multi-value-ebayhoeklogging-incmodule-config-incmomentobjutilon-headersraptor-asyncservice-client-ebaytry-requireunderscoreutils-ebaypathfinder-ebayipcolo-detect-ebaysecurity-ebay
1.0.0

4 years ago