Внешние API
Плагин работает в iframe с политикой безопасности контента (Content Security Policy, CSP). Чтобы обратиться к внешнему домену, объявите его в манифесте и выберите канал доступа:
proxy— плагин вызываетhostApi.externalApiCall(), а платформа отправляет запрос со своего бэкенда;direct— плагин отправляет запрос напрямую из браузера с помощьюfetchилиXMLHttpRequest. Этот способ не рекомендуется для запросов, требующих авторизации.
Для одного домена можно разрешить оба канала.
Разрешение в манифесте
Добавьте в manifest.json секцию permissions.external с перечнем разрешенных доменов и каналов доступа:
{
"permissions": {
"external": [
{
"domain": "api.example.com",
"access": ["proxy"],
"authorization": {
"type": "oauth",
"scopes": ["read", "write"],
"contextTypes": ["user"]
}
},
{
"domain": "api-direct.example.com",
"access": ["direct"]
},
{
"domain": "api-both.example.com",
"access": ["direct", "proxy"]
}
]
}
}
В поле domain укажите hostname строчными буквами, без протокола, пути и порта. Для доменов с национальными символами используйте Punycode. Wildcard-домены не поддерживаются.
Обязательное поле access — непустой массив без повторов. Используйте одно или оба значения:
directдобавляетhttps://<domain>в директивуconnect-srcполитики CSP;proxyразрешает обращаться к домену черезhostApi.externalApiCall().
Поле authorization опционально и допустимо только для домена с каналом proxy: токен подставляет бэкенд платформы, в iframe он не передается.
Прямые запросы
Используйте прямой доступ, только если уверены в условиях
Выбирайте direct только для запросов без авторизации или если вы уверены, что у пользователя уже установлены необходимые cookie и браузер сможет передать их внешнему сервису. Для запросов с cookie укажите credentials: "include", а на стороне внешнего сервиса разрешите CORS-запросы с источника плагина и передачу учетных данных. Учитывайте, что браузер может заблокировать сторонние cookie.
Платформа только добавляет домен в директиву connect-src: она не авторизует пользователя, не подставляет cookie или токены и не настраивает CORS. Если эти условия нельзя гарантировать, используйте канал proxy.
Для домена с access: ["direct"] или access: ["direct", "proxy"] можно использовать браузерные сетевые API:
const response = await fetch("https://api-direct.example.com/data.json");
const data = await response.json();
Внешний сервис должен поддерживать CORS для источника (origin) плагина. Точное значение источника можно посмотреть в заголовке Origin исходящего запроса в инструментах разработчика браузера. Платформа не участвует в прямом запросе: не подставляет токен, не применяет аудит и rate limit прокси.
Канал direct расширяет только директиву connect-src и не изменяет img-src, script-src, style-src и другие директивы CSP.
Домен с access: ["proxy"] не добавляется в connect-src, поэтому прямой запрос к нему будет заблокирован CSP.
CSP, зависящая от разрешений
Некоторые разрешения на работу с данными требуют прямых запросов к техническим доменам сервиса. Для таких разрешений платформа автоматически добавляет связанные источники в CSP. Перечислять эти домены в permissions.external не нужно: набором управляет сервис, и он может различаться между контурами.
Если для разрешения настроены дополнительные источники, его объявление расширяет CSP, но само по себе не дает доступ к данным. Права пользователя и проверка токена продолжают действовать.
Использование прокси
Типичный сценарий — проверить авторизацию, при необходимости запросить ее у пользователя, затем вызвать API:
import {
hostApi,
PluginActionError,
} from "@weavix/tracker-plugin-sdk-react";
async function fetchItems() {
// Проверить авторизацию и показать диалог, если нужно
const { success } = await hostApi.externalApiAuthCheckAndRequest({
domains: ["api.example.com"],
contextType: "user",
});
if (!success) {
// Пользователь закрыл диалог или истек таймаут
return;
}
// Вызвать внешний API через прокси хоста
const { status, body } = await hostApi.externalApiCall({
url: "https://api.example.com/v1/items",
method: "GET",
contextType: "user",
});
// status — HTTP-статус ответа
// body — тело ответа (Record<string, unknown>)
}
POST с телом и таймаутом:
const { status, body } = await hostApi.externalApiCall({
url: "https://api.example.com/v1/items",
method: "POST",
headers: { "Content-Type": "application/json" },
body: { name: "New item", value: 42 },
contextType: "organization",
timeoutMs: 10000,
});
Обработка ошибок прокси
При сетевой ошибке прокси или ответе с ошибочным статусом хост бросает PluginActionError с кодом EXTERNAL_API_CALL_ERROR (1013). Детали — в e.errorData:
import { EXTERNAL_API_CALL_ERROR } from '@weavix/sdk-core';
try {
await hostApi.externalApiCall({
url: "https://api.example.com/data",
method: "GET",
});
} catch (e) {
if (e instanceof PluginActionError && e.code === EXTERNAL_API_CALL_ERROR) {
console.error("Proxy error:", e.errorData);
}
}
Ошибки прямых запросов обрабатывайте средствами выбранного браузерного API. Например, для fetch отдельно проверяйте сетевые ошибки и HTTP-статус ответа.
Управление авторизацией прокси
Быстрый путь — externalApiAuthCheckAndRequest проверяет авторизацию и при необходимости показывает диалог в одном вызове, см. пример выше.
Ручное управление. Если нужен более тонкий контроль — используйте отдельные методы:
// Проверить статус по доменам
const { domains } = await hostApi.externalApiAuthGetStatus({
domains: ["api.example.com"],
contextType: "user",
});
const isAuthed = domains.every((d) => d.authenticated);
// Показать диалог авторизации с подсказкой
if (!isAuthed) {
await hostApi.externalApiAuthRequest({
domains: [
{
domain: "api.example.com",
instructions: {
ru: "Войдите в Example",
en: "Sign in to Example",
},
},
],
});
}
// Отозвать сохраненные учетные данные
await hostApi.externalApiAuthRevoke({
domains: ["api.example.com"],
contextType: "user",
});
Подробнее о методах — в разделе hostApi.externalApi*.