Sagepep

Welcome to the MMEPeP wiki!

Required elements for all events

GA Code	Name	Value
t	Hit type	pageview,event,timing
v	Protocol version	1
tid	Tracking ID	UA-XXXXX-X
cid	Client ID	Device ID

The Client ID (cid) is an identifier used by Google to identifiy a visitor. When using Google analytics.js script this identifier is allocated the first time and stored in a Cookie for later used. This identifier is used for session management and visitor ratios.

Common custom elements

Custom dimensions

Index	Type	Value	Send with
1	Text	A unique customer ID	All
2	Text	Application name	All
3	Text	Unique ID	All
4	Text	Unique user identifier inside the Customer space	All
5	Text	Application version	All
6	Text	Application module name	All
7	Desktpop,Webtop	Platform type	All

Common event categories

These categories has been defined to normalize reports.

Common Events categories

EventCategory	EventAction	EventLabel	EventValue
Startup	Desktop,Server	"Product Information"	1
Setting	"Setting Name"	"Unit of measurement"	Integer
Serial	"Application Name"	"Serial Number"	1
Login	Desktop, Webtop, Mobile	"Application Name"	1
Process	"Process Name"	"Unit of Measurement"	Integer
System	Database, Browser, OS Client, OS Server	"Provider + Version"	1

sagepepmme dll

The sagepepmme dll is an helper dll for Desktop and Server side Applications.

The dll is available in 32 and 64 binary formats and support both Ansi and Unicode string format.

A first set of methods uses the Unicode string format : sagePEPxxx(), an alternative set of methods is available, add "A" to the method name, sagePEPxxxA() to call sagePEPxxx() with an Ansi string instead of a unicode string.

Initializing the dll

This function lets you set the global settings of the DLL.

C Syntax void sagePEPSettings(_in_ PSTR iText);

Parameters

• iText [in]

The setting parameters to be set This parameter must be a valid list of parameter/value couple separate by a comma.

Mandatory parameters

Parameter	Type	used for
Enable	Integer (0,1)	Global enable flag
GAUA	string	Google Analytics tracking ID
AppName	string	Application identification string
AppVersion	string	Application version string
CustomerID	string	Unique customer identifier (for example product serial number)
UserID	string	Unique user identifer inside the customer namespace ; must be impersonal

Note:Parameter names are case insensitive.

Retrieve the dll settings

This function retrieves the current settings from the DLL

C Syntax int sagePEPGetSettings(_ou_ PSTR iText, _in_out_ PSTR iTextLength);

Parameters

• iText [out]

A buffer to receive the settings. If this parameter is null the iTextLength parameter is set with the actual length of the settings string.

• iTextlenth [in/out]

The length of the iText buffer.

• Remarks

• This function could be used to check settings in part of unit test program.
• This function returns also the proxy settings.

Initialize the proxy settings

This function lets you set the proxy settings.

C Syntax

int sagePEPProxySettings(_in_ PSTR iProxyHost,_in_ INT32 iProxyPort,_in_ PSTR iProxyUser,_in_ PSTR proxyPassword);

Return

0 : OK

Parameters

• iProxyHost [in]

Address of the proxy server.

• iProxyPort [in]

Port of the proxy server.

• iProxyUser [in]

Authentication user parameter.

• iproxyPassword [in]

Authentication user password parameter.

Remarks

• For a Microsoft NTLM proxy the authenticate parameters must not be set.
• The proxy is initialized with the Internet Explorer proxy settings, this function overwrite these settings.
• You can reset the default proxy settings by calling sagePEPProxySettings with iProxyHost=

Sending page hits

This function sends a page hit event to Google GA.

C Syntax:

int sagePEPHit(

_in_ PSTR iEltModule,

_in_ PSTR iEltName,

_in_ PSTR iElTitle,

_in_ PSTR iEltReferrer,

_in_ PSTR iEltGroup1,

_in_ PSTR iEltGroup2,

_in_ PSTR iEltGroup3,

_in_ PSTR iUserID

);

Return

0 : OK

1 : PEP is disable

2 : GAUA is not set

Parameters

• iEltModule

The module name related to this page hit

• iEltName

The page name

• iElTitle

The page title

• iEltReferrer

The referrer of the page

• iEltGroup1

A grouping category relevant to this page

• iEltGroup2

A grouping category relevant to this page

• iEltGroup3

A grouping category relevant to this page

• iUserID

(New in 0.3) Optional UserID, overwrite the global settings, pass an empty string to ignore

Remarks

• This function is asynchronous, requests are pushed in a transmit queue and send by a working thread. The function returns before the request was sent.

Sending events

This function sends an event event to Google GA

C Syntax:

Int sagePEPEvent(

_in_ PSTR iCategory,

_in_ PSTR iAction,

_in_ PSTR iLabel,

_in_ INT32 iValue,

_in_ INT32 iMetric,

_in_ PSTR iUserID

);

Return:

0 : OK

1 : PEP is disable

2 : GAUA is not set

Parameters

• iCategory

The category of the this event. See Common event categories for a list of normalized categories.

• iAction

The action associates to this event.

• iLabel

The label associate to this event.

• iValue

The integer value associate to this event.

• iMetric

A supplementary value associate to this event.

• iUserID

(new in 0.3) Optional UserID, overwrite the global settings, pass an empty string to ignore

Remarks

• See sagePEPHit

Sending event sets

This function sends a set of events to Google GA

C Syntax:

Int sagePEPEvents(

_in_ PSTR iCategory,

_in_ PSTR iAction,

_in_ PSTR iKeyValues,

_in_ INT32 iMetric,

_in_ PSTR iUserID

);

Return:

0 : OK

1 : PEP is disable

2 : GAUA is not set

Parameters

• iCategory

The category of the this event. See Common event categories for a list of normalized categories.

• iAction

The action associates to this event.

• iKeyValues

A key/value set. Each key/value will be send has an event.

• iDuration

A duration associate to this set of events.

• iUserID

(New in 0.3) Optional UserID, overwrite the global settings, pass an empty string to ignore

Remarks

• See sagePEPEvent

sagepepmme js

The sagepepmme.js is a javascript wrapper for analytics.js

Using the sagepepmme.js

Include the sagepepmme.js in your script section, you can include the minimized version or the debug version.

<script type="text/javascript" src="../js/sagepepmme.min.js"></script>

or

<script type="text/javascript" src="../js/sagepepmme.js"></script>

The sagepepmme defines a javascript module inside a _sageMME namespace

You can get a reference on this module using window._sageMME.pep

<script>
   var _GA = window._sageMME.pep;
   _GA.setSettings(data);
</script>

Note : The sagepepmme.js script includes the Google analytics.js loader, you don't have to include analytics.js in your html page.

Initializing the module

The module maintains some globals which can be set by the setSettings() function.

function setSettings(data) {};

member	type	used for
enable	boolean	This is a global flag which enable or disable the tracking.
ua	string	The tracking ID to be used.
dialogUrl	string	The url of the inrollment dialog, overwrite the default
cd	structure	Static custom dimensions

An example of data structure to initialize the module :

"GA":{"enable":true,"ua":"UA-55379346-6","cd":{"dimension1":"000000","dimension2":"Sage FRP 1000 Suite Financière-7.0.0.0","dimension4":"00000000000000000008000000640028"}}

Sending page hits

Use the sendPageView function to send pageview hits.

function sendPageview(data) {};

member	type	used for
pageName	string	The name of the page
pageTitle	string	The title of the page
pageModule	string	The module name of the page

Example :

var _GA = window._sageMME.pep;
_GA.setSettings({"enable":true,"ua":"UA-XXXX"});
_GA.sendPageView({"pageName":"acountForm", "pageTitle":"Account entry", "pageModule":"Accounting"});

Sending events

Use the sendEvent function to send event.

function sendEvent(data) {};

member	type	used for

Example :

var _GA = window._sageMME.pep;
_GA.sendEvent({
'eventCategory':'System',
'eventAction':'Browser',
'eventLabel':navigator.userAgent,
'eventValue':1,
'cd7':'Webtop'
});

Calling the inrollment dialog

The module has support to manage the inrollment dialog.

Use the showDialog function to display the inrollment dialog.

function getDialogDiv(idName){};
function showDialog(elt, callback){};

• getDialogDiv() lets you redefine the default id name of the container element.
• showDialog() display the dialog in an iframe an call you in response.

Example :

var _GA = window._sageMME.pep;
_GA.showDialog(_GA.getDialogDiv("pepDialog"), 
	function(e) {
		// PEP callback
		// manage result here
		// e.data is a struct with result member
		// This code update the user status on the server side
		_myAjax.sendJSONService(_myGA.pepJSONURL, function(object, error)
		        // server answer with the new settings for GA
			// redefine GA settings
			if (object.GA) _GA.setSettings(object.GA); 
		}, null, null, e.data, true);
	}
);

Enrollment dialog

The enrollment dialog manage the opt in / opt out user workflow.

The dialog is a simple dialog which doesn't require a server back end.

Using from a desktop program

The dialog may be call by a desktop program using Microsoft Internet WebBrowser control.

The calling process must monitor the navigation to catch the user reply.

see dlgpep.pas for calling example.

Using from a web client

The dialog may be call in an IFrame. The user reply is send via messaging to the parent container.

see the sagepepmme.js for calling example.

Parameters

The dialog has two optional parameters

Parameter	Value
status	The current enrollment status of the user
lang	The user language

• The "status" parameter is used to pre check the acceptance checkbox.
• The "lang" parameter is used to set the user language, if not set the navigator language is ued. Note that IE control do not set the language so you may have to explicitly set it.

Translation

The dialog may be translated to any user language. As describe before the user language is either passed as an argumet or defined by the navigator language.

Translation files are json files which are located in the localize folder.

guisagepepdll

guisagepepdll is a unit test program.

You don't need to deliver it with your release but you can used it for test purpose.

guisagepepdll.exe uses guisagepepdll.ini for configuration.

Settings

You must change the GAUA parameter to switch to your own Google Analytics test tracking ID.

Minimum execution

You must execute :

• TestSagePEPOK

Test the presence of the dll

• TestSettings

load configuration in the dll

before testing event or hit functions.

Testing the proxy

The proxy settings may be used to resolve proxy problems. By default, the dll used the system proxy configuration.

• TestProxySettings

Load the proxy configuration of the .ini in the dll

• TestSystemProxy

Reset the default system proxy configuration