OutSystems - Traditional

OutSystems Traditional Web Apps

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

Install

Download the plugin from the OutSystems forge

Import the Pyze component as a dependency inside the Traditional Web App as shown below.

Initialize

Find a common web-block that is present in all the screens, if not then create one invisible web-block and add to all screens.

Add & edit the preparation action of the web-block. Drag the ‘InitializePyze’ action inside the action flow as shown below.

Add the mandatory ‘pyzeAppKey’ obtained from https://growth.pyze.com and optional ‘dimensions’ if required as JSON string as shown above.

Dimensions are attributes that can be attached to all events within a session. This is useful to have a standard set of attributes that change over time, and is simply a helper to accomplish this goal.

Dimensions are any key-value pairs that you attach to the initialize call. Create an object, and modify the initialize call to include this object.

Custom Events

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

Event

To post custom event to Pyze, drag and drop ‘PostCustomEvent’ action in the action flow. Replace the ‘eventName’ attribute value with the desired event name.

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.

Drag ‘PostCustomEventWithAttribute’ action if you want to add attributes to your event as shown below. ‘attributes’ is a JSON string.

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.
  • postTimedEventWithAttributes - End the timer by referencing the same name and attaching any attributes as well. The time in milliseconds will automatically be attached to this event.

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.

  • You can use SetUserProfile action to set the user profile to Pyze. It accepts ‘userId’, ‘pyzeProfileAttributes’ and ‘customProfileAttributes’.

where userId is a unique user identifier string and ‘pyzeProfileAttributes’ are specific keys shown in the table below.

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

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.

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.

SetUserOptOut

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.

DeleteUser
Last modified 2022-10-06