Set up simplified email reports

Simplified email reports

Dev Guides

Last updated: Jan 14, 2025

To retain users in your app, the App Center can send email reports that contain updates on metrics in your app. Such reports can be sent daily, weekly, or monthly.

If a user enables email reports from your app, the App Center requests data from the app's backend in JSON format and sends the report to the user via email.

If you want to let the user set up the email subscription on their own, use custom email reports which work via the App Center server-to-server API.

Restrictions:

Simplified email reports have a fixed template.
App Center can only send simplified email reports to users who purchased the app, got it for free, or have a trial.
Email notifications are turned off by default. Users can change how often they want to receive email reports, or even unsubscribe from emails completely.
You can't send service and promotional emails to the app's users from Semrush.
Simplified email reports can't contain more than 10 lines.

Set up simplified email reports

To receive requests from the App Center, prepare a special URL for reports that can look like this: https://example.com/reports.
Change the report URL in your test app's settings.
Set up your app's backend to process GET HTTP requests in a specific format that the App Center makes to this URL. The request contains a jwt HTTP header that has an encoded user ID. Your app must check the JWT signature and verify that the request comes from a specific App Center user. Once a user turns on email reports, the App Center starts sending requests to the report URL. Request example ›
Set up your app's backend to respond with a JSON file in a specific format. Response example ›
To show a user the modal window with email subscription settings, use the SM.client('requestEmailSubscriptionChange') JS SDK method.
Send your simplified email reports setup with the App Center Team for review and approval.

If the response is valid, App Center compiles the email report and sends it. If the validation fails or your app returns an error response, App Center doesn't send the email to the user and doesn't retry the request to the app.

A user can change email frequency on the My Apps page or directly in the app in the corresponding modal window:

Email report example:

Reference

Request

The request from the App Center contains a jwt HTTP header with the following data:

Header:

{
  "alg": "HS256",
  "typ": "JWT"
}

Payload:

{
  "aud": "5a1c6200-a0d1-11ea-9e0d-1b1d380a852b",
  "exp": 1234567890,
  "viewer_id": "236ba11dfabf49109278-99a5842",
  "is_main_product_active": false,
  "is_main_product_trial_available": true,
  "product_trials_available": ["5a2e742f-6300-4378-9195-4a6909fae65b"],
  "active_products": [
    { "id": "6f9f9120-8933-4cfa-8f4b-44e370fd8828", "value": 1 }
  ]
}

The header contains the token type (JWT), and the signing algorithm (HMAC SHA256). The payload contains the following parameters:

Key	Type	Description
`aud`	`string`	The unique app ID.
`exp`	`number`	Lifetime of a valid token, which is 5 minutes in this case.
`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`	The value is `false` if the app hasn't been purchased or the app is free of charge. Once a user purchases the app or gets a trial, the value becomes `true`.
`is_main_product_trial_available`	`boolean`	This value is `true` if a user can activate trial for app's main product. For example, it will be `true`, if a user never bought app or activated trial for main product.
`product_trials_available`	`Array<String>`	This array contains all app's products ids, for which user can activate trial. For example, if a user never bought or activated trial for in-app purchase with given `id`, that `id` will be in this array.
`active_products` (optional)	`Array<Product>`	The list of the user's purchased in-app products that extend the app functionality with extra features. `<Product>` fields: `ID` (`string`) — product ID `value` (`number`) — amount of purchased in-app products

Response

As a response to the App Center request, your service must return a JSON file with the following data:

{
  "url": "reports",
  "tables": [
    {
      "header": ["Domain", "Visibility", "Change"],
      "body": [
        ["some-site.com", "0.00%", "0.00%"],
        ["other-site.com", "0.45%", "2.55%"]
      ]
    },
    {
      "header": ["Domain", "Traffic", "Change"],
      "body": [
        ["some-site.com", "0.00%", "0.00%"],
        ["other-site.com", "0.45%", "2.55%"]
      ]
    }
  ]
}

The response must contain the following parameters:

Key	Type	Description
`url`	`string`	The relative path to the page where the user can view the web version of the reports. In the example, we pass the `reports` path. When the user receives the email and clicks View in app, the Reports page in your App Center app opens.
`tables`	`Array<Table>`	List of the report tables of your app. Table fields: `header` of the `Array<string>` type is a list of the Titles column. `body` of the `Array<Array<string>>` type is a body of a table that's a two-dimensional array. The first dimension is the number of rows, and the second is the number of columns.

Requirements:

The list must contain between 1 and 4 tables.
The table must contain between 1 to 4 columns.
The number of rows in the table body must be between 1 and 10.
The number of columns must match the number of Titles in the header.

If these requirements aren't met, the email report can't be sent.