To get started on developing your app, check out the sample app that uses all the features provided by the App Center API:
All browser requests, regardless of the entered URL, will always come only to this endpoint
with a single jwt search parameter—for example, https://awesome.com/semrush/main?jwt=token.
The URL entered in the browser will be inside JWT in the url field.
Therefore, if the user enters https://semrush.com/app/your-app/long/path?arg=1&arg=2 in the browser,
the JWT's url field will contain /long/path?arg=1&arg=2.
Learn more about using search parameters ›
To decode the content of the received JWT, refer to the JSON Web Tokens website. To get more details about the meaning of the fields, head over to the JWT Reference.
Example in the sample app code ›
Using the JWT signing and validation libraries, validate the key in the jwt parameter.
To do that, you need the secret app key that you get after you register your app in the App Center.
The JWT is only valid for 5 minutes. You must not authorize users who have outdated keys.
Example in the sample app code ›
When the user opens any page in your app, the handler must return the Content-Security-Policy header.
The minimum required header contents are frame-ancestors https://*.semrush.com;.
This way, the app can't open outside the iframe, making it safer for Semrush users.
Check your configuration with the Google CSP Evaluator.
Example in the sample app code ›
This SDK lets you integrate into the ecosystem of the App Center and Semrush. You can connect it in two ways:
If you're using Node.js, install the JS SDK as an npm package:
npm install @semcore/app-center-js-sdkThis package also contains typings for TypeScript. Example in the sample app code ›
If you're connecting it as a dependency in HTML, include the App Center SDK in the <head>...</head> section:
<script async src="https://static.semrush.com/developer-app-center/static/sdk_0.0.7.js"></script>Make sure that the initialization code only runs once when the user opens a page in your app.
To initialize the SDK correctly, do the following:
If you're using the npm package, initialize the SDK when the frontend of the app starts:
window.SM.init().then(function() {
// All methods are available now.
});If your app doesn't use additional frameworks—such as React or Vue.js—you can initialize the SDK inside the HTML code:
<script>
window.onSmSdkLoad = function() {
// "SM" variable is available now.
window.SM.init().then(function() {
// All methods are available now.
});
};
</script>Never pass secret keys to the frontend. Authorization using secret keys must be performed at the backend.
To authorize the user on the frontend and get their data, get the authorization token using the SM.client('getAccessToken') method:
SM.client("getAccessToken").then((token) => encryptJWT(token))You don't need to validate the JWT obtained by this method.
You'll need the corresponding library for working with JWT.
This method returns the JWT for the user employing the data in the token.
This way, you can understand what access level the user has.
To authorize the user on backend, use the jwt search parameter from the iframe URL.
Learn more about the token ›
Both the JWT from the search parameter and the Access Token are identical and are only valid for 5 minutes. However, the JWT from the search parameter contains more data and should be validated on the backend when the user opens the app. Only use it once at the backend during frontend delivery. At the frontend, always use the Access Token.
To request new tokens, use the SM.client('getAccessToken') method.
Example in the sample app code ›
You must always authorize the user when a backend request is made.
For a backend request, get the fresh JWT on the frontend using the SM.client("getAccessToken") method and pass it to the backend.
Validate the token on the backend side using your secret key. Never pass the secret key to the frontend.
Example in the sample app code ›
The app in the iframe can't modify the URL of the parent window. To navigate between the app pages in the iframe, use the following methods that change the history in the parent window:
pushUrl adds a record to the browser history without refreshing the page.
replaceUrl replaces the latest record in the browser history.
Example in the sample app code ›
These methods let you save an additional state linked to the user history within the current session. When the user navigates backward and forward in the browser, the onUrlPop callback returns the saved state, including information about the URL changes in the parent window. The user can thus go back and forth between the pages of your app smoothly. Example in the sample app code ›
Get ready for the app approval and release.