GitHub CommunityYouTubeTwitchTwitterSupport
Docs/Connected Accounts

Connected Accounts

You can choose to provide a more robust experience for your customers who already have a Grammarly account. The connected accounts feature allows users to connect their Grammarly account to your application so that they can access full account features and suggestions, such as their personal dictionary, style guide, and customization preferences.

How it works

Grammarly implements the industry-standard OAuth 2.0 protocol to securely issue access tokens for third-party applications.

  • Once the connected accounts feature is turned on for your application, users will start seeing the “Connect your Grammarly Account” menu option under the Grammarly button.

  • After clicking “Connect your Grammarly Account,” the user will see the consent screen, which will ask the user to authorize your application to interact with their Grammarly account. The consent screen is a crucial part of the standard OAuth 2.0 flow.

  • Once the user approves the application, the Grammarly Text Editor SDK receives a long-term session token that is stored in the localStorageopen in new window of your application. The session token gets automatically renewed each time a user interacts with Grammarly through the Text Editor SDK from within your application.

    The session token expires after 30 days of inactivity. Once the token expires, a user would be offered to reconnect their Grammarly account to your application. When a user reconnects, they will not be asked for consent again if they have approved your app previously.

  • A user can log out of their Grammarly account from your application by choosing the “Log out” menu option under the Grammarly button. If they choose to connect their Grammarly account again, the consent screen will be skipped, as the user already authorized your application in the past.

A user may use your application from multiple browsers. Each browser would maintain its own connection state, as the session token is saved in localStorage that is not shared between different browser instances. However, a user will only need to approve the application via the consent screen once for your application, as the user’s consent is shared between sessions.

Grammarly Button

Turning on connected accounts

+You can turn on and set up this feature in the Connected Accounts section of your App Console. For desktop clients only, there are a few more steps required to support the user authorization flow, described below.

You can customize the way your application is shown to users publicly by setting a display name and an app logo.

Privacy policy

Please note that you’ll need a privacy policy that states your commitment to your customers. This would be in addition to Grammarly’s own privacy policy, which does not cover your application’s privacy practices.

Configuring connected accounts for desktop clients (Electron)

The instructions below are for desktop clients only. For a web client, you don't need to perform any of these additional steps—simply turn on connected accounts for your application.

Allowing users to connect their Grammarly accounts to your desktop application requires a few extra steps. The instructions below will guide you through this process. They include code snippets and pseudocode you can use to get started. Complete examples are available in the Grammarly for Developers GitHub repositoryopen in new window:

Before you begin: Ensure you have a desktop application that includes a renderer script with at least one text field successfully using the Grammarly Text Editor Plugin. See Text Editor SDK for Electron for detailed instructions.

Add a list of redirect URIs to your client configuration

Grammarly needs to know which URIs it can redirect to after a user attempts to connect their Grammarly account to your application. When configuring the credentials for your desktop client, you can create a list of redirect URIs.

Grammarly validates each redirect URI as described in the bulleted list below. If you feel your URI is being incorrectly marked as invalid, please create an issue in the Grammarly for Developers GitHub repositoryopen in new window.

  • The redirect URI must not use well-known schemesopen in new window such as HTTP, HTTPS, FTP, Telnet, and other common application protocols. Your Electron application is unlikely to be the default handler for these standard schemes, so Grammarly does not allow redirect URIs with these schemes.
  • The redirect URI must not use wildcard characters, non-printable ASCII characters, or null characters.
  • The redirect URI must not contain a path traversal (e.g. /..).
  • The redirect URI must not contain the userinfo subcomponentopen in new window.
  • The redirect URI must not contain a fragmentopen in new window identifier component.
  • The redirect URI must have a domain. Domains with non-Latin characters can be Punycodeopen in new window encoded.

The following steps will walk you through how to add a list of redirect URIs to your desktop client configuration.

  1. In My Appsopen in new window, navigate to your application. Then select Desktop in the left menu.
  2. In the Credentials section, click Add a redirect URI.
  3. Input a URI that the Grammarly consent screen is permitted to redirect to after a user has connected their account. The URI should point to a resource the desktop application will open (e.g. example://grammarly-auth).
  4. Repeat Steps 2 and 3 as needed.
  5. Click Save.

Turn on connected accounts for your Electron app

You will need to turn on connected accounts so that users will see the “Connect your Grammarly account” option when they click the Grammarly Button in your application.

The Grammarly button menu that includes an option to 'Connect your Grammarly account'
  1. In My Appsopen in new window, navigate to your application. Then select Connected Accounts in the left menu.
  2. Select Allow connected accounts with OAuth 2.
  3. Input the display name, homepage URL, and privacy policy URL for your app.
  4. Optionally upload a logo for your app.
  5. Click Save.

Configure the Grammarly Text Editor Plugin

To use connected accounts, you’ll need to configure the oauthRedirectUri property of the EditorConfig for the Text Editor Plugin. The oauthRedirectUri must be in the list of redirect URIs in your desktop client credentials (see the section above).

Example code for configuring the plugin for a textarea to have an OAuth redirect URI of "example://grammarly-auth" is below.

<script>
  Grammarly.init().then((grammarly) => {
    grammarly.withElement(document.querySelector("textarea"), { oauthRedirectUri: "example://grammarly-auth" });
  });
</script>

When a user selects "Connect your Grammarly account", they’ll be taken to a URL to log in on grammarly.com. It’s important to ensure that this URL is opened in a web browser, rather than inside the app. Here’s an example of code that could be included in your main script:

win.webContents.setWindowOpenHandler(({ url }) => {
  if (url.includes("grammarly")) {
    shell.openExternal(url); // open the link in Electron system's default browser
    return { action: "deny" }; // don't open the link in Electron app
  } else {
    // these are not Grammarly links, so they can be opened within Electron app
    return { action: "allow" };
  }
});

Set your app as the default protocol client for your redirect URI

For any redirect URIs specified earlier, you’ll need to set your app as the default protocol client. This will ensure that, when the OAuth flow completes, the URI will be opened inside of your desktop app.

To do so, include a line like the following in your main script:

app.setAsDefaultProtocolClient("example");

Add an event listener for open-url events in your main process

After a user successfully authenticates on grammarly.com, Grammarly will call the redirect URI you specified in the editor config. Your desktop application should listen for open-url events and pass the URL associated with the event to a renderer process that is using the Text Editor SDK.

There are a variety of ways to listen for events in the main process and pass the associated URL to a renderer process. The psuedocode below listens for open-url events and checks if the URL matches a Grammarly redirect URI that was configured for this desktop application in My Appsopen in new window.

app.on("open-url", (event, url) => {
  // If the link matches a Grammarly redirect URI, send the link to the renderer process
  if (url.includes("grammarly-auth")) {
    event.preventDefault();

    // Add your messaging code here to send the link to your renderer process
  }
});

Pass the URL to the Text Editor SDK

The final step in the OAuth flow is to pass the URL from the open-url event to the EditorSDK in your renderer script. This is done by calling handleOAuthCallback inside a renderer script.

For instance, in your code that handles receiving messages from the main process, you could include code like the following:

const grammarly = await init("YOUR_CLIENT_ID");
grammarly.handleOAuthCallback(url); // this URL is passed from the main script as described in the previous step

Summary

Now you’ve configured connected accounts for your Electron app! Users can click the Grammarly button in your app, select the option to connect their account to your application, and access full account features and suggestions.

Complete examples are available in the Grammarly for Developers GitHub repositoryopen in new window:

Learn more about enabling Grammarly suggestions in the guide for using the Text Editor SDK in Electron apps.

Last Updated: 2/7/2023, 10:38:49 PM
Rate this page