A replay rule is a modification to the session data during replay so that the replay looks as close as possible to what visitors experienced when they visited the application.
Configuring replay rules
You can control different aspects of session replay by changing the Replay rules text file. For example, you can control host and port remapping, custom page modification, and the fields in the session requests that are used for the URL and hostname.
You can use a replay rule to simulate steps in DOM capture session replay that are not supported by Tealeaf Web SDK.
To upload the Replay Rule file, go to the Company Settings tab and select the Replay Rules Upload file function.
Using the ResponseModify rule
You can use ResponseModify
rules for applying special modifications to the response to enhance replay.
The standard ResponseModify
rule includes the following parameters:
- url
- The URL pattern to be matched.
The URL must be a regular expression.
Validation: value field cannot be empty, it means all URLs will match this rule and will be ignored for the specific domain. If not empty, the value always Start with ‘
/
’ or‘.’
. It cannot contain empty spaces in between. - pattern
- Regex Pattern to be searched in Response Data. Accepts any valid Regular Expression.
- replacementString
- String value to replace matched pattern in Response. Can be empty.
- occurrences
- Whether to replace only the first occurrence (
First
) in the response or all occurrences (All
).
Example of ResponseModify rule
You can use ResponseModify
replay rules to correct any environmental issues that affect Replay fidelity. For this example, consider an application that has third party scripts and third party functions calls which might not be required during Replay. In such cases you can write some Response Modify rules to make Replay work properly.
Figure 1. Sample syntax for ResponseModify rule
<ResponseModify id="9" url="/TLAsForRulesEditor/ResponseModRule/index\.html"
pattern="displayError\(\);" replacementString="" occurrences="first" reqVar="" reqVarValue=""/>
For native sessions, the name of HostProfile will be the value of appKey
, and url of the replay rule will be screen name. For example:
Figure 2.
Sample syntax for ResponseModify replay rule for native session
<HostProfile name="fc56983a32ec44029c3fc98a80c1f347">
<ResponseModify url="c3" pattern="test"
replacementString="mytest" occurrences="first" />
</HostProfile>
where "fc56983a32ec44029c3fc98a80c1f347
" is appKey value, and "c3
" is screen name For webview in hybrid sessions, when the webview points to local file, the name of HostProfile will be the value of appKey
. For example:
Figure 3. Sample syntax for ResponseModify replay rule for hybrid session
<HostProfile name="93b07040e94f4d979ccded272b3a15c1">
<ResponseModify url="/android_asset/www/mobile_domcap/unresponsiveGestures.html" pattern="Button"
replacementString="MyButton" occurrences="first" />
</HostProfile>
An enhancement to ResponseModify rule addresses some inherent limitations.
Enhancement to the ResponseModify rule
An enhancement to the ResponseModify
allows the rule to modify searched pattern strings dynamically, by dropping, adding (prefix, suffix etc) or modifying parameters in between the searched pattern string.
When you configure the rule to modify searched pattern strings dynamically, the rule:
- Searches for a subPattern in the list of the match string.
- Replaces the matching elements and subPattern dynamically with a replacement string.
Applying the enhancement
To apply the enhanced ResponseModify
rule, add and configure the subPattern parameter to the rule.
As an example, here is the ResponseModify
rule without the subPattern parameter:
Figure 1. ResponseModify rule without the enhancement
<ResponseModify url=".*" pattern="<input type="text".*?
value="\S+".*?style="display: none;">"
replacement="<input type="text" value="abc"
style="display:block"> occurrences="all" id="7" />
For the syntax shown in the previous example, the rule searches for all input elements that have a value set and also style="display:none:
in the response (this can result in an increase processing overhead). Because you might want to modify just the style attribute, the replacement string is always static, irrespective of the fact that the searched string might contain other class attributes that might need to be retained.
Here is an example of the rule with the enhancement applied:
Figure 2. ResponseModify rule with the enhancement
<ResponseModify url=".*" pattern="<input type="text".*?
value="\S+".*?style="display: none;">"
subPattern="style="display: none;""
replacement="style="display: block;"" occurrences="all" id="7" />
In the previous example, the subPattern parameter contains the string that is to be modified within the pattern. The modification / modified string is part of the replacement string. The rule looks for the all the input elements that match the pattern, looks for the subPattern in the list of the match string and replaces them dynamically with the replacement string.
To simplify dropping any string in the searched pattern, apply the rule as follows:
<ResponseModify url=".*" pattern="<input type="text".*?
value="\S+".*?style="display: none;">"
subPattern="style="display: none;"" replacement="" occurrences="all" id="7" />
Adding a prefix and suffix is easier by searching a small portion of the text using subPattern and then modifying the searched subPattern within the replacement for the required operation.
Enhanced ResponseModify rule processing is enabled only when the subPattern parameter is set, else the rule works as originally intended.
Using the UIElementCustomHighlight replay rule
For selected UI Events, you can use the UIElementCustomHighlight
replay rule to run a custom JavaScript™ during replay.
You can use the UIElementCustomHighlight
rule for debugging or alerting, when specific user actions or values are displayed in a session. The UIElementCustomHighlight
replay rule includes the following parameters:
- url
- The URL pattern to be applied by the rule.
- elementId
- The element ID is pre-populated with the unique identifier for the selected event through element ID or XPath. You can modify the element ID field to use a regular expression, if needed, for matching multiple elements.
- js
- Any custom JavaScript that can be executed on the page to manipulate the page. The JavaScript is executed in the
onload
event.
Figure 1. Sample syntax for UIElementCustomHighlight replay rule
<UIElementCustomHighlight url="/path/to/your/page"
elementId="[["hotelSearch"],["DIV",0],["DIV",0],["SPAN",0],
["A",0]]" js="alert("ha gotcha!")">
For native sessions, the name of HostProfile is the value of appKey
, and the URL of the replay rule is the screen name. For example:
Figure 2. Sample syntax for UIElementCustomHighlight replay rule for native sessions
<HostProfile name="fc56983a32ec44029c3fc98a80c1f347">
<UIElementCustomHighlight url="c3" elementId=".*" js="alert('this is a test');" />
</HostProfile>
where fc56983a32ec44029c3fc98a80c1f347
is the appKey value and c3
is the screen name.
For webview in hybrid sessions, when the webview points to local file, the name of HostProfile is the value of appKey
. For example:
Figure 3.
Sample syntax for UIElementCustomHighlight replay rule for webview in hybrid sessions
<HostProfile name="93b07040e94f4d979ccded272b3a15c1">
<UIElementCustomHighlight url="/android_asset/www/mobile_domcap/unresponsiveGestures.htm" elementId=".*" js="alert('this is a test');" />
</HostProfile
Native / hybrid sessions are like web sessions, except the name of HostProfile is the value of the appKey
, and the URL of the replay rule is the screen name.
Displaying mobile gesture events in session replay with the SimulateUIEvents replay rule
To support mobile web gestures in session replay, you must configure and implement the SimulateUIEvents
replay rule. The SimulateUIEvents
replay rule enables the display of mobile gesture events in the navigation pane of session replay.
The following example shows how to configure the replay rule so that mobile gesture events are displayed in the session replay navigation pane:
<HostProfile name="hostname" >
<SimulateUIEvents id="14" value=".*"
uiEvents="gestures" />
</HostProfile>
For information about configuring gestures in native applications, see the Tealeaf UI Capture documentation.
Using the SimulateUIEvents replay rule to enable DOM Capture session replay UI events
You can use the SimulateUIEvents
replay rule to enable DOM Capture session replay UI events not currently supported by Tealeaf UIC.
When the Replay server sees the rule, it simulates the requested UI events on top of the last captured DOM (ceiling).
The DOM capture replay feature has always relied on the DOM being captured for a given UI event, in order to replay that UI event. This approach guarantees that replay is never compromised by an unexpected DOM change. Processing DOM capture and replay in this manner requires more storage, as well as more bandwidth to transmit data to the server. It also requires UIC to support DOM Capture for each type of UI event. Because Tealeaf UIC supports Type 2 (load/unload step) and Type 4 (click/change step) messages only, some UI events are excluded from DOM capture session replay. The SimulateUIEvents
addresses this limitation, while at the same time keeping replay reliable.
When you configure the SimulateUIEvents
replay rule, you specify the type of UI event (for example, click
, change,
gesture
, scroll
, or resize
) to simulate during replay. You also specify the page on which the Replay rule is applied.
Note: There are scenarios for which the SimulateUIEvents
Replay rule does not work. For example, the rule does not work if there are significant changes to the underlying DOM between last captured DOM, and the actual DOM when this UI step took place. Additionally, JavaScript (which requires a renderer) is not invoked for the SimulateUIEvents
Replay rule.
As a best practice, use the SimulateUIEvents
Replay rule for specific pages and UI Events only. The SimulateUIEvents
Replay rule is not intended to be used for all UI Events or pages at once (for example, setting value =".*.
). Customers and Acoustic Tealeaf Professional services representatives should work together to identify those pages and UI Events on which to apply the SimulateUIEvents
Replay rule.
Example of the SimulateUIEvents replay rule
In the following example of the SimulateUIEvents
replay rule, the /path/to/somepage would include references to a specific page on which to apply the rule.
<HostProfile name="www.abc.com" id="11">
<SimulateUIEvents id="14" value="/path/to/somepage"
uiEvents="resize,valuechange,click,mouseup,scroll, gestures" />
</HostProfile>
The Replay server checks an enumerator before the UI Events are enabled and when there is a missing DOM. The enumerator values are:
click
change
scroll
mouseup
mousedown
gestures
hover
resize
touchend
focusout
Supporting scroll events in replay
You can use the SimulateUIEvents
replay rule to ensure that scroll events are displayed in replay.
Replaying scroll events works for web (desktop) and mobile-web applications only.
Only those scroll events that occur within the main window area are displayed in replay. Scroll events that occur in frames that are nested within a page (iFrames), are not supported in replay.
To simulate scroll events in replay, add the following rule:
Figure 1. Replay rule configuration for scroll events
<HostProfile name="www.abc.com">
SimulateUIEvents value=".*" uiEvents="scroll"/>
</HostProfile>
In this example, change the host name to the host name of the web site or mobile-web application that you are replaying.
Once scrolls are enabled with this rule, the scroll gestures engaged in by the visitors are displayed in the navigation list.
Using the RemapURL replay rule to remap the URL of content that is external to the captured pages of a session
You can use the RemapURL
rule to remap the URL of content that is external to the captured pages of a session, to a new destination.
Remapping URLs is used in situations where the external content is not available or accessible from the original site, and a copy is made on another server, to which you can remap the URL.
The standard RemapURL
rule includes the following parameters:
- parameter_1
- The parameter_1 ….
- parameter_2
- The parameter_2 ….
- parameter_3
- The parameter_2 ….
- ignoreFromCRS
- When set to
TRUE
URL remapping in Replay and the LTSServer is ignored, when retrieving assets from CMS.A non-remapped URL is used to fetch from CMS, while a remapped URL is used always for a remote host, with the presence of rule with parameter.
Example of RemapURL rule
Figure 1. Sample syntax for RemapURL rule
<RemapURL urlPatterrn="https://w19dvhiis005\.ldstatdv.\net:7453/.*"remapFormat="https://secure.sstate.co.nz%5 enabled="1" id="31"/>
Using the GetStaticAssets replay rule to retrieve static resources from a remote host
You can use the GetStaticAssets
replay rule to retrieve static resources from a remote host or from a Content Management System (CMS). The replay server is programmed to fetch static resources from the original URL. Replay problems can happen if your IT department does not host older versions of the static resources and you try to replay sessions that rely on earlier versions of the static resources.
To avoid such problems:
- Use the Find Static Package feature to locate and save static resources to a CMS.
- Configure ReplayServerProfile.xml with the
GetStaticAssets
replay rule.During web replay, the rule fetches the static resources from the CMS or remote host system based on the
GetStaticAssets
replay rule configuration.
The GetStaticAssets
replay rule includes the following parameters:
- name
- Specifies the system on which the static resources reside. The replay server has an enum that checks the name value (
enum sourceType {REMOTEHOSTFIRST , CMSONLY, CMSFIRST}
). If an invalid name is entered, the replay server gets the static content from the original URL.The name denotes the priority of how the resources are fetched:
- CMSFIRST
- CMSONLY
- REMOTEHOSTFIRST
- sessionDateRange
- Valid formats are -MM/DD/YYYY or MM/DD/YYYY-MM/DD/YYYY or MM/DD/YYYY-. The replay server checks to see if the date for the session falls within the range specified in the
sessionDateRange
parameter.If an end date is not included, the replay server understands that the end date is later than the date that is set in the rule. For example, if the session date is
10/28/2016
and the value set in thesessionDateRange
parameter is10/27/2016-
, then the condition matches.If a start date is not included, the replay server understands that the start date is earlier than the date that is specified. For example, if the session date is
10/28/2016
and the value set in thesessionDateRange
parameter is-10/27/2016
, then the condition fails. - urlList
- The urlList specifies the resources that need to be fetched. The replay server gets the resource from the value specified in the rule, which represents a regular expression where
.*
represents all resources.The urlList can be separated by commas to include multiple specific resources.
Note: If the session date matches or falls within all or multiple date ranges that are configured in the GetStaticAssets
rule, the resource fetched is always from the last matching condition.
Note: The Session Date range should match exactly what was entered in the Tag 2 field when you use the Find Static Package function, because CMS interprets these tags as strings and they should not be modified.
Using GetStaticAssets
to check CMS first for a given session date range else fetch from original URL
In the following example, the replay server tries to fetch all static assets from CMS for the given session date range. If these assets are not available, it then tries to fetch all assets from the original URL, irrespective of the SessionDateRange
.
<GetStaticAssets id="12" name="CMSFIRST" SessionDateRange="10/01/2016-10/30/2016" urlList=".*" />
Using GetStaticAssets
to check external URL first for given date range else fetch from CMS
In the following example, the replay server tries to fetch all static assets from remote host for the given session date range. If these assets are not available, it then tries to fetch all assets from CMS for the given SessionDateRange
.
<GetStaticAssets id="12" name="REMOTEHOSTFIRST" SessionDateRange="10/01/2016-10/30/2016" urlList=".*" />
Using GetStaticAssets
to check CMS only
In the following example, the Replay server tries to fetch all static assets from CMS for only the given SessionDateRange
.
<GetStaticAssets id="12" name="CMSONLY" SessionDateRange="10/01/2016-10/30/2016"
urlList=".*" />
Using GetStaticAssets
to check CMS first for two specific URLs within the given date range else fetch from original URL
In the following example, the replay server tries to fetch the two specified static assets from CMS for the given session date range. If these assets are not available, it then tries to fetch these two assets, and other assets that are needed for replay, from original URL, irrespective of the SessionDateRange
.
<GetStaticAssets id="12" name="CMSFIRST" SessionDateRange="10/01/2016-10/30/2016"
urlList="https://www.abc.com/logos/doodles/2016/abc.gif,
https://www.abc.com/css/doodles/2016/xyz.css " />
You decide to upload all Static resources to CMS and use it to replay sessions from then (Ex - 10/01/2016)
In the following example, the replay rule configurations would look something like this:
<GetStaticAssets id="12" name="CMSONLY" SessionDateRange="10/01/2016-" urlList=".* " />
After an interval of time (for example a month later 11/01/2016
), a new version of the same resources is uploaded.
The replay rule would look something like this:
<GetStaticAssets id="12" name="CMSONLY" SessionDateRange="10/01/2016-" urlList=".* " />
<GetStaticAssets id="12" name="CMSONLY" SessionDateRange="11/01/2016-" urlList=".* " />
Note: When there are multiple matching conditions, the last matching condition is always considered.
The previous example uses two rules because you might also have different URLs to fetch from different uploads, which can be configured in urlList.
You decide to upload static content to CMS to replay sessions on a single / specific day
In the following example, the replay server tries to fetch all static assets from CMS for the given session date range. If these assets are not available, it then tries to fetch all assets from original URL, irrespective of the SessionDateRange
.
<GetStaticAssets id="12" name="CMSONLY" SessionDateRange="10/01/2016-10/01/2016" urlList=".*" />
In the previous example, SessionDateRange
is interpreted as 10/01/2016 00:00:00 - 10/01/2016 23:59:59.
Use the AddQueryParameters replay rule to keep some, or all the parameters in a URL
When retrieving static content, the Replay server removes the query parameters from the URL automatically.
For example, when retrieving static content from the following URL
https://abc.com/logo.png?p1=value1&p2=value2&p3=value3
the Replay server (by default) removes the arguments p1=value1&p2=value2&p3=value3
from the URL. The resulting URL is:
https://abc.com/logo.png
If you want to keep some, or all the parameters in the URL, you can use the AddQueryParameters
rule.
All replay rules are within <HostProfile>
section in the rule xml file. For native sessions, the value for the <HostProfile>
name is the appKey
, and the URL of the replay rule is the screen name
.
The AddQueryParameters
replay rule includes the following parameters:
- AddQueryParameters id
- The identification number for the rule in the Rule profile file.
- urlPattern
- The regex pattern to match the URL.
Accepts ‘
?
’, ‘*
’, ‘[
‘, and ‘]
’ characters. This is not a Regex match, it is just a pattern match.Validation: value field can be Empty, it means all URLs will match this rule and will be ignored for the specific domain. If not empty, the value always Start with ‘
/
’ or ‘*
’. It cannot contain empty spaces in between. - queryParameters
- A list of the parameters that were removed by the Replay server when retrieving static content, and that you want to add back into the URL
Figure 1. Sample syntax for AddQueryParameters replay rule
<HostProfile name="abc.com">
<AddQueryParameters id="12" urlPattern=".*" queryParameters="comma separated list of parameters" />
</HostProfile>
Using the URL https://abc.com/logo.png?p1=value1&p2=value2&p3=value3
as an example, if you wanted to add parameters P1 and P2 (but not parameter P3) back into the URL, configure the AddQueryParameters
replay rule as follows:
<HostProfile name="abc.com">
<AddQueryParameters id="12" urlPattern=".*" queryParameters="P1, P2"/>
</HostProfile>
To add all the parameters (P1, P2, and P3) back into the URL, leave queryParameters empty, as follows.
<HostProfile name="abc.com">
<AddQueryParameters id="12" urlPattern=".*" queryParameters="" />
</HostProfile>
If the queryParameters field is empty, the Replay server keeps all the parameters, and requests the static assets with the full URL.
Use the ExternFileModify replay rule to modify external files that are referenced in the response
You can configure ExternFileModify
rules to complete additional processing to external files that can interfere with replay.
You can use ExternFileModify
rules to modify external files that are referenced in the response.
In the following example, an external JavaScript™ file is modified to change the value of this.fadeDuration
from .8
to .001
, which causes the fade for the page to be much shorter.
<ExternalFileModify id="409"
url="/path/Details.js\?cache=.*"
pattern="this.fadeDuration = .8;"
replacementString="this.fadeDuration = .001;"
occurrences="all"/>