Пользовательские вставки HTML, CSS и JavaScript

ng-custom — это специальный каталог основного сайта, через который можно подключать пользовательские HTML, CSS и JavaScript-вставки без изменения исходного Angular-кода и без пересборки основного frontend-приложения.

Этот механизм нужен для подключения внешних сервисов и дополнительных клиентских вставок, которые должны работать на публичной части сайта.

Через ng-custom можно подключать:

• онлайн-чаты;
• системы аналитики;
• рекламные пиксели;
• сторонние JavaScript-виджеты;
• HTML-коды внешних сервисов;
• verification meta-теги;
• JSON-LD-разметку;
• noscript-коды;
• собственные CSS-файлы;
• пользовательский JavaScript.

Публичный путь для файлов всегда один: /ng-custom/

Пример публичной ссылки:

https://example.com/ng-custom/client-scripts.js

---

Главное правило

ng-custom работает только для основного сайта, то есть для Angular frontend.

Если проект разделён так:

example.com          — основной сайт / frontend / Angular
app.example.com      — backend / Laravel / админка / API

то ng-custom нужно создавать только в основном сайте:

public/ng-custom/

Не нужно создавать ng-custom в backend-папке, в админке или в API-проекте.

ng-custom не влияет на Laravel backend, API, админ-панель и backend-страницы. Он предназначен только для публичного frontend-сайта.

---

Как устроена система

В проекте могут встречаться два типа каталогов ng-custom.

/ng-custom/	Что означает
public/ng-custom/	Основная runtime-папка для клиентских вставок на production
dist/.../ng-custom/	Папка внутри результата сборки Angular

Для ручной настройки на сервере используйте именно:

public/ng-custom/

Каталог dist — это результат сборки. Его не рекомендуется редактировать вручную, потому что при следующей сборке файлы могут быть перезаписаны.

Правильная логика такая:

public/ng-custom/     — редактируется клиентом на сервере
dist/                 — результат сборки, вручную не редактируется

---

Структура каталога

Внутри public/ng-custom/ создаются основные файлы:

client-scripts.js
client-snippets.html
ssr-head.html
ssr-body-start.html
ssr-body-end.html

Итоговая структура:

public/
└── ng-custom/
    ├── client-scripts.js
    ├── client-snippets.html
    ├── ssr-head.html
    ├── ssr-body-start.html
    └── ssr-body-end.html

Если нужны отдельные SSR-вставки для разных языков, можно добавить языковые папки:

public/
└── ng-custom/
    ├── ru/
    │   └── ssr-head.html
    ├── en/
    │   └── ssr-head.html
    ├── uk/
    │   └── ssr-head.html
    ├── client-scripts.js
    ├── client-snippets.html
    ├── ssr-head.html
    ├── ssr-body-start.html
    └── ssr-body-end.html

Если языкового файла нет, система использует общий файл из корня public/ng-custom/.

---

Режимы работы

ng-custom поддерживает два режима работы:

Режим	Что делает	Для чего использовать
Browser Mode	Загружает код уже в браузере после открытия сайта	Онлайн-чаты, пиксели, виджеты, JS-коды
SSR Mode	Вставляет код сразу в исходный HTML, который отдаёт сервер	Meta-теги, JSON-LD, noscript, SEO-коды

Оба режима можно включить одновременно.

Browser Mode

Browser Mode — это режим, при котором пользовательский код загружается уже в браузере после открытия страницы.

Этот режим подходит для сервисов, которым не обязательно быть в исходном HTML страницы.

Используйте Browser Mode для:

• онлайн-чатов;
• рекламных пикселей;
• аналитики;
• сторонних JavaScript-виджетов;
• pop-up сервисов;
• callback-виджетов;
• небольших пользовательских скриптов.

Файлы Browser Mode:

client-scripts.js
client-snippets.html

1

client-scripts.js

client-scripts.js используется для JavaScript-кода.

Этот файл:

• выполняется только в браузере;
• не выполняется на SSR;
• не входит в Angular bundle;
• может изменяться отдельно от основного приложения.

Пример подключения внешнего виджета:

window.IEX_CUSTOM_INIT = function (api) {
    api.onReady(function () {
        api.loadScript('https://example.com/widget.js', {
            id: 'example-widget',
            async: true,
            defer: true
        });
    });
};

2

API внутри client-scripts.js

В client-scripts.js доступен объект api.

Метод	Для чего нужен
api.loadScript(src, options)	Подключает внешний JavaScript-файл
api.injectHtml(html, options)	Вставляет HTML в страницу и выполняет script-теги
api.onReady(callback)	Выполняет код после готовности DOM
api.safeRun(callback, label)	Выполняет код безопасно через try/catch

Пример безопасного выполнения кода:

window.IEX_CUSTOM_INIT = function (api) {
    api.onReady(function () {
        api.safeRun(function () {
            console.log('Custom code loaded');
        }, 'custom-log');
    });
};

3

client-snippets.html

client-snippets.html используется для готового HTML-кода от сторонних сервисов.

Например, если внешний сервис выдал готовый блок с div и script, его можно вставить в этот файл.

Пример:

<div id="support-chat"></div>

<script>
    window.supportChatId = 'client-123';
</script>

<script src="https://example.com/chat.js"></script>

Система обработает файл автоматически:

Что находится в файле	Что сделает система
Обычные HTML-элементы	Добавит в страницу
meta, link, style, title	Перенесёт в head
script	Пересоздаст и выполнит
<base>	Проигнорирует, чтобы не сломать маршруты сайта

SSR Mode

SSR Mode — это режим, при котором содержимое файлов вставляется прямо в HTML, который отдаёт сервер.

Этот режим нужен, если внешний сервис требует, чтобы код был именно в исходном HTML страницы.

Используйте SSR Mode для:

• Google Site Verification;
• Yandex Verification;
• meta-тегов подтверждения домена;
• JSON-LD;
• Schema.org;
• SEO-разметки;
• noscript-кодов;
• сервисов, которые требуют вставку сразу после <body>.

Файлы SSR Mode:

ssr-head.html
ssr-body-start.html
ssr-body-end.html

1

ssr-head.html

ssr-head.html вставляется перед закрывающим тегом:

</head>

Используйте для кода, который должен находиться внутри head.

Подходит для:

• verification meta-тегов;
• JSON-LD;
• Schema.org;
• preconnect;
• stylesheet;
• дополнительных link-тегов.

Пример:

<meta name="google-site-verification" content="token">

<link rel="preconnect" href="https://example.com">

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "Exchange"
}
</script>

2

ssr-body-start.html

ssr-body-start.html вставляется сразу после открытия:

<body>

Используйте для кодов, которые должны быть размещены в начале body.

Подходит для:

• noscript;
• Google Tag Manager fallback;
• сервисов, которые требуют вставку сразу после <body>.

Пример:

<noscript>
    <iframe src="https://example.com/ns.html?id=demo"
            height="0"
            width="0"
            style="display:none;visibility:hidden"></iframe>
</noscript>

3

ssr-body-end.html

ssr-body-end.html вставляется перед закрывающим тегом:

</body>

Используйте для скриптов, которые должны быть в исходном HTML, но не должны блокировать загрузку страницы.

Пример:

<script src="https://example.com/tracker.js" defer></script>

---

Создание папки на FastPanel

На сервере нужно создать каталог public/ng-custom/ в основном frontend-сайте.

Перед выполнением команд замените:

имя_пользователя_frontend

на пользователя основного сайта в FastPanel.

Замените:

ваш_домен

на основной домен сайта.

Создайте папку:

mkdir -p /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom

Создайте основные файлы:

touch /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/client-scripts.js
touch /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/client-snippets.html
touch /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/ssr-head.html
touch /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/ssr-body-start.html
touch /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/ssr-body-end.html

Если нужны языковые папки:

mkdir -p /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/ru
mkdir -p /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/en
mkdir -p /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/uk
mkdir -p /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/ka

---

Настройка ENV

В ENV основного frontend/SSR-сайта укажите путь к runtime-папке ng-custom.

Пример:

CLIENT_CUSTOM_DIR=/var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom
CLIENT_CUSTOM_SCRIPTS_ENABLED=true
CLIENT_CUSTOM_SSR_ENABLED=true

Переменная	Что означает
CLIENT_CUSTOM_DIR	Полный путь к папке public/ng-custom
CLIENT_CUSTOM_SCRIPTS_ENABLED=true	Включает Browser Mode
CLIENT_CUSTOM_SSR_ENABLED=true	Включает SSR Mode

Если нужны только browser-вставки:

CLIENT_CUSTOM_SCRIPTS_ENABLED=true
CLIENT_CUSTOM_SSR_ENABLED=false

Если нужны только SSR-вставки:

CLIENT_CUSTOM_SCRIPTS_ENABLED=false
CLIENT_CUSTOM_SSR_ENABLED=true

После изменения ENV нужно перезапустить SSR-процесс сайта.

После изменения самих файлов внутри public/ng-custom/ пересборка Angular обычно не нужна.

Настройка Nginx

В nginx-конфиг основного frontend-домена добавьте отдельный блок:

location ^~ /ng-custom/ {
    alias /var/www/имя_пользователя_frontend/data/www/ваш_домен/public/ng-custom/;
    try_files $uri =404;

    expires -1;
    add_header Cache-Control "no-store, no-cache, must-revalidate" always;
    access_log off;
}

Важно:

Правило	Почему важно
Использовать alias	Так Nginx отдаёт файлы из нужной папки
alias должен заканчиваться /	Это нужно для корректного сопоставления путей
Не ставить долгий кеш	Файлы могут часто меняться вручную
Указывать frontend-папку	ng-custom относится к основному сайту, а не к backend

Порядок поиска SSR-файлов

SSR-файлы могут быть общими или языковыми.

Допустим:

язык страницы: en
язык по умолчанию: ru
файл: ssr-head.html

Система ищет файл в таком порядке:

public/ng-custom/en/ssr-head.html
public/ng-custom/ru/ssr-head.html
public/ng-custom/ssr-head.html
dist/.../browser/en/ng-custom/ssr-head.html
dist/.../browser/ru/ng-custom/ssr-head.html
dist/.../browser/ng-custom/ssr-head.html

Основное место для настройки:

public/ng-custom/

dist используется как резервный слой после сборки, а не как основное место ручной настройки.

Как добавить код для всех языков

Если код одинаковый для всех языков, используйте общий файл:

public/ng-custom/ssr-head.html

Пример:

<meta name="google-site-verification" content="token">

Как добавить код только для одного языка

Если код нужен только для английской версии, используйте:

public/ng-custom/en/ssr-head.html

Пример:

<meta name="custom-language" content="en">

Если код нужен только для русской версии:

public/ng-custom/ru/ssr-head.html

Важное отличие browser-файлов от SSR-файлов

Browser-файлы загружаются только из корня:

/ng-custom/client-scripts.js
/ng-custom/client-snippets.html

Они не загружаются автоматически из языковых папок:

/ng-custom/en/client-scripts.js
/ng-custom/ru/client-scripts.js

Если нужен разный browser-код по языкам, сделайте условие внутри общего client-scripts.js.

Пример:

window.IEX_CUSTOM_INIT = function (api) {
    api.onReady(function () {
        const lang = window.location.pathname.split('/')[1] || 'ru';

        if (lang === 'en') {
            api.loadScript('https://example.com/en-widget.js', {
                id: 'en-widget',
            });
            return;
        }

        api.loadScript('https://example.com/default-widget.js', {
            id: 'default-widget',
        });
    });
};

Подключение внешнего JavaScript

Если сервис дал код:

<script src="https://example.com/widget.js"></script>

лучше подключить его через client-scripts.js.

Пример:

window.IEX_CUSTOM_INIT = function (api) {
    api.onReady(function () {
        api.loadScript('https://example.com/widget.js', {
            id: 'example-widget',
            async: true,
            defer: true
        });
    });
};

id нужен, чтобы один и тот же скрипт не добавлялся повторно.

Подключение готового HTML-кода

Если сервис дал готовый блок:

<div id="support-chat"></div>
<script>
    window.supportChatId = 'client-123';
</script>
<script src="https://example.com/chat.js"></script>

добавьте его в:

client-snippets.html

Система сама вставит HTML в страницу и выполнит скрипты.

Подключение собственного CSS

Создайте CSS-файл:

public/ng-custom/custom.css

Затем подключите его в ssr-head.html:

<link rel="stylesheet" href="/ng-custom/custom.css">

После этого файл будет доступен по адресу:

/ng-custom/custom.css

---

Проверка работы

Проверьте, что файл отдаётся через Nginx:

curl -I https://example.com/ng-custom/client-scripts.js

Ожидаемый результат:

HTTP/2 200
Cache-Control: no-store, no-cache, must-revalidate

Проверьте SSR-вставки:

curl -s https://example.com/ru/ | grep "iex-custom"

Если SSR-вставка работает, в HTML будут маркеры:

<!--iex-custom:ssr-head:start-->
<!--iex-custom:ssr-head:end-->

Для body-start:

<!--iex-custom:ssr-body-start:start-->
<!--iex-custom:ssr-body-start:end-->

Для body-end:

<!--iex-custom:ssr-body-end:start-->
<!--iex-custom:ssr-body-end:end-->

---

Почему код не отображается

Проверьте:

Что проверить	Что должно быть
Папка	Создана public/ng-custom/ в основном frontend-сайте
ENV	Указан правильный CLIENT_CUSTOM_DIR
Browser Mode	CLIENT_CUSTOM_SCRIPTS_ENABLED=true
SSR Mode	CLIENT_CUSTOM_SSR_ENABLED=true
SSR-процесс	Перезапущен после изменения ENV
Nginx	alias указывает на правильную папку
Файл	Файл не пустой и содержит рабочий код
Домен	Проверяется основной сайт, а не app. домен админки

Что нельзя делать

Не редактируйте dist как основную папку настройки.

Не создавайте ng-custom в backend-проекте.

Не вставляйте полный HTML-документ:

<html>
<head></head>
<body></body>
</html>

Вставляйте только нужные фрагменты.

Не используйте тег:

<base>

Он может сломать ссылки и маршрутизацию сайта.

Не давайте доступ к папке ng-custom случайным пользователям, потому что JavaScript из этой папки выполняется на сайте.

Рекомендуемые сценарии

Задача	Куда вставлять
Онлайн-чат	client-scripts.js или client-snippets.html
Meta verification	ssr-head.html
JSON-LD	ssr-head.html
Noscript fallback	ssr-body-start.html
Внешний JS-файл	client-scripts.js
Готовый HTML-код сервиса	client-snippets.html
Собственный CSS	custom.css + подключение в ssr-head.html
Скрипт перед закрытием body	ssr-body-end.html

---

Итоговая схема

Основной сайт:

example.com

Рабочая папка для вставок:

public/ng-custom/

Публичный URL:

/ng-custom/

ENV:

CLIENT_CUSTOM_DIR=/полный/путь/к/public/ng-custom
CLIENT_CUSTOM_SCRIPTS_ENABLED=true
CLIENT_CUSTOM_SSR_ENABLED=true

Nginx:

location ^~ /ng-custom/ {
    alias /полный/путь/к/public/ng-custom/;
    try_files $uri =404;

    expires -1;
    add_header Cache-Control "no-store, no-cache, must-revalidate" always;
    access_log off;
}

Проверка:

curl -I https://example.com/ng-custom/client-scripts.js
curl -s https://example.com/ru/ | grep "iex-custom"

---

Коротко

ng-custom — это механизм для подключения пользовательских HTML, CSS и JavaScript-вставок на основном сайте iEXExchanger.

Он позволяет подключать сторонние сервисы, аналитику, онлайн-чаты, SEO-разметку и собственные скрипты без изменения исходного кода платформы и без пересборки Angular-приложения.