PX SDK Configuration Reference Guide

Tracking and Analytics

Configuration	Default Value	Description
autoTrack	TRUE	Automatic tracking, including clicks, page views, and lead events.
autoClickTrack	TRUE	Turns on automatic tracking of user clicks.
autoTrackPage	TRUE	Automatic tracking of page views.
trackPageTitles	FALSE	Enables page title tracking as part of engagement or analytics data.
autoTrackHash	FALSE	Enables automatic tracking of hash changes in URLs. Useful for single-page applications that use hash for navigation.
enableIdentifyFromIFrame	FALSE	Allows user identification from iframe tags. If false, identify calls in iframes are ignored.
clientSideEngagementTracking	FALSE	Tracks engagement views on the client side before they are confirmed by the server. Useful for performance monitoring.
maxEngagementCalls	1	Defines the maximum number of engagement fetch calls allowed after a command call. Use this to control how frequently engagements are fetched. By default, the SDK sends a fetch call for every command call. However, if multiple command calls occur close together, one fetch call may serve more than one command.
engagementCallDelay	750	Specifies the delay (in milliseconds) between a command call and the engagement fetch. If maxEngagementCalls is set to greater than 1, use this setting to define the delay between successive fetch calls.
badgeRefreshInterval	5	Defines the interval (in seconds) for refreshing the engagement badge information from the server.
keyboardTriggerClick	FALSE	Tracks click events triggered from keyboard interactions ( Space, Enter, on non-input elements) that helps improve accessibility. PX does not track input elements such as text fields or text areas, as keystrokes may not lead to a submission and could result in misleading event data.
evaluateEngRuleOnNavigation	FALSE	Determines if engagement rules should be re-evaluated during navigation if engagement is rendered on screen.
crossProductEngagement	FALSE	Enables displaying engagements across different products. Useful if you have a multiple-product subscription.
elementClickToPointer	FALSE	Uses pointer events in Guide engagements to detect interaction with the tooltip’s mapped element.
iframeModeEnabled	TRUE	Turns on support for tracking interactions inside iframes. Ideal for applications that use multiple IFrames and control all of them. Set to false if your application is running as a tenant IFrame under a different application .
sessionCookieTTL	1800000	Sets the expiration time for the apt.sid cookie in milliseconds.

Security and Privacy

Configuration	Default Value	Description
htmlSanitization	FALSE	Scans guide content for scripting or potentially risky elements. If a risk is detected, the guide is not displayed.
htmlSanitizationAllowedDomains	-	Defines exclusive domains allowed to host referenced content or links for engagements.
htmlSanitizationAllowedSchemes	['http:', 'https:', 'data:']	List of allowed URL schemes for href and src attributes in in-app content. By default, sanitization allows http:, https:, and data:.
sameSiteCookie	undefined	By default, the PX SDK sets the SameSite attribute to None or uses the browser’s default value. This configuration allows you to set a specific SameSite value (Lax, Strict, or None) for all cookies created by the SDK to control cross-site behavior. More Info
fullDomainCookie	FALSE	Tracks user sessions based on the application's top-level domain (for example, .mydomain.com). When set to true, the PX SDK stores cookies on the full domain. This is useful when different subdomains represent different products and should be tracked as separate users and sessions.
localStorageCookie	FALSE	By default, Gainsight PX SDK use cookies to store data in your browser. When enabled, Gainsight PX SDK stores data values such as apt.sid, apt.uid, and apt.token in local storage instead of browser cookies.
useSessionStorageEditorToken	FALSE	When set to false, the editor apt.token is stored in session storage instead of cookies.
useSessionStorageForRedirect	FALSE	By default, the SDK appends additional data as query parameters when redirecting in a guide engagement. When set to true, the SDK stores this data in session storage instead, thus preserving context.
strictProductVerification	FALSE	By default PX tracks users across products. This flag ensures that the product key in the apt.uid cookie matches the key in the SDK tag. If not, users are tracked anonymously until re-identified.
trustedOrigin	-	Restricts postMessage calls between iframes and the main window to only specific origin. In the main window config, this value must contain the origin (scheme, domain) of the iframe(s). In the iframe config, it must contain the origin of the top-level window. Example: trustedOrigin: "https://toplevel.example.com".
widgetNonce	undefined	Allows adding a nonce to the bot widget's script tag for CSP compliance.
cssNonce	undefined	Sets a nonce value on style tags for CSP compliance.
strictCSP	FALSE	Applies strict Content Security Policy (CSP) rules by preventing inline styles and using class names instead.
allowBlankSrc	FALSE	Allows tracking for iframes that have an empty src attribute.
engagementChecksumFileUrl	-	Specifies the path to a hosted checksum file that the SDK verifies before displaying in-product engagements. This is a strict security measure to lock engagement content. Any changes to a guide require updating the CDN checksum file for validation. The checksum is validated only on the production environment.
skipChecksumForEngagementIds	[]	List of engagement IDs for which checksum validation should be skipped.
enableKcSecureArticle	FALSE	Determines if KC Bot articles should load in an iframe.
usePOST	FALSE (unless the payload is too large for a GET)	Determines whether tracking calls use HTTP POST, by default, instead of GET. The PX SDK automatically uses POST when the data size is long.
enableFullStory	FALSE	Enables populating FullStory session on PX tracking activity.
allowCrossDomain	FALSE	Allows accepting iframe post messages from cross-domain sources. Use caution to avoid security risks.

Engagement and Guide Behavior

Configuration	Default Value	Description
guideAdvanceOnHover	FALSE	Determines whether guides advance when the user hovers over elements.
tooltipDynamicReposition	FALSE	Automatically reposition tooltips in real time if the intended position is off-screen, and a better position is available on-screen.
supportFixedPosition	FALSE	Inherits position:fixed for engagement step (tooltip or hotspot) if the target element or its ancestors already use position: fixed. Helps prevent positioning issues.
viewAlignedScroll	FALSE	Uses Gainsight PX’s internal scroll-to-element logic to handle edge cases that are not supported by native scrolling behavior.
enableModalBodyScroll	TRUE	By default, the SDK allows scrolling when an engagement is displayed with a modal. Set this to false to prevent scrolling during modal display.
scrollToArea	undefined	Sets the scroll alignment behavior when guide scroll the page to show the next tooltip. Accepted values are start, end, center, and nearest. More Info Sets the scroll alignment behavior when a guide engagement scrolls the page to display the next tooltip. Accepted values are start, end, center, and nearest.
dockMapper	FALSE	Set to true to activate docking functionality for Editor v1.
mapperResizeFullHeightElements	FALSE	Used for Editor v1 or Guide Linker to adjust height.
mapperResizeFullHeightBody	FALSE	Used for Editor v1 or Guide Linker for body resizing.
queryParamsInHash		Uses history.replaceState to update engagement redirect URLs with query parameters in the hash. Helps avoid full-page reloads.
elementAttributeWhitelist	[]	Specifies custom DOM element attributes that should be included in click tracking. Supports wildcards.
elementAttributeDenyMap	{}	Defines attributes that should not be tracked when recording click events. Can be set for specific element types. Example: { "button": ["value"], "select": ["value"] } prevents tracking value attributes for buttons and select elements.
kcAllowedFuncNames	[]	Specifies a list of allowed JavaScript function names that the bot can call when a link with a defined function is clicked. This acts as a security measure to restrict execution to approved functions only.
kcDisplayType	Default	Defines the default display configuration (floater or embedded) for the bot.
kcPositionType	injection	Specifies the positioning method (fixed, absolute, or injection) for the embedded bot.
overrideBotSearchContextUrl	undefined	Overrides the bot's search context URL. Can be used to proxy the traffic.
engagementExcludeUrl	[]	A list of URLs to exclude from engagement viewing and tracking. Supports wildcards.
excludeUrls	[]	List of URLs to be excluded by the SDK. The SDK will not perform any tracking or display engagements on these pages.
delayClickEventTime	2000	The delay time (in milliseconds) for client-side feature rule matching after a click. This applies only when UI Element Rule includes text.
engagementEditorV2AutoSave	FALSE	Enables automatic save functionality in Editor V2. Reduces risk of losing edits while working.

Proxying and Content Delivery

Configuration	Default Value	Description
contentProxyDomain	undefined	Specifies a proxy URL prefix for loading static content files used in the SDK, such as images or JavaScript assets. Should be configured together with espProxyDomain and storageProxyDomain to enable consistent content delivery through your proxy.
storageProxyDomain	undefined	The proxy overrides the domain so that static content is fetched from an alternate source instead of the Google Storage domain used by PX.
espProxyDomain	undefined	Overrides the prefix of the PX tracking server. To enable full proxy coverage, this should be configured along with contentProxyDomain and storageProxyDomain. The value can include the domain and part of the path. The PX SDK automatically appends /rte and the tracking endpoint suffix to the specified prefix.
cssFileEndpoint	undefined	Specifies a URL to load the style.css file via proxy. Typically unnecessary if contentProxyDomain is configured.
widgetFileEndpoint	undefined	Specifies a URL to load the aptrinsic-widget.js file via proxy. This file is used to render Knowledge Center Bot.
crossOriginStyle	FALSE	Loads the SDK's CSS with crossOrigin='anonymous' for CORS compliance. Useful for environments with strict CSP settings.

URL & Parameter Handling

Configuration	Default Value	Description
filterType	mask	Determines how URLs are filtered or masked in tracking. Mask: Replace tracked URL values with \[domain]/apt-masked-url Exclude: ignore the page completely.
filterUrls	[]	A list of URLs to be excluded from tracking or masked, depending on filterType. Supports wildcards. When mask is applied the value of URL path will be /apt-masked-url
nameParamFilterType	mask	Controls how URL parameters are filtered in tracking. mask: Replace parameter values with apt-masked Exclude: Ignore parameter and value from tracking data.
namedParamFilter	[]	A list of specific URL parameter names to exclude from tracking. Wildcards are not supported. If masked, the parameter value will be replaced with apt-masked.
stripSafeUrlProtocol	True	Determines whether to ignore the URL protocol when processing URLs. If set to true, URL matching fails if the protocol is different (for instance, http: versus https:).
maskUrlFunction	undefined	Custom function for masking URLs before they are sent in tracking events. Detailed Documentation
keepRuleUrlHash	FALSE	Preserves the hash fragment in product mapper rules.

Compatibility and Framework Support

Configuration	Default Value	Description
angularMutationObserver	FALSE	By default, the SDK uses the browser’s native MutationObserver implementation. Angular overrides this implementation but retains a reference to the original. When set to true, the SDK uses the native MutationObserver instead of Angular’s version to resolve conflicts.
angularAddEventListener	FALSE	The Angular framework overrides the default addEventListener and removeEventListener functions. By default, the SDK uses Angular’s custom implementation on the window object. When set to true, the SDK uses the original browser implementation retained by Angular.
framesetMode	FALSE	Enables compatibility mode for legacy applications using HTML framesets.
usesShadowDom	FALSE	Enables support for web components using Shadow DOM. Set to true if your application uses shadow DOM elements for guide rendering.

Operational and Miscellaneous

Configuration	Default Value	Description
enableTag	TRUE	Determines whether the PX tag is enabled. When set to false, no PX functionality is available in the application.
widgetEnabled	FALSE	Controls whether the onboarding widget is active.
requestTimeoutDefault	0	Default timeout (in ms) for all SDK requests. By default, the PX server defines the timeout.
requestTimeoutCritical	0	The timeout (in ms) specifically for config and identify requests.
badgeUseInterval	FALSE	Use a timed interval instead of a mutation observer to reposition badges.
badgeRepositionInterval	500	Specifies the interval (in milliseconds) at which the SDK validates the position of the element associated with the badge, if badgeUseInterval is set to true. The SDK validates whether the element has moved on the screen due to scrolling or removal.
multipleProductsPerDomain	TRUE	Enables tracking multiple products within the same domain.
badgesUseFixedPosition	FALSE	By default badges use absolute position. If set to true badges use position: fixed to maintain consistent placement during page scrolling.