Pega Systems

Pega SDK

Before starting your application instrumentation, ensure that you have created an app and have an appKey

Install

Installing Pyze Analytics for Pega is simple, and will require Pega Web Analytics Component as dependency.

Download the Pega component from the pega marketplace

Download the Pyze component from the github releases

  • Open your Application Definition. (Application -> Definition)
  • Click Manage components.
  • Select Install new and select the zip file that includes the component. Starting with the Web Analytics Component
  • Click Open.
  • Select Enabled to enable the new component for this application.
  • Click OK.

For more information check the link : Installing Component

Initialize

To initialize Pyze component open Data-Admin-System-Settings by going to App tab and searching for Data-Admin-System-Settings as shown below.

Find PyzeIntegRS and set the value to your Appkey

The pyze SDK will now start capturing many automated metrics.

Custom Events

Events allow you to easily track unique user actions within your app.

Event

Pyze custom events can be called from Run Scripts in pega.

  • Add a Run script to button action as shown below image
  • Pass the below snippet as Function Name
"PyzeEvents.postCustomEvent";
  • Add the paramter to the run script action as the event name as shown below

This allows you to track when a user executed an action, for a simple count of how often that event is occurring.

Event with Attributes

Attributes are any key-value pair that you can attach to an event. You can have up to 99 attributes with any event. It is highly recommended to follow our Best Practices and heavily rely on attributes to make your instrumentation as minimal and useful as possible. In a typical application, you should have many more attributes than events.

  • Pyze API to send custom attributes accepts the attributes in JSON format.
  • Create a HTML Fragment by going to Records -> Technical -> HTML Fragment
  • Add a script tag and define a javascript function to be invoked from the Run script as shown below.
<script>
function postCustomEventWithAttrbutes(){
  var attributes = {};
  attributes["screen"] = "Home";
  attributes["seconds spent"] = "50";
  PyzeEvents.postCustomEventWithAttributes("Blog Read", attributes);
}
</script>
  • Finally invoke the postCustomEventWithAttrbutes function from the Run Script. Don’t use double inverted quotes while calling the function.

Timed Events

Timing how long a user takes to complete an action is a common usecase for Pyze. The SDk has built-in handling for this, by allowing you to start a timer, and then send a custom event at the completion of that action.

  • startTimerForEvent - Start the timer with a name
  • postTimedEvent - End the timer by referencing the same name. The time in milliseconds will automatically be attached to this event. You can also optionally pass attributes as an additional paramater as show in the example below
//Start timer for event
PyzeEvents.startTimerForEvent("Screen Load Time");

//Post timed event.
//Note : The event name attribute for the `startTimerForEvent` and  `postTimedEvent` should match.
PyzeEvents.postTimedEvent("Screen Load Time");

//Post timed event API when you want to send additional attributes
var customAttributes = {};
customAttributes["device"] = "iMac";
customAttributes["location"] = "CA";
PyzeEvents.postTimedEventWithAttributes("Screen Load Time", customAttributes);

Profile

Profiles are a powerful way to add data about your users to Pyze. Use profiles to add data that is not specific to a point in time (events) and are attached to a specific user.

When a user logs in to your app, call setUserProfile to identify them to Pyze. Any events that happen after they are identified, will be attributed to this user. You should only call this method once upon the initial login of a session.

You can optionally include profile attributes.

Pyze built-in profile attributes get special handling in the pyze UI, and we will attempt to discern the data type for custom attributes based on the data recieved. There is no difference between the built-in attributes and custom ones outside of formatting applied.

//Create Pyze Profile Attributes object
var pyzeProfileAttributes = {
	email_id: "xyz@abc.com",
	date_of_birth: "1984-06-01",
	first_name: "John",
	last_name: "Jacobs",
};
//Create Custom Profile Attributes object
var customProfileAttributes = {
	age: 29,
	pincode: "23200",
	city: "XYZ",
};
//Call the setUserProfile API
PyzeIdentity.setUserProfile(userId, pyzeProfileAttributes, customProfileAttributes);

Pyze profile attributes

Pyze User Profile Field Name Data Type/Description
background (string) User background, biography or historical data
country (string) Country codes must be sent in the ISO-3166-1 alpha-2 standard.
current_location (object) Format: {“longitude”: -33.991894, “latitude”: 25.243732}
date_of_first_use (date at which the user first used the app) String in ISO 8601 format or in yyyy-MM-dd’T’HH:mm:ss.SSSZ format.
date_of_last_use (date at which the user last used the app) String in ISO 8601 format or in yyyy-MM-dd’T’HH:mm:ss.SSSZ format.
date_of_birth (date of birth) String in format “YYYY-MM-DD”, example: 1984-06-01.
email_id (string) Email Id
email_subscribe (string) Acceptable values are “opt_in” (explicit approval to receive email messages), “opt_out” (explicit denial to email messages), and “subscribed” (neither opted in nor out).
email_hard_bounced Automatically updated when a hard bounce occurs (true or false)
email_spam_reported Automatically updated when a user marks your email as spam, via the ISP (true or false)
facebook_id facebook ID
first_name (string) User’s First name
gender (string) “M”, “F”, “O” (other), “N” (not applicable), “P” (prefer not to say) or “U” (unknown).
home_city (string) User’s Home City
image_url (string) URL of image to be associated with the user
language (string) Require language to be sent in the ISO-639-1 standard.
last_name (string) User’s Last Name
marked_email_as_spam_at (string) Date at which the user’s email was marked as spam. Must be in ISO 8601 format or in yyyy-MM-dd’T’HH:mm:ss.SSSZ format.
phone (string) Phone number
push_subscribe (string) Available values are “opted_in” (explicitly registered to receive push messages), “unsubscribed” (explicitly opted out of push messages), and “subscribed” (neither opted in nor out).
push_tokens Array of objects with app_id and token string. You may optionally provide a device_id for the device this token is associated with, e.g., [{“app_id”: App Identifier, “token”: “abcd”, “device_id”: “optional_field_value”}]. If a device_id is not provided, one will be randomly generated.
time_zone (string) Time Zone’s must be sent as per IANA Time Zone Database (e.g., “America/New_York” or “Eastern Time (US & Canada)”). Only valid values will be respected.
twitter_id Twitter ID

Updating an existing user Profile

To update user profile attributes which are already set, use the following api.

Note : Do not call this api before calling setUserProfile.

//Create Pyze Profile Attributes object
var pyzeProfileAttributes = {
	email_id: "xyz2@abc.com",
	date_of_birth: "1984-07-01",
	first_name: "John M",
	last_name: "Jacobs",
};
//Create Custom Profile Attributes object
var customProfileAttributes = {
	age: 29,
	pincode: "232001",
	city: "XYZ2",
};
//Call the updateUserProfileAttributes API
PyzeIdentity.updateUserProfile(pyzeProfileAttributes, customProfileAttributes);

Logging out a user

Call this api when a user logs out. Event sent after this call will have no identity attached, and will be attributed to an anonymous user.

PyzeIdentity.resetUserProfile();

User Privacy

Pyze provides APIs to allow end-users to Opt out of Data Collection and also instruct the Pyze system to forget a user’s data.

setUserOptOut

Allows end-users to opt out from data collection. Opt-out can be toggled true or false.

Pyze.setUserOptOut(true);

To resume user data collection set value to false

deleteUser

Allows end-users to opt out from data collection and delete the user in the Pyze system. We recommend you confirm this action as once a user is deleted, this cannot be undone.

Pyze.deleteUser(true);

Configure Pyze agent to track clipboard data

This section allow Pyze to track additional case data from clipboard. The steps for configuring additional clipboard information for Pyze to track are listed below.

Identify the data from the clipboard

  • Open the clipboard for any case and identify the information to track.
  • This information has to be simple and non-nested data structure (Ex: String, Number etc)
  • Copy the indentified attribute key.

Configure the Pyze agent

Once the data is identified, Open Pyze Web Analytics component and provide the attribute name by following the steps below.

  • Go to Dev Studio -> Configure -> User Interface -> Web Analytics as shown in the image below
  • Click on the Settings icon and go to App Data tab
  • Click on Add Item
  • Provide appropriete name for the clipboard attribute under Name section.
  • Provide the attribute key in the pyWorkPage.ATTRIBUTE_NAME format as shown in the image below.
  • Finally, click on Submit to save the changes.

Controlling Which Users Have Pyze Enabled

The Pyze Pega Component has four operating modes:

  • Enabled for all users
  • Selectively enabled based on a clipboad variable
  • Selectively enabled based on access groups
  • And disabled for all users.

Enabled for All Users

To enabled the Pyze Pega Component for all users:

Open Dynamic System Settings from Records -> SysAdmin menu and set EnablePyzeByRole to false

By default, the Pyze Pega Component is enabled for all users.

Selectively Enabled Based on a clipboard variable

To selectively enable based on a clipboard variable:

Open Dynamic System Settings from Records -> SysAdmin menu and set EnablePyzeByRole to true

  • Identify a key from the pyWorkPage Clipboard variable to be configured
  • Update PyzeWhitelistKey from Dynamic System Settings with the key identified.
  • Identify possible values for the key idenfied to be whitelisted.
  • Update PyzeWhitelistValues of the Dynamic System Settings field with values separated by commas.

Once configured, Pyze will be enabled only on pages where the configured clipboard key and one of the value are present.

Selectively Enabled Based on Access Groups

To selectively enable based on role or access group:

Open Dynamic System Settings from Records -> SysAdmin menu and set EnablePyzeByRole to true

When EnablePyzeByRole is set to true only those users in access groups with the PyzePegaRole:EnablePyze role will have Pyze enabled.

To enable Pyze for a specific group:

Add the role PyzePegaRole:EnablePyze to the desired access group.

Note: To view your current user access group select the user menu on the bottom left corner and go to the “Access group” option.

Disabled for All Users

Go to Configure -> User Interface -> Web Analytics and uncheck the Use web analytics flag on the Pyze component.

:warning ** Make sure to remove all the roles from the user access groups in case you decide to remove the Pyze component from the application. **

Remove Pyze component and the RuleSets

Overview

  1. Remove the component dependencies from the application

    a. Remove components from the application definition

    b. Remove any roles added to the application access group

  2. Unlock the component and ruleset

  3. From the ruleset wizard, find and delete the PyzeIntegRS ruleset.

    a. Delete both the versions(01-01-01)

  4. Delete the component itself

  5. Finally install the new package

Detailed instructions

Step 1

a. Delete both the Pega Web Analytics and the Pyze Component from application from the applicaiton definition page. (Application -> Configure)

Step 2

a. Unlock the component and its rulesets. The component and its ruleset should look as shown below after unlocking.

Step 3

a. Goto System -> Refactor -> RuleSets as shown below

b. Select the Delete a RuleSet option.

c. From the ruleset wizard, search and delete the PyzeIntegRS ruleset.

d. You should see a success message as shown below.

Step 4

Delete the component as shown below and save.

Step 5

Finally relogin and reinstall the component.

API Reference

Full API reference available here

Last modified 2024-07-10