Auto Frame Install & Sync

Some applications are composed of various frames using the iframe tag. For Pendo to collect analytics and display guides in each frame, the agent needs to be installed, usually using the snippet, into each frame. If guides are expected to cross frames or be coordinated across the frames, intialize the agent using the same apiKey and metadata for the visitor and account.

Introduced in Pendo Agent version 2.141.1, there are new options to have the agent automatically install and initialize in child frames that have the same origin as the parent frame. Additionally, any changes to the identity or metadata of the visitor can be synced across the frames. This was created to support the common scenario where a customer has multiple frames in their application but all frames have the same origin and same visitor information.

With this change you would only need to add the snippet to the top frame of your application and if you change metadata or identity of the visitor you would only need to do that in any one of the frames for it to appear in all of them.

How to enable for your installation

These new features are enabled in your installation through a couple of new configuration options passed to the pendo.initialize method. As shown in the "Developer's Guide To Installing the Pendo Snippet", the initialize method can take configuration options in addition to the normal visitor and account data. The new configuration options are as follows:

• autoFrameInstall - This takes a boolean value (true or false). Passing a true for this option will enable the new functionality to install and initialize the agent in any child frames that have the same origin. This will continue to work for any frames that are already on the page, are added later, or are reloaded. This will initialize the child frames using the original configuration options passed to initialize and the current visitor information.
• frameIdentitySync - This also takes a boolean value (true or false). Passing a true for this option will enable the new functionality to sync updates to the identity (visitor id or account id) or the metadata of a visitor. This works by propagating calls to pendo.identify or pendo.updateOptions to the other frames that are running the agent on the page. This is intended to be used with the auto frame install option above. NOTE Although the auto frame install will not work across cross-origin frames, the identity sync functionality can still work since initialized agents have their own communication channel.
• selfHostedAgentUrl - This takes a string value. This is to be used if you are self-hosting the agent and have a specific url you would like the child frames to also use. This is only needed if you do not have a <script> on the page with a src attribute that ends in pendo.js .

Limitations

There are a few limitations to the current implementation that you will find listed below:

• Cross-origin frames - Currently the auto install can only function for same-origin frames due to security limitations imposed by browsers with adding scripts. The identity sync portion will however still work for cross-origin frames as long as each frame is initialized separately.
• Setup in Pendo - The only way to use this feature currently is to add the configuration options to your initialize statement. We plan to add these as configurable options from the application settings at a later date.
• Ignoring Specific Frames - Currently this feature is designed to install the agent into any child frames that share origin. There might be some cases where you do not want the agent installed into certain frames but that is not yet supported.

Example

pendo.initialize({
    visitor:  {
        id:  "testuser@pendo",
    },
    apiKey:  "YOUR API KEY HERE",
    account:  {
        zipCode:  90210,
        id:  1,
        city:  "Beverly Hills",
        name:  "The Empire",
        tag:  null,
    },
    autoFrameInstall:  true,
    frameIdentitySync:  true,
    selfHostedAgentUrl:  'https://pendo.theempire.com/pendo-agent.js'
});