How the plugin platform works

A plugin is a standalone frontend JavaScript application that runs in an iframe inside the Tracker app. An SDK is provided for its development. Using React is considered a priority. There is also a vanilla JavaScript library that allows you to avoid being tied to React.

The platform covers the entire lifecycle of plugins: it provides tools for development and debugging, versioning, and publishing, as well as a repository for storing plugins. Administrators can install, update, and disable plugins, controlling their availability to users and contexts.

Running a plugin in an iframe

The interface part of plugins is static content hosted on Tracker's servers. It runs in an isolated iframe on a cookieless domain, where almost everything is forbidden, including any network requests. Therefore, all communication with Yandex services, the Tracker public API, and the outside world is done through the SDK.

SDK

Interacting with Tracker is done using the SDK, which is connected as a library. The SDK provides methods for interaction at the user interface level, methods for working with the Tracker public API, and a plugin data storage.

The SDK is delivered as two npm packages:

• core — API client and basic integration primitives (JS/TS).
• react — React wrappers over core for easy UI development.

CLI

CLI is a command-line utility in the form of an NPM package that covers the entire plugin lifecycle: creation, debugging, validation, and publishing.

UI components

A library of UI components in Tracker's style, available for use in plugins.

Manifest

The manifest is a manifest.json file in the project's root directory. It describes the plugin, the requested permissions, and integration points with Tracker.

JSON Schema

When creating a project, CLI adds a manifest.schema.json file next to the manifest and specifies it in the $schema field:

{
  "$schema": "./manifest.schema.json"
}

The code editor uses the schema to validate the manifest, provide autocomplete, and show allowed values. CLI validates the manifest against the built-in schema even if the $schema field is missing. Do not edit manifest.schema.json manually. To update the local schema and other template files, run weavix up.

Restrictions and lists of allowed values may change. Check them in the manifest.schema.json of the current project.

Manifest fields

Configuring slots

A plugin can use multiple integration points. For each point, specify:

• entrypoint — path to the entry HTML file;
• title — interface element name in Russian and English;
• contextLevel — level of data available to the plugin:
  • basic — ID of the current entity and basic metadata;
  • full — full entity object, for example, all issue fields;
• description — optional description in Russian and English;
• icon — optional object with a path to the icon in the url field. Used in the dock slot.

Use full only if the plugin needs the full entity object.

The slots field is not required by the manifest format, but you must configure at least one slot to validate and publish the project.

"slots": {
  "tracker": {
    "issue.action": [
      {
        "entrypoint": "index.html",
        "contextLevel": "basic",
        "title": {
          "ru": "Мой плагин",
          "en": "My Plugin"
        }
      }
    ]
  }
}

Permissions

In the manifest, specify only the permissions that the plugin needs. The permissions object contains the following fields:

• data — required array of permissions for working with Tracker data. Permissions have the format tracker:<resource>:read for reading and tracker:<resource>:write for modifying data. For example, tracker:issues:read allows reading issues, tracker:issues:write allows modifying them, and tracker:attachments:write allows uploading attachments. The current list of allowed values is provided in manifest.schema.json;
• device — access to the user's device capabilities. Allowed values: clipboard-write, microphone, camera, geolocation, web-share, and allow-downloads. If supported by the browser, the user must additionally allow access to the selected capability;
• ui — additional actions in the Tracker interface. Add such a permission only if it's specified in the description of the SDK method you're using;
• external — domains of external APIs and authorization parameters. Direct requests to such APIs from the plugin are forbidden: the platform proxy handles them. For more information, see External APIs.

Plugin data storage

The platform provides a unified plugin data storage and an API for working with it, which supports two modes:

• Contextual storage [Coming soon] — data is linked to a specific Tracker entity and a granularity level (organization, user, queue, portfolio, project, issue, issue-comment). This is suitable for settings and states that depend on an organization, user, queue, or specific issue. The storage context does not have to match the plugin installation context.

• Key-value mode — data is stored as key → value pairs in the plugin's namespace. This is suitable for simple configurations and service data where quick access by key is more important than linking to a domain entity.

In both modes, the API covers reading, writing, updating, and deleting data, supports concurrent change control (versioning/optimistic locking), and stores pluginVersion for managed data migrations when the plugin is updated.

For more information about the current storage implementation and its API, see the Plugin data storage section.

Access to external APIs (OAuth and proxy)

The platform provides a secure mechanism for integrations with external services: a platform proxy for making HTTP requests and a secret vault for storing OAuth tokens.

• Platform proxy — a single endpoint for calling external APIs on behalf of the plugin. The plugin sends the request parameters: URL, method, headers, body. The platform executes the request on the backend and returns the result. Access is restricted declaratively (domain allowlist). The platform blocks unsafe destinations (private networks/localhost, unauthorized redirects), runs audits, and applies rate limits per pluginId and organization.

• OAuth and Secret vault — the platform takes over the OAuth flow and token storage: access/refresh tokens are saved in the secret vault and never end up in the plugin's iframe. Tokens are supported in two contexts: user (personal) and organization (shared across the organization, created by the administrator). When making requests through the proxy, the platform automatically inserts the appropriate token, and upon expiration, it either performs a refresh on the backend or signals the need for re-authorization.

For more information on how to call external APIs from a plugin, see the External APIs section.

Integration points (slots)

The location where the plugin will be opened, as well as the mechanism for invoking it (such as a button or as part of a form), is determined by the slot. The slot is specified in the manifest.

Available slots and details of their use are described in the Integration points section.

Plugin launch context

The plugin launch context is determined by the slot it is in and contains the following information:

• Current Tracker theme
• Current Tracker language
• Slot context — data from the environment of the page where the plugin is running. For example, in the issue.action slot, information about the open issue will be returned. The context format is as close to the public API types as possible.

Slot context levels

The context level is set by the contextLevel parameter in the slot description in manifest.json and determines what data will be available to the plugin via useTrackerPluginContext.

basic

Only the current entity ID and basic metadata are available:

type BasicContext = {
    /** Current entity ID */
    entityId: string;
    /** Additional basic information about the entity.
     *  For example, for a comment, this will contain the parent issue ID. */
    entityMeta?: Record<string, string>;
};

Use basic if the plugin only needs to know the entity ID — this is a lighter option without unnecessary overhead.

full

Full context with live entity data. The format matches the public API types. For example, for the issue.action slot, it's the full Issue object. The data is up to date as of the moment the plugin is opened.

Use full only if the plugin really needs the full entity data.