Plugin Quick Start
This guide registers a plugin in the Developer Console, scaffolds a plugin server from the App Connect template, and installs the plugin for an account.
Prerequisites
- Node.js 20 or newer
- A RingCentral account for the Developer Console and App Connect extension, with App Connect admin rights for the install step
- A public HTTPS tunnel when the Core server runs in production, or when it cannot reach the local plugin directly
Plugin server network policy
The network policy is selected by the Core server's NODE_ENV, not the plugin server's environment or catalog visibility:
| Core environment | Plugin server URLs |
|---|---|
Exactly NODE_ENV=production |
Absolute HTTPS URLs resolving exclusively to public Internet unicast addresses. |
Any other value, including development, test, staging or an unset variable |
Absolute HTTP or HTTPS URLs; localhost and private-network destinations are allowed for local testing. |
All environments reject malformed URLs, unsupported protocols and embedded URL credentials. HTTPS certificate verification remains enabled. Set NODE_ENV=production explicitly in production before starting Core; an absent value does not enable production network restrictions. The connector deployment environment template includes this setting.
The same policy applies to registration, processing, token synchronization and license checks, including endpoints retained in old installation snapshots. When both Core and the plugin run locally, start Core with NODE_ENV=development and configure the plugin URLs with the local host and port. A production Core still requires a public HTTPS tunnel to reach a developer's plugin. localhost always refers to the machine running Core.
Each request retains the selected policy for its connection and redirects. The transport uses the checked DNS addresses for the connection, supports IPv4 and IPv6, and does not route through ambient HTTP proxies or alternate transports. Redirect method/body behavior and the HTTP client's existing credential stripping remain intact; callbacks do not restore removed credentials. No new application timeout or port-443-only restriction is imposed.
private and shared describe catalog visibility; their server URLs follow the same network policy. Browser pricing, purchase and subscription links keep their separate licensing URL contract. A rejected snapshot update retains the previous snapshot, and every invocation is checked again.
Verification: packages/core/test/lib/pluginHttp.test.ts, packages/core/test/handlers/plugin.test.ts, and packages/core/test/handlers/log.test.ts. Review the production plugin DNS/redirect paths and Node address-family behavior before rollout. The address classification follows IANA IPv6 allocation and also excludes Azure's virtual platform address.
1. Register a plugin profile
Open the Developer Console, create a plugin, and note its secret key from the plugin's Quick setup section. Configure the plugin's URLs later, once the plugin server is reachable from Core.
2. Scaffold a plugin server
npx @app-connect/cli init my-plugin --template plugin
cd my-plugin
The generated project includes:
src/app.ts, which wires the routes App Connect expects a plugin server to exposesrc/plugins/syncPlugin.tsandsrc/plugins/asyncPlugin.ts, starter implementationssrc/handlers/license.tsandsrc/handlers/oauth.ts, optional license and OAuth handlerssrc/lib/pluginToken.ts, which issues and validates the plugin JWT.env.test, copied to.envby the CLI
3. Configure the secret key
Run the following inside the project and paste the plugin secret key from the Developer Console when prompted:
npx @app-connect/cli env
The CLI detects a plugin project and saves the value as PLUGIN_SERVER_SECRET_KEY in .env. The template ships a placeholder for this variable, which the CLI treats as not yet configured. To skip the prompt:
npx @app-connect/cli env --secret-key <your-plugin-secret-key>
4. Start the server and expose it
npm run dev
The plugin template listens on port 6067 by default. If Core also runs locally with NODE_ENV=development, use a local address reachable from Core, such as http://localhost:6067, for the configured plugin URLs, retaining each endpoint's path. When Core runs in production or on another machine without direct access, expose the plugin with a public HTTPS tunnel, for example ngrok http 6067, and update all configured URLs in the Developer Console to its HTTPS address.
Note
The plugin dev script rebuilds and starts the server once. Restart it after changing code.
5. Install and test
- Open the App Connect extension and connect to a connector as an admin user.
- Open the Admin tab and install the plugin.
- Make or receive a test call and log it. The plugin runs according to its
supportedLogTypes.
See Registration flow for what happens during install, and Server endpoints for the request and response contracts.