Skip to main content


The options listed below pertain to core features and functionality of the Agent.

Available Options

additionalApiKeysWhen included, all analytics events will be sent to each of the api keys in the list (guide events are only sent to the primary api key). This will only function if there are no additionalApiKeys set on the configuration included in the downloaded Agent.[]string[]
annotateUrlA function that returns either an array of strings or an object to decorate the url for events. Deprecated: new usages to edit the url for events should use the location api.undefinedfunction
apiKeyA primary api key to send data to from the Agent. This will only function if there is no apiKey set on the configuration included in the downloaded Agent.undefinedstring
appAutoOrderingArray of api key strings to set app priority for auto display guides. Eligible guides will auto display sequentially in the order of api keys set here. Takes priority over leaderKey setting and default ordering.undefinedstring[]
autoFrameInstallIf set to true, the agent will try to install and initialize in all same-origin frames on the page. Read more about frame support.falseboolean
contentHostAn alternate url to load guide content from. This will be used to replace the standard google storage url for your subscription. Usually used for CNAME setups.undefinedstring
cookieDomainA unique domain to append to cookies that the Agent stores. If this is set, the Agent will not use local storage but will store all information as cookies using this domain. If not set, the browser will use the current domain when setting cookies. Note: The domain must match the domain of the JavaScript origin. Setting cookies to foreign domains will be silently ignored. Read more on MDN.undefinedstring
dataHostAn alternate url to use when transmitting event data. Usually used for CNAME setups.undefinedstring
disableCookiesAlthough the name refers to cookies, if set to true the Agent will not persist any data in local storage or cookies and will rely only on memory.falseboolean
disableFeedbackIf Feedback is setup for your subscription, this option can be used to selectively disable Feedback.falseboolean
disablePendoIf set to true the Agent will cancel out of initialization. This can be useful to disable the Agent with minimal code changes.falseboolean
disablePersistenceBy default, the Agent will store the most recently used visitor and account ids as well as historical metadata. These stored values will be used if the agent is initialized in the future without them. Setting this to true will mean the agent will not store these values but will only use what is provided or fall back to anonymous ids.falseboolean
forceAnonymousHaving identity persisted by default makes it so that a transition from using identified visitor ids to using anonymous visitor ids is challenging. Anyone that used your application with an identified visitor id would have that value persisted to storage and whenever they agent is initialized for them, that value would be read from storage treating them as the same identified visitor. When set true, this config option will only use persisted identity values if they are an anonymous id. It is meant to be used to smoothly make this transition to using anonymous ids while still retaining the benefit of consistent anonymous ids for visitors. This option will be ignored if you provide an identified visitorId to the initialize call.falseboolean
frameIdentitySyncBy default, the identity of a visitor in various iframes on a page are independent from each other. Setting this to true will instead have the Agent make sure all frames use the exact same visitor and account information. Read more about frame support.falseboolean
ignoreHashRoutingIf set to true, the Agent will strip url fragments from the url used for events (everything after a # symbol). Deprecated: new usages to edit the url for events should use the location api.falseboolean
initializeImmediatelyBy default, the Agent will wait until the document.readyState is set to "complete". Setting this to true will allow the Agent to initialize while the document is still loading.falseboolean
observeShadowRootsUse this setting when using preferMutationObserver with an application that has Shadow DOM elements. On page load, the Agent will run a full document scan for shadow roots and attach a MutationObserver to all results.falseboolean
leaderKeySpecify a preferred apiKey to lead the multi-apiKey iframe installations to make decisions about automatic guide display. In installations with more than 2 apiKeys, the leaderKey can be specified as a priority list (e.g. leaderKey: ['key1', 'key2', ...]). Either all frames must agree on the leaderKey setting, or only one frame should specify the leaderKey. If neither of these conditions are met, the default leader determination logic (top frame or earliest to join) will be used.[]string[]
localStorageOnlyIf set to true, the Agent will only persist data using local storage and memory.falseboolean
preferBroadcastChannelBy default, if there are multiple frames on the page that have the Agent installed, they will communicate using window.postMessage. If set to true the Agent will instead use the browser's Broadcast Channel API to communicate. This will only work when all frames use the same domain.falseboolean
preferMutationObserverBy default, the Agent will scan the page every 500ms to determine if any new badges or guides are eligible. To improve idle performance, this can be set to true and then the Agent will instead use a mutation observer and only check eligibility if the page content has changed.falseboolean
preventUnloadListenerBy default, the Agent adds an unload event listener to the page to make sure it sends events upon navigation. If set to true, the Agent will instead use the visibilitychange event listener and send events when the visibility is changing to "hidden".falseboolean
queryStringWhitelistAn array of strings or a function that returns an array of strings. The Agent will then strip any query string parameters from the url that are not found in the provided array. Deprecated: new usages to edit the url for events should use the location api.undefinedstring[] or function
sanitizeUrlA function that takes the current url and should return a new url to use instead. This can be used to remove sensitive data or alter it in any way. Deprecated: new usages to edit the url for events should use the location api.undefinedfunction
selfHostedAgentUrlMeant to be used with autoFrameInstall. If set, the Agent will use this as the url to download the Agent from in child frames. Read more about frame support.undefinedstring
sendEventsWithPostOnlyIf this option is set to true, event data will only be transmitted using requests of type POST instead of first trying to use GET requests. This can result in fewer requests being sent each time that event data is transmitted.falseboolean


visitor: {
name: "John Doe",
email: "",
role: "Viewer"
account: {
name: "Acme Co"
additionalApiKeys: [],
annotateUrl: () => { return []; },
appAutoOrdering: [],
autoFrameInstall: false,
contentHost: '',
cookieDomain: '',
dataHost: '',
disableCookies: false,
disablePendo: false,
disablePersistence: false,
frameIdentitySync: false,
ignoreHashRouting: false,
initializeImmediately: false,
leaderKey: [],
localStorageOnly: false,
observeShadowRoots: false,
preferBroadcastChannel: false,
preferMutationObserver: false,
preventUnloadListener: false,
queryStringWhitelist: [], // () => { return []; }
sanitizeUrl: (url) => { return url; },
selfHostedAgentUrl: '',
sendEventsWithPostOnly: false