Skip to main content
A selector can target an element inside an <iframe> — a lesson activity, an embedded editor, a part of your product served as a frame — as long as the frame is on the same origin as the page. Usertour looks for the selector on the page first, then in every frame it can read, nested frames included. Tooltips are positioned, and the target’s visibility judged, with the frame’s offset taken into account. Nothing changes in how you write the selector: #submit-answer finds the button whether it lives on the page or inside a frame. This applies wherever a selector is used — tooltip targets, launcher targets, and start rules or step triggers such as Element is present or Element is clicked. Banners are the exception. A banner placed relative to an element — Top of container element, Immediately before element and the like — is embedded only at an element of the page itself. If its selector matches only inside a frame, the banner is not shown.

​
Requirements

  • Same origin. The page and the frame’s document must share scheme, host and port. A frame on another origin is opaque to the browser, and so to Usertour: a selector inside it is reported as not found, exactly as if the element did not exist.
  • No sandbox without allow-same-origin. A sandboxed frame is treated as another origin unless its sandbox attribute includes allow-same-origin.
  • Install Usertour.js on the page only. Do not add the snippet inside the frame; the page’s Usertour.js reaches into the frame by itself.
Nested frames work as long as every frame on the way down meets these requirements. Origin is stricter than “the same website”. For a page at https://app.example.com/lessons/42:

​
Checking a frame

In the browser’s developer tools, select the <iframe> element that holds the content and look at two things: the address in its src next to the address of the page, and whether the tag carries a sandbox attribute. A developer can also ask the browser directly. In the page’s console, with a selector that matches the frame:
If a document comes back, the page can read the frame, and so can Usertour. If the answer is null, it cannot, and selectors will not reach inside.

​
Which match is used

When a selector matches more than one element, the page’s matches come first, then each frame’s in the order the frames appear on the page. The 1st / 2nd / 3rd… choice next to the selector counts through that combined list.
The element picker currently picks elements on the page itself, not inside a frame. For an element inside a frame, type its selector by hand. A dedicated attribute such as [data-tour="submit-answer"], agreed with your developers as described in Selecting Elements, is the easiest to read off your markup and the least likely to break.

​
When a frame cannot be read

What to do depends on who serves the frame’s content. Your team does. Serve it from the page’s own origin, and it qualifies. Content that lives on another subdomain today can usually be exposed under a path of the page’s domain, such as /activities/, by the same server or proxy that serves the page. Someone else does. A third-party tool embedded in your page stays out of reach. You can still guide users through it: attach the step to the <iframe> element itself, or use a step that is not attached to any element, explain what to do inside, and let users continue with a Next button.

​
When your app itself runs inside a frame

Some apps are embedded whole by another page — a portal, a shell around several products. Install Usertour.js in your app’s own page, the one inside the frame, as you would anywhere else. “The page” in this guide then means that page: selectors are resolved in it and in the frames below it, and tooltips are drawn inside it. Nothing is installed in the page that embeds your app.