The Semrush JavaScript SDK includes a full set of available methods that you may need for setting up your app in App Center.
SM.init(): PromiseInitializes and sets up the Semrush JS SDK.
SM.client('getAccessToken'): PromiseReturns the promise with the encoded JWT string with the following fields:
aud (string): Unique app ID.exp (number): Lifetime period of a valid token—in this case, 5 minutes.viewer_id (string): App user ID. If this is a corporate account, all its sub users have the same value.is_main_product_active (boolean): Is false if the app hasn't been purchased or the app is free of charge.
Once the user purchases the app or gets a trial, the value becomes true.is_app_taken_for_free (boolean): Is true if the user gets the app for free.
Applicable only for free and demo apps.is_main_product_trial_available (boolean): Is true if the user can activate a trial for the app's main product.
For example, it will be true, if the user has never bought the app or activated a trial for its main product before.product_trials_available (Array<string>): Contains all the IDs of the app's products for which the user can activate a trial.
For example, if the user has never bought or activated a trial for the in-app purchase with the given id before, that id will be in this array.active_products (optional, Array<Product>): List of the user's purchased in-app products.
The <Product> fields:
ID (string): Product ID.value (number): Number of purchased in-app products.extra_user_data (optional, Object): Contains additional information about the state of the app trial and in-app trials.
Learn more in JWT reference.
The object fields:
is_main_product_trial_active: Is true if the user has activated a trial of the app and the trial period hasn't expired yet.active_product_trials: List of in-app IDs in an active trial state with an unexpired trial period.This method is useful for checking AJAX requests from your client on your server.
Note that every time your app is using the method, each call sends a new request to the server. For your app to perform better, we recommend you to save the result from the method for some time and reuse it.
SM.client('requestMainProductPurchase')Opens the pop-up window or redirects to the page with the offer to purchase the app or get the trial version.
When the user purchases the app, the page reloads with the updated is_main_product_active JWT parameter.
If the user doesn't have a linked bank card and a paid Semrush subscription, calling the method redirects the user to the payment page without displaying a modal window.
For free apps or the demo mode of freemium apps, the value is false before the user purchases their full version.
Once they purchase the app or get a trial, the value becomes true.
The method doesn't have any outcome if is_main_product_active is true.
Learn more about the is_main_product_active parameter in monetization options.
SM.client('requestInAppPurchase', productIds?: Array<string>)Opens the pop-up window with the in-app product purchase options.
If you use the method without the productIds parameter, the pop-up window will show all in-app purchase options.
You can show specific in-apps using their IDs: SM.client('requestInAppPurchase', ['UUID1', 'UUID2']).
If your app has only one in-app product, the user will get the offer to purchase that product.
When a user purchases any in-app product, the page reloads with an updated active_products JWT parameter.
The method doesn't have any outcome if the app doesn't have any additional in-app features.
Freemium and paid apps
If the is_main_product_active parameter is false, or the user has the trial version of the app, they will get a pop-up prompting them to buy the full version.
Free apps
The is_main_product_active parameter is always false.
A pop-up window with in-app product purchase options will appear, excluding the option to buy the app first.
SM.client('pushUrl', url: string, options?: { state: any })Changes the page URL by adding it in the browser history, which is useful for navigation.
By default, the links in the iframe don't change the URL in the parent window. You can include search parameters in the parent window URL, but you must use only approved parameters. Otherwise, they won't be displayed in the address bar. For more details, refer to search parameters section.
SM.client('replaceUrl', url: string, options?: { state: any })Changes the page URL by replacing it in the browser history, which is useful for navigation.
By default, the links in the iframe don't change the URL in the parent window. You can include search parameters in the parent window URL, but you must use only approved parameters. Otherwise, they won't be displayed in the address bar. For more details, refer to search parameters section.
SM.client('showLoginModal')Opens the pop-up window that asks the user to log in. It's useful when the user logs out on another browser tab.
When you get a response with USER_UNAUTHORIZED: Bad response text from SM.client('getAccessToken'),
call this method to show the login pop-up window and ask the user to log back in. The user can log back in or close the pop-up.
When the user logs back in, they'll be redirected to the same page (same URL with the same query parameters). For more details, refer to the Authentication section.
SM.client('requestUserFeedback')Opens the pop-up window with the user feedback form.
The pop-up won't open in the following cases:
Don't show the user a button that calls the method because it may not open the feedback pop-up.
Use the method as a reaction to some event or action. For example, you can call it when the user has purchased the app's paid version or successfully tried a new feature.
You can use the method for apps in test mode as well, but the feedback won't be saved.
In test mode, you can call the method as many times as you want.
All user feedback is kept in the App Center database.
SM.client('requestEmailReports'): PromiseOpens the pop-up window with the offer to let us email the user notifications. The user can allow notifications, reject them, or close the pop-up window.
Once the user has made a decision, the page reloads with the updated email_subscription.state JWT parameter.
Make sure that you can open the pop-up window. If the user has the STATE_UNSPECIFIED value, you can open the pop-up.
In other cases, the pop-up won't appear, but the subscription can still be managed through the menu by clicking the gear icon.
If they close the window, the method returns an error and the window won't open during the next week.
For a test app, you can call the method for an unlimited number of times and still be able to check the user status.
Use the method as a reaction to some user action, such as clicking on the Subscribe button.
SM.client('requestEmailSubscriptionChange')Opens the pop-up window with email subscription settings.
Email subscription settings include the following:
Never)Daily, Weekly, Monthly)Once the user closed the pop-up, the page reloads with the updated email_subscription.enabled JWT parameter.
The method is used for the recurrent emails.
SM.client('setLogging', isLogging: boolean)Enables and disables logging.
To disable logging, call this method with the false parameter.
By default, logging is enabled for all levels (log, info, warn, error).
Learn more about JS console API.
Error level logging always happens, even if you try to turn it off.
This method is deprecated. Use
SM.client(‘requestMainProductPurchase’)instead.
SM.client('requestAppInstall')SM.client('resizeWindow', {width?: number, height?: number})This method is deprecated. To switch to the fixed layout, refer to the migration guide.
Changes the app iframe width and height.
It's better to change only the iframe height to fit the content of the app. If you don't set a specific width value, the default iframe width is dynamic, and equals to the page width.
SM.client('scrollTo', {top?: number, left?: number, behavior?: 'smooth' | 'auto'})This method is deprecated. Use the window.scrollTo method instead. To switch to the fixed layout, refer to the migration guide.
Scrolls to a specific set of coordinates on the page. You can also set the animation of scrolling:
behavior: 'smooth' for smooth scrolling.behavior: 'auto' for instant scrolling.SM.client('getPageInfo'): PromiseThis method is deprecated. Use the window.innerWidth and window.innerHeight methods instead. To switch to the fixed layout, refer to the migration guide.
Returns a JavaScript object containing the app viewport properties. All of them have the number type:
clientHeight: Height of the viewport in pixels.clientWidth: Width of the viewport in pixels.offsetLeft: Number of pixels between the left edge of the viewport and the left edge of your app's iframe.offsetTop: Number of pixels between the top edge of the viewport and the top edge of your app's iframe.scrollLeft: Number of pixels between the left edge of your iframe and the left edge of your iframe's viewport.scrollTop: Number of pixels between the top edge of your iframe and the top edge of your iframe's viewport.SM.addCallback(
'onUrlPop',
callback: (newUrl: string, options?: { state: any }) => unknown
): FunctionAdds the callback which is called when the user clicks the back or forward button in the browser.
Callback receives two arguments:
newUrl: string is a new URL that the user navigated tooptions: { state: any } is an object with single property state which contains data that you passed to
pushUrl or replaceUrl methods
Returns the function which removes this callback.Example:
const unsubscribe = SM.addCallback('onUrlPop', callback);
function callback(newUrl) {
console.log('User clicked "back" or "forward" button. The current URL is: ', newUrl);
}SM.addCallback(
'onScroll',
callback: (data: {scrollX: number, scrollY: number}) => unknown
): FunctionThis method is deprecated. To switch to the fixed layout, refer to the migration guide.
Adds the callback which is called when the app page or an element has been scrolled by the
user or an API, refer to scrollTo.
Returns the function which removes this callback.
Example:
const unsubscribe = SM.addCallback('onScroll', callback);
function callback(data) {
console.log('scrolling the page', data);
}SM.configReturns application config.
{
"layout": 1,
"allowedGetParams": ["page", "device_type"]
}Fields description:
layout (string): Defines the layout type:
1: Scrollable.2: Fixed.To switch the layout from scrollable to fixed, refer to the migration guide.
allowedGetParams (Array<string>): list of query parameters allowed in URL.
SM.setAutoHeightUpdate(params: { enable: boolean, calculateHeight?: () => number, minHeightReduceToResize?: number = 16, minHeightExpandToResize?: number = 4 }): void;This method is deprecated. Learn the migration guide to switch on the fixed layout.
Allows the app iframe to align its height with the app’s content automatically.
The method accepts a single argument — the params object, which must include the boolean enable property. If the enable parameter value is true, resizing is enabled, and if it's false, resizing is disabled. The method uses ResizeObserver to track changes.
You can also control the precision of resizing with the following optional parameters:
calculateHeight function for calculating the app content height. The function is called every time the app content size changes. If the app height expands by at least the minHightExpandToResize value or reduces by at least the minHeightReduceToResize value, the iframe size changes.minHeightReduceToResize for specifying the number of pixels for the reducing threshold. If not specified, it defaults to 16 pixels.minHeightExpandToResize for specifying the number of pixels for the expanding threshold. If not specified, it defaults to 4 pixels.Examples
SM.setAutoHeightUpdate({ enable: true });SM.setAutoHeightUpdate({ enable: false });calculateHeight function and minHeightExpandToResize parameter:SM.setAutoHeightUpdate({ enable: true, calculateHeight: () => document.body.clientHeight, minHeightExpandToResize: 1 });