Iframe integration guide
Security
When enabling communication between iframe and parent window, security considerations are crucial. To prevent vulnerabilities such as cross-site scripting (XSS) and ensure the safety of the app and its users, the App Center Team has put together a Security requirements guide. Your app must adhere to these requirements. This will also help you speed up security checks.
Navigation
To let you manage the state of the parent window, App Center offers dedicated JS API methods. They ensure seamless communication between the iframe and its parent window and help you enhance the overall user experience.
These JS API methods let you create effortless navigation by controlling the URL, search parameters, and navigation history.
To learn more, refer to the Search parameters section.
Authentication
Authentication in the Partner App within an iframe works using a JWT. This token is provided by Semrush during page load and updates, letting you verify and manage user sessions in your app. This means that you don't need to create your own authentication system within your app. The token contains information about the user's purchases.
The initial token has a 5-minute expiration period. When the token expires, you need to request a new token using the getAccessToken JS API method.
You must avoid handling requests with expired JWTs.
To do that, check the JWT expiration field by calling the SM.client('getAccessToken') method before each request.
If the user is logged out, the method returns a 403 error with USER_UNAUTHORIZED: Bad response text.
This practice enhances security and prevents authentication key leakage on the user's side.
Login modal pop-up
When you identify that the user is unauthorized, call the
SM.client('showLoginModal')
method to open a pop-up window prompting the user to log back in.
The user can log in using this window, and they will be redirected back to the
current page (same URL with the same query parameters).
The user can also close the pop-up window and return to the app.
To summarize, your app needs to display the pop-up for every
SM.client('getAccessToken')
call that returns a 403 response with USER_UNAUTHORIZED: Bad response message.
Responsiveness
The Semrush page containing the iframe supports responsive design. However, App Center doesn't require your app to be responsive. If your app adapts to screen width, it will continue to do so within the iframe.
By default, the iframe takes up the full width of the browser's workspace and almost the entire height, except for the Semrush panel and a small footer.
Modal windows
All Semrush App Center modal windows called through the SDK open outside the iframe and are automatically centered on the screen. Apps can't modify or customize them in any way.
Your app's modal windows must be displayed inside the iframe and can't overlay the App Center header and footer.
Modal windows within the iframe must not collect user data. Links to external and partner resources within the iframe are prohibited.
Local development
You can create a development app with the iframe URL set to either http://localhost:port or http://127.0.0.1:port.
This lets you run the app in debug mode on your local machine within the Semrush infrastructure.
The SDK won't work outside the iframe.
The App Center doesn't offer the option to run the working environment locally without access to the Internet and the Semrush infrastructure.
Browser API
Integrating with the App Center doesn't restrict you from using any browser capabilities such as accessing the microphone, camera, geolocation, and others. You can gain access to these features by making a request to your Account Manager.
Navigating through links in iframe
If your app supports client routing, you can use code similar to this React/TypeScript example to open your app links in the same tab without reloading the page.
import { ReactNode, FC } from "react";
import { useNavigate } from "react-router-dom";
const appRootPath = "https://semrush.com/app/your-app";
interface Props {
to: string;
children?: ReactNode;
}
const InternalLink: FC<Props> = ({ to = "", children }) => {
const navigate = useNavigate();
return (
<a
onClick={(event) => {
event.preventDefault();
navigate(to);
}}
href={`${appRootPath}${to}`}
>
{children}
</a>
);
};Usage:
<InternalLink to="/about">
Will open in the same tab without page reload
</InternalLink>
<a href={`${appRootPath}/about`} target="_blank" rel="noreferrer">
Will open in a new tab with page reload
</a>
<a href={`https://example.com`} target="_blank" rel="noreferrer">
External link that will open in a new tab
</a>If your app doesn't use client routing or npm, you can set a base tag
in the HTML <head> element:
<base href="https://semrush.com/app/your-app/" target="_parent">and use relative links in your app:
<a href="about" target="_blank">Will open in a new tab</a>
<a href="about" target="_parent">Will open in the same tab</a>Redirects inside iframe
By default, an iframe will block all attempts to open a URL from another domain inside it.
This includes redirects to your subdomains inside an iframe.
Only the domain that's part of your app's iframe url isn't blocked.
This is enforced on the App Center side using the Content-Security-Policy header.
Not to be confused with Content-Security-Policy from the application side.
This is an example of how your links will act inside an iframe:
<!-- Given that your iframe URL is https://semrush.example.com:8080/ -->
<a href="https://semrush.example.com:8080/about">Will redirect iframe to this URL</a>
<a href="https://semrush.example.com/about">Will be blocked: wrong port</a>
<a href="http://semrush.example.com:8080/about">Will be blocked: downgrade to HTTP (upgrade to HTTPS is allowed)</a>
<a href="https://example.com:8080/about">Will be blocked: wrong domain</a>
<a href="https://othersite.com/">Will be blocked: wrong domain</a>If you need to open some URLs specified in the example in your app, contact your Account Manager. They can manually allow certain domains for you.
Search parameters
Search parameters play a crucial role in enhancing the user experience by letting you preserve your app's state, including filters, sorting preferences, and page settings. Additionally, they empower users to interact with links, such as opening links from email reports or sharing them with others.
However, note that browser security restricts pages loaded in iframes from accessing objects and methods in the parent window if they originate from different domains (or subdomains). To overcome this limitation, the App Center Team has developed JavaScript API methods that let you modify the URL of the parent window, including its search parameters.
Before you start
Before you implement search parameters in your app, the App Center Team needs to conduct a security validation of the parameters you intend to configure. To get started, prepare a list of the desired parameters and share it with your Account Manager.
This list needs to include the following information:
- Parameter Key:
- May contain Latin letters (uppercase or lowercase), numbers (0-9), underscores, and dashes.
The key is validated against this regular expression:
^[0-9A-Za-z_-]+$. - As commas (,) aren't permitted, to include multiple parameters, separate them with ampersands (&).
For example:
?param=value1¶m=value2¶m=value3.
- May contain Latin letters (uppercase or lowercase), numbers (0-9), underscores, and dashes.
The key is validated against this regular expression:
- Parameter Value:
- The value must comply with this regular expression:
^[0-9A-Za-z_:./-]+$.
- The value must comply with this regular expression:
- Parameter Description:
- Describe the intended use of each parameter and the context in which they're employed.
For instance, if the parameter is
id, explain what thisidrepresents and what it's used for.
- Describe the intended use of each parameter and the context in which they're employed.
For instance, if the parameter is
For security reasons, URL parameters must not contain any personal, confidential, or other sensitive information.
Once the validation is completed, the App Center Team will add these parameters to the list of approved parameters for your app and inform you of this update.
Work with search parameters inside iframe
When your parameters are approved, you can use them in the following cases:
Case 1: Read parameters on initial load
During the initial loading of your app, to customize how your app renders, extract the complete URL,
including all search parameters, from the url field of the access token.
For more information about this process, refer to the JWT reference.
Case 2: Read parameters in app
To obtain the current state of the address bar—including the search parameters—subscribe to the onUrlPop method.
Case 3: Set parameters in address bar
To display search parameters in the address bar, pass them to the pushUrl and replaceUrl methods.
Case 4: Preserve page state in browser history
Preserving a page state in browser history lets users return to a specific page within a single session in your app by using the browser's Back option.
To let users do that, pass an object in the options argument with the property state to either
the pushUrl or replaceUrl method.
It will be saved with the history entry and passed to onUrlPop.
FAQ
Can I choose not to configure Content-Security-Policy for my app?
No, this is a security requirement.
An App Center app must open only in an iframe with the jwt GET parameter in the semrush.com domain.
Can multiple URLs/domains be used in iframe?
By default, an iframe can be redirected to any URL on the same domain (without subdomains). To open URLs from another domain inside the iframe, contact your Account Manager.
Can I develop my app outside iframe?
Yes, but then the App Center JS SDK won't work since it doesn't have a mode without a connection to the Semrush API.
If I use JS SDK, should I pass Semrush address or JWT in pushUrl?
Only pass the relative path—that is, instead of https://semrush.com/app/some-app/new-path, pass only /new-path/.
How do I know if user logged out from Semrush?
The getAccessToken method will return an error.
Can I increase minimum width of iframe for my app?
No, you can't modify the layout.
In test app, should feedback modal and email subscription pop-up appear every time I trigger them?
Yes, this is the intended behavior for the test app, designed to make testing these windows easier. For the Production app, there will be restrictions on when these pop-ups appear, depending on user actions. If the user gives their consent to receive notifications, the modal window will no longer be displayed to them. For users who close the window, this modal will reappear only after a week. For users who decline notifications, the modal will reappear after a month if you invoke it again.