“Яндекс.Метрика” — Документация docs.cs-cart.ru 4.13.x

Предыдущая статья Следующая статья

• Возможности
• Установка и настройка
  • Шаг 1. Создание и настройка счётчика
  • Шаг 2. Получение API Яндекс.Метрики
  • Шаг 3. Настройка модуля “Яндекс.Метрика”
• Что делать, если Яндекс.Метрика не работает?

Модуль “Яндекс.Метрика” позволяет связать ваш магазин с одноимённым сервисом “Яндекс.Метрика”. Подробнее о том, какие возможности даёт этот сервис, а также обо всех настройках на стороне Яндекс.Метрики, вы можете прочитать в Яндекс.Справке.

Важно

Установите модуль “Яндекс.Метрика” в ваш магазин так же, как и любой другой модуль.

Настройте Яндекс.Метрику в три шага:

Шаг 1. Создание и настройка счётчика

1. Откройте страницу Яндекс.Метрики и авторизуйтесь.

2. Нажмите кнопку Добавить счётчик.

3. На вкладке “Задайте настройки” заполните необходимые поля:

   • Имя счётчика — введите название счётчика.
   • Адрес сайта — введите адрес вашего магазина.
   • Часовой пояс — выберите ваш часовой пояс.

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

5. Поставьте галочку согласия с условиями пользовательского соглашения и нажмите Создать счётчик.

6. На вкладке “Установите код счетчика на сайт” переключитесь на вкладку CMS и конструкторы сайта.

7. Скопируйте код счётчика — его необходимо будет указать в настройках модуля “Яндекс.Метрика”. Также его можно скопировать со страницы с детальной информацией о счётчике.

8. Пролистайте вниз и нажмите Начать пользоваться.

Шаг 2. Получение API Яндекс.Метрики

Для того, чтобы получить API Яндекс.Метрики, вам необходимо зарегистрировать приложение на Яндекс.

OAuth.

1. На странице создания приложения заполните необходимые поля:

   • Название приложения — введите название приложения.
   • Описание приложения — введите краткое описание вашего приложения.
   • Ссылка на сайт приложения — укажите ссылку на сайт вашего магазина.

2. В разделе “Платформы” выберите Веб-сервисы.

3. В поле Callback URI #1 введите Callback URI из настроек модуля “Яндекс.Метрика”.

4. В разделе “Доступы” найдите Яндекс.Метрику и включите все доступы.

5. Нажмите Создать приложение. Откроется страница с информацией о вашем приложении. Данные с этой страницы понадобятся вам в следующем шаге по настройке модуля.

Шаг 3. Настройка модуля “Яндекс.Метрика”

1. В панели администратора откройте страницу Модули → Управление модулями.

2. Найдите в списке модуль “Яндекс. Метрика” и нажмите на название модуля, чтобы открыть его настройки.

3. Настройте модуль:

   • Общие:

     • Номер счетчика — укажите номер счётчика, который вы создали на сайте Яндекс.Метрики.
     • Устаревший код счётчика — поставьте галочку, если хотите использовать устаревший код счётчика и предыдущую версию Вебвизора.

   • Настройки и Дополнительные настройки — выберите сервисы, которые хотите использовать.

   • Доступ к API Яндекса:

     • ID приложения — укажите ID приложения, которое вы создали в предыдущем шаге.

     • Пароль приложения — укажите пароль от вашего приложения.

   • Цели — выберите, по каким целям хотите собирать статистику. Выбранные цели настроятся в вашем счётчике автоматически.

4. В настройках модуля нажмите Сохранить.

5. В разделе “Доступ к API Яндекса” нажмите Обновить токен, затем авторизуйтесь.

Если счётчик Яндекс.Метрики не собирает информацию о вашем магазине или цели не появились автоматически в вашем счётчике, попробуйте выполнить следующие действия:

• Проверьте правильность кода счётчика.
• Проверьте, правильно ли указаны ID и пароль приложения.
• Обновите токен в настройках модуля “Яндекс.Метрика”.
• Подождите некоторое время. Яндекс.Метрика подгружает данные с некоторой задержкой.

Инструкция, как настроить счетчик Метрики

Наверняка вы уже знаете, что счетчик Метрики необходимо установить на сайте для отслеживания бизнес-показателей: источники трафика, время на сайте, глубина просмотра, конверсия и т. д. Это открывает возможности глубокого анализа эффективности работы ресурса и своевременного внесения корректировок. Большой плюс в том, что абсолютно бесплатный счетчик дает обширную статистику.

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

Настройка счетчика и целей в Яндекс.Метрике

В первую очередь необходимо создать аккаунт в Яндексе (или авторизоваться в существующем) и перейти на страницу самого сервиса.

Для новых пользователей на данной странице автоматически выбрано меню «Счетчики», в котором следует нажать на кнопку «Добавить счетчик»:

Важно! Счетчик – это представление сайта внутри Метрики, т.е. место, где будут храниться все данные о сайте. Если у вас несколько сайтов, то для каждого сайта нужно создавать отдельный счетчик, чтобы статистика собиралась и отображалась корректно. В противном случае данные будут смешиваться.

После клика по кнопке «Добавить счетчик» видим следующую форму:

Заполняем поля формы:

1. Имя счетчика — удобнее всего указать название сайта, чтобы потом не путаться при создании других счетчиков.
2. Адрес сайта — указываем URL сайта.
3. Дополнительные адреса — если вы хотите собирать общие данные по нескольким сайтам, то добавьте их здесь.
4. Часовой пояс — выберите часовой пояс региона, в котором работает ваша компания.
5. Валюта — указываем валюту, в которой хотим видеть данные о товарах.
6. Тайм-аут визита в минутах — время бездействия посетителя на сайте, по истечении которого визит будет считаться завершенным (например, человек открыл ваш сайт, а потом вышел на кухню и забыл, что работал за компьютером, время визита идет, а визита по факту нет). Лучше оставить значение по умолчанию.

В итоге получится вот так:

Вкладка «Код счетчика»

Вкладка выбрана автоматически и на ней мы видим список параметров:

Выбираем пункт «Вебвизор, карта скроллинга, аналитика форм», который откроет нам доступ к картам и вебвизору. Другие опции очень специфичны и могут вам никогда не понадобиться, поэтому о них можно почитать в справке Яндекса.

Прокручиваем страницу вниз и обязательно нажимаем на кнопку «Сохранить».

Внизу видим код нашего счетчика, который необходимо разместить на всех страницах сайта в HTML-коде (желательно в начале тега <body>):

Важно! Каждый раз, когда вы вносите изменения в настройки счетчика на данной вкладке, необходимо нажать кнопку «Сохранить» и после этого заменять код счетчика на сайте.

Вкладка «Фильтры»

Устанавливаем галочку «Не учитывать мои визиты», чтобы собирались более чистые данные по вашим посетителям, без учета вашей активности на сайте, и нажимаем на кнопку «Сохранить».

Если не выбрать данный фильтр, то в отчетах, скорее всего, будут высокие отказы по прямым заходам или, наоборот, показатели «время на сайте» или «количество просмотренных страниц» буду слишком высокими. Не надо думать, что ваши визиты могут дополнить статистику. Владельцы взаимодействуют с сайтом немного по-другому, чем клиенты.

Для пункта «Фильтрация роботов» параметр лучше оставить по умолчанию.

Вкладка «Уведомления»

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

Не забудьте сохранить введенные данные.

Готово! Основные настройки счетчика выполнены и его код можно устанавливать на сайт.

Важно! Для корректного сбора данных код должен быть на каждой странице сайта. Код начинает собирать данные сразу после добавления на сайт.

Вкладка «Цели»

Цель настраивается на конкретное действие пользователя на сайте, например, посещение страницы, нажатие кнопки, загрузка файла и т. д. Главное – отслеживать те действия, которые приносят пользу именно вашему бизнесу.

Обратите внимание, что нет какого-либо стандартного набора целей. Все индивидуально и зависит от задач, которые вы ставите перед сайтом. Сейчас рассмотрим основные виды целей, из которых вы сможете выбрать подходящий вариант.

Цели можно в любое время добавлять, редактировать или удалять, но мы рекомендуем сразу настроить их для всех конверсионных элементов и/или страниц. Это позволит избежать нехватки данных в будущем.

В Метрике доступно 4 вида целей, которые вы можете найти во вкладке «Цели» (кликаем на кнопку «Добавить цель»):

1. Посещение страниц – цель, выбранная по умолчанию. Позволяет отслеживать количество посетителей для одной или набора страниц (до 10). Также можно анализировать переходы на внешние сайты или загрузку файлов.
   Например, мы хотим узнать, сколько пользователей заходит на страницу контактов: https://1ps.ru/contacts/. Для этого:
   1. Указываем понятное нам название цели «Посещение страницы контактов». Пишите подробные названия, чтобы потом было легче вспомнить, для чего создавалась цель.
   2. Затем в поле «Условие» выбираем «url: содержит» и справа указываем полный адрес страницы. Если же у нас раздел с контактной страницей делится на подразделы и мы не хотим, чтобы собирались данные по подразделам, лучше выбрать параметр «url: совпадает».
   3. Сохраняем цель, нажав на кнопку «Добавить цель».

   На первый взгляд цель простая, но отлично работает для таких событий, как:

   • Посещение страницы подтверждения заказа (для интернет-магазина) или регистрации.
   • Скачивание файла (например, прайс-листа или презентации).
   • Посещение страницы с информацией для партнеров или списком дилеров.
   • Добавление комментария или отзыва.
   • Посещение страницы с подтверждением подписки на рассылку и др.

   Такую цель вы можете настроить без помощи программиста. Но из-за привязки к адресу страницы – это вариант цели не подойдет для неуникальных страниц.

2. Количество просмотров – эта цель позволяет выбрать тех пользователей, которые просмотрели указанное количество страниц. Необходима для оценки глубины просмотра сайта.

   Например, укажем 5 страниц, чтобы отслеживать количество пользователей, которые просмотрели 5 и более страниц сайта. Не забываем указывать название цели и нажимать на кнопку «Добавить цель».

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

3. JavaScript-событие – цель, позволяющая отслеживать выполнение событий: клик по кнопке, заполнение формы, просмотр видео и т. д. Для задания цели в поле «Идентификатор цели» указывается уникальный параметр, который с помощью функции «reachGoal» вызывается в коде элемента на сайте.

   Например, мы бы хотели отследить для страницы продажи аудитов https://1ps.ru/cost/audit/ количество кликов по кнопке «Получить совет эксперта» и поэтому укажем параметр sovet следующим образом:

   Затем, чтобы данные о цели засчитались, на сайте в коде элемента необходимо добавить функцию с нашим параметром:

   yaCounter12345678. reachGoal(‘sovet’), где 12345678 – номер вашего счетчика, который указан вверху страницы Метрики:

   Важно! Для каждого элемента идентификатор должен быть уникальным и совпадать с соответствующим параметром в коде сайта. Идентификаторы не должны содержать такие же слова, как и в адресе страницы, а также спецсимволы: /, &, #, ?, =.

   Минус в том, что если вы не знаете, как внести изменения в код вашего сайта, то придется привлечь соответствующего специалиста (что может занять время). Но зато данная цель не привязана к адресу страницы, позволяет отслеживать несколько действий на одной странице.

4. Составная цель – подходит для отслеживания последовательности действий. Чаще всего используют для анализа процесса заказа товара или оформления заявки на услугу.

   Например, для заказа товара составим примерный порядок шагов:

   1. Переход на страницу корзины – url: начинается с https://site. ru/cart
   2. Заполнение формы заказа – идентификатор zakaz
   3. Переход на страницу подтверждения заказа – url: совпадает https://site.ru/success

   Название и количество шагов может различаться, зависит от сайта. Для данной цели рекомендуем для каждого шага указывать название, для идентификаторов необходимо добавить соответствующие функции в код сайта.

   В Метрике форма заполняется следующим образом:

   Данная цель как некий конструктор, где каждый шаг это цель вида «Посещение страниц» или «JavaScript-событие». В отчетах вы также сможете увидеть данные отдельно по каждому шагу. Максимальное количество шагов – 5, поэтому если у вас на сайте процесс выполняется в больше этапов, то стоит разбить его на несколько составных целей.

   Важно! Шаги должны быть связаны и выполнятся подряд: если можно выполнить третий шаг, минуя второй, то такая последовательность не засчитается. В таком случае придется создавать отдельную цель для каждого сценария.

В целом по составлению целей стоит знать о следующих особенностях:

• Для одного счетчика можно создать не более 200 целей.
• При изменении цели накопленные данные не пересчитываются.
• При удалении цели данные не сохраняются.

Отчет по целям

Общие данные по конверсии для всех настроенных целей доступны в отчете «Конверсии».

И результаты будут выглядеть следующим образом:

Каждую цель можно «раскрыть» для более подробного анализа информации.

Составная цель будет выглядеть следующим образом:

Если нажать на знак воронки рядом с названием,

можно получить пошаговый отчет в виде воронки:

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

Заключение

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

Для закрепления информации также рекомендуем прочитать нашу книгу «Бизнес аналитика. Ни шагу без Яндекс.Метрики» и посмотреть вебинар.

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

Экспорт данных из Яндекс Метрики через Logs API

Статьи Яндекс Метрики

yandex metrica

с бесплатным готовым рабочим пространством Postman

Logs API предназначен для получения неагрегированных данных , хранящихся в Яндекс Метрике. Кто-то может также назвать это сырыми данными, но на самом деле это слегка преобразованные* данные.
* автор этой статьи предполагает, что YM работает с расширенными наборами данных, недоступными для экспорта.

Веб-аналитики могут столкнуться с трудностями при получении данных через API, поскольку для этого требуются некоторые технические навыки, которые редко требуются в их повседневной работе. Эта статья представляет собой пошаговое руководство в помощь всем, у кого нет опыта и навыков работы с API (Application Programming Interface).

Зачем использовать Logs API

• Свободное владение данными, с которыми вы работаете. Если вы понимаете, какие данные собираются и как они хранятся, вы повышаете свою профессиональную компетентность и расширяете видение возможных сценариев измерения и анализа аналитики.

• Для запуска анализа данных за пределами возможностей отчетности Метрики. Даже для устранения неполадок, потому что иногда трудно понять, почему отчеты Метрики возвращают это вместо то . Например, как он считает пользователей.

• Чтобы помочь вашим дружественным дата-инженерам обогатить DWH или Data Lake данными Metrica. Им нужно будет понимать структуру данных, варианты подключения и многие другие аспекты того, как использовать данные веб-аналитики. Имея хотя бы общее представление о том, что такое журналы, вы сможете эффективно сотрудничать с командой во время проекта.

• Расширяя предыдущий пункт, если вы инженер данных или член команды, создающей что-то надежное на основе данных YM, то Logs API — это обязательный строительный блок, который вы должны хорошо знать.

Предоставление доступа

Начнем с получения учетных данных для подключения к Logs API, так как доступ, предоставляемый для запуска отчетов в пользовательском интерфейсе Метрики, недостаточен.

Откройте эту страницу https://yandex.com/dev/metrika/ и нажмите «Получить токен доступа OAuth» (или просто перейдите по этому URL https://oauth.yandex.com/client/new ).

Вы будете перенаправлены на страницу авторизации Яндекса, войдите в систему, используя свои обычные учетные данные, которые вы используете для пользовательского интерфейса отчетности Метрики (учетная запись Яндекса), если вы еще не прошли аутентификацию.

Заполните форму:

1. Имя службы — так учетные данные будут отображаться в дальнейшем. Например, вы можете ввести «Яндекс Метрика — название вашей компании».

2. Установите флажок Веб-службы и нажмите на синюю ссылку, расположенную под полем URL обратного вызова, чтобы заполнить его значением по умолчанию, как показано на скриншоте https://oauth.yandex.com/verification_code

3. Прокрутите список услуг, пока не найдете Яндекс.Метрику, разверните его и поставьте галочку « Доступ к статистике и возможность просмотра всех настроек счетчика «. Этого будет достаточно для получения отчетов и экспорта данных через Logs API.

4. Прокрутите страницу до самого конца и по желанию заполните другие поля. Например, имеет смысл добавить некоторые комментарии в Описание в качестве напоминания о том, для чего будет использоваться эта служба (учетные данные)
Нажмите Создать приложение , чтобы завершить настройку

Вы получите подтверждение об успешном создании приложения и информация, необходимая для установления соединения через Logs API:
— ClientID (*не путать с ClientID, используемым для идентификации посетителей в YM)
— Секрет клиента

Когда вам нужно вернуться на эту страницу (к учетным данным приложения), используйте эту ссылку https:/ /oauth. yandex.com

Postman

Если вы никогда не работали с API, советую использовать Postman. Он доступен в виде приложения как для Windows, так и для macOS.

Использовать общедоступное рабочее пространство для работы с API Яндекс Метрики по этой ссылке
https://www.postman.com/andreyosadchuk/workspace/y…

Он настроен с двумя средами — демонстрационной и другой для вашего личного тега. Поэтому, если у вас нет данных в собственном теге, вы можете подключиться к тегу Demo.

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

Настроим окружение.
Если вы не использовали Postman, имейте в виду, что все, что вы будете вводить, останется с вами, ничего никому не будет передано по замыслу, вы просто используете предварительно настроенный шаблон.

1. Выберите Environments, выберите «Yandex Metrica My Test Counter» (переименовать можно после создания копии рабочей области под учетной записью Postman)
2. Заполнить ячейки таблицы в столбце ТЕКУЩЕЕ ЗНАЧЕНИЕ:
yandex_client_id: ClientID
yandex_access_token: Секрет клиента
yandex_counter_id: Номер тега Яндекс Метрики, к которому вы хотите подключиться

Затем перейдите в Коллекции, чтобы открыть список предварительно настроенных методов для использования Yandex Metrica Logs API.

• Evaluate — проверяет, может ли запрос, который вы собираетесь запланировать, быть обработан Яндексом вообще (возможно ли запустить такой экспорт данных?)
• Создать — создает запрос (задание) на данные экспорт
• GetInfo — возвращает статус для данного запроса, чтобы проверить, доступны ли данные для загрузки или они еще готовятся
• GetList — возвращает информацию обо всех запросах
• Скачать — загрузить успешно обработанные запросы
• Очистить — удалить ранее созданный запрос

Начать работу с Logs API

Нажать на кнопку Создать и заполнить таблицу:

3 90 имя таблицы (либо посещения, либо просмотры)

• дата1 — первая дата отчетного периода
• дата2 — последняя дата отчетного периода
• поля — список полей (параметры и показатели) через запятую. По умолчанию значение сопоставляется с переменной среды для извлечения всех полей. Не изменяйте его, если не хотите сузить вывод.

Выберите свою среду (в правом верхнем углу).

Нажмите Отправить .

Вы увидите ответ, как показано ниже:

Это означает, что запрос был успешно получен и теперь он готовится. Скопируйте назначенный request_id.

Теперь нужно немного подождать, пока данные будут готовы к загрузке.
Переключитесь на GetInfo , заполните ЗНАЧЕНИЕ с request_id и нажмите Отправить.

Когда данные будут готовы к загрузке, вы увидите в ответе «статус»: «обработано» . Если набор данных, подготовленный по запросу, относительно большой, он будет разделен на несколько частей. Проверьте, сколько частей указано в ответе (массив «parts», а внутри «part_number», начиная с нуля).

Перейти к загрузке.
Введите request_id и part_number .

Затем откройте раскрывающееся меню рядом с кнопкой «Отправить» и нажмите « Отправить и загрузить ».

Сохраните ответ в виде текстового файла, поскольку Logs API возвращает данные в формате текстового файла с разделителями табуляции (также известного как .tsv).

Я не буду рассматривать другие методы, доступные в коллекциях рабочей области, поскольку они говорят сами за себя. Вот ссылка на документацию Logs API, объясняющую все методы запроса.

Обсудить в Telegram

ng-yandex-metrika — npm

Краткий старт находится в активной разработке и еще не доработан.

Может быть не полностью совместим с текущими версиями Angular.

Это простой быстрый запуск библиотеки Angular, реализующий Угловой формат пакета v4.0.

В настоящее время поддерживаются только основные библиотеки точек входа без области.

Особенности:

• простой пример библиотеки
Модульные тесты
• для библиотеки
• демонстрационное приложение, которое использует библиотеку в режиме JIT и работает в режиме просмотра
• приложение для интеграции, которое использует библиотеку в режиме JIT и AOT и запускает тесты e2e

Общие задачи представлены в виде сценариев npm:

• npm start для запуска сервера с перезагрузкой в ​​реальном времени с демонстрационным приложением
• npm run test для проверки в режиме наблюдения или npm run test:once для запуска только один раз
• npm run build для сборки библиотеки
• н/мин запустить lint до lint
• н/мин от очистки до очистки
• npm run Integration для запуска интеграционных тестов e2e
• npm install ./relative/path/to/lib после npm run build для локального тестирования в другом приложении

Если вам нужно отладить приложение интеграции, проверьте . /integration/README.md .

Библиотека быстрого запуска seed

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

Любая установка, создающая необходимый формат пакета, подходит и для потребителя. Вам предлагается настроить этот процесс по своему усмотрению.

При разработке собственной установки помните, что даже если AOT предпочтительнее, должна поддерживаться своевременная компиляция.

Убедитесь, что у вас установлены как минимум Node 6.9 и NPM 3.0. Потом…

1. Создайте папку проекта (вы можете назвать ее quickstart-lib и переименовать позже).
2. Клонируйте или загрузите начальное число библиотеки QuickStart в папку вашего проекта.
3. Установить пакеты npm.
4. Запустите npm start , чтобы запустить пример приложения.

Клонирование

Выполните шаги клонирования для запуска с помощью этих команд терминала.

 клон git https://github.com/filipesilva/angular-quickstart-lib.git
cd angular-quickstart-lib
установка нпм
запуск нпм
 

Загрузить

Загрузить начальное число библиотеки QuickStart и разархивируйте его в папку вашего проекта. Затем выполните оставшиеся шаги с этими командами терминала.

 cd angular-quickstart-lib
установка нпм
запуск нпм
 

Инициализируйте свой репозиторий

Если вы клонировали пакет с github, у него есть папка .git , в которой хранится история официального репозитория.

Вам не нужна эта история git — вы захотите создать свою собственную.

Удалите эту папку и инициализируйте ее как новый репозиторий:

 rm -rf .git # Linux или OS/X (bash)
rd .git /S/Q # Windows
git инициировать
 

Предупреждение : Делайте это только в начале, чтобы случайно не удалить свою собственную настройку git!

Что содержится в исходном коде библиотеки QuickStart?

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

Следовательно, в проекте много разных файлов . Сосредоточьтесь на следующих файлах TypeScript ( .ts ) в папке /src .

 источник/
├── демо/
| └── приложение/
| ├── app.component.ts
| └── app.module.ts
└── библиотека/
   ├── index.ts
   └── источник/
      ├── компонент/
      | └── lib.component.ts
      ├── обслуживание/
      | └── lib.service.ts
      └── module.ts
 

Каждый файл имеет свое назначение и развивается независимо по мере роста приложения.

Файлы за пределами src/ касаются сборки, развертывания и тестирования вашего приложения. Они включают файлы конфигурации и внешние зависимости.

Файлы внутри src/lib/ «принадлежат» вашей библиотеке, а src/demo/ содержит демонстрационное приложение который загружает вашу библиотеку.

Библиотеки не запускаются сами по себе, поэтому очень полезно иметь это «демонстрационное» приложение при разработке чтобы увидеть, как ваша библиотека будет выглядеть для потребителей.

При запуске npm start , демонстрационное приложение запущено.

Следующее все в src/

Файл	Цель
демо/приложение/app.component.ts	Демонстрационный компонент, отображающий библиотечный компонент и значение из библиотечной службы.
демо/приложение/приложение.модуль.тс	Демо NgModule , который импортирует библиотеку LibModule .
lib/src/component/app.component.ts	Пример компонента библиотеки, отображающий тег h3 .
lib/src/service/lib.service.ts	Пример службы библиотеки, которая экспортирует значение.
lib/src/module. ts	Основные библиотеки NgModule , LibModule .
библиотека/index.ts	Общедоступный API вашей библиотеки, где вы выбираете, что экспортировать потребителям.

Этап сборки

Вы можете собрать библиотеку, запустив npm run build . Это создаст каталог dist/ со всеми точками входа, описанными выше.

Всю логику создания сборки можно найти в ./build.js . Он состоит примерно из 5 шагов:

• Компиляция с помощью компилятора AOT (компилятор AOT или ngc ) для ES5 и ES2015.
• Встраивание html и css в сгенерированные файлы JavaScript.
• Типы копий, метатады, html и css.
• Создайте каждый пакет с помощью Rollup.
• Копировать ЛИЦЕНЗИЯ , package.json и README.md файлы

Тестирование библиотек

Хотя тестирование всегда важно, особенно важно в библиотеках, поскольку потребитель приложения могут ломаться из-за ошибок в библиотеках.

Но тот факт, что библиотека используется другим приложением, затрудняет ее тестирование.

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

Исходное число библиотеки QuickStart включает каталог с именем Integration , содержащий автономный приложение, которое использует вашу встроенную библиотеку в режимах AOT и JIT со сквозными тестами для проверки оно работает.

Чтобы запустить интеграционные тесты, выполните команду npm run Integration , которая выполняет следующие действия:

• Создайте свою библиотеку.
• Войдите в каталог приложения интеграции.
• Установить зависимости.
• Создайте приложение в режиме AOT.
• Протестируйте приложение в режиме AOT.
• Протестируйте приложение в режиме JIT.

Выполнение интеграционных тестов дает вам больше уверенности в правильности сборки вашей библиотеки.

В дополнение к интеграционным тестам вы также можете запускать модульные тесты в режиме просмотра через npm run test , или одиночный запуск через npm run test:once .

Вы также можете протестировать свою библиотеку, установив ее в другой имеющийся у вас локальный репозиторий. Для этого сначала соберите свою библиотеку через .npm запустить сборку . Затем установите его из другого репо, используя относительный путь к папке dist: npm установить относительный/путь/к/библиотеке/расстояние .

Публикация вашей библиотеки

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

Используйте свой редактор для поиска в проекте всех экземпляров quickstart-lib и измените его на предполагаемое имя (также в тире-регистр 9формат 0250). Имя библиотеки упоминается как минимум в следующих файлах:

• Integration/src/app/app.component.ts
• интеграция/src/app/app.module.ts
• интеграция/src/systemjs.config.js
• интеграции/package.json
• src/demo/app/app.component.ts
• src/demo/app/app.module.ts
• src/demo/systemjs.config.js
• источник/демо/tsconfig.json
• источник/библиотека/tsconfig.es5.json
• источник/библиотека/tsconfig.lib.json
• bs-config.json
• package.json
• README.md

Вам также потребуется переименовать папку, в которой находится ваш проект.

После того, как вы изменили имя пакета, вы можете опубликовать его в NPM (читать эту ссылку для деталей).

Вместо того, чтобы следовать Обновление пакета в предыдущем документе, здесь мы используем стандартная версия. Прочитайте их документы, чтобы узнать, как его использовать.

Сначала вам нужно создать учетную запись NPM и войти на свой локальный компьютер. Затем вы можете опубликовать свой пакет, запустив npm publish dist/ .
Поскольку ваш пакет создан в папке dist/, вы должны опубликовать ее.

Быть хорошим специалистом по обслуживанию библиотек

Теперь, когда вы опубликовали библиотеку, вам также необходимо поддерживать ее. Ниже приведены некоторые из наиболее важных пунктов:

• Документируйте свою библиотеку.
• Следите за системой отслеживания проблем.
• Правильно управляйте своими зависимостями
• Следуйте семантическим версиям
• Настройте решение для непрерывной интеграции для тестирования вашей библиотеки (в комплект входит .travis.yml файл для Travis CI)!
• Выберите соответствующую лицензию.

Приложение: Поддержка AOT

AOT играет важную роль в оптимизации приложений Angular. Поэтому важно, чтобы сторонние библиотеки публиковались в формате, совместимом с AOT. компиляция. В противном случае включить библиотеку в скомпилированное приложение AOT будет невозможно.

Только код, написанный на TypeScript, может быть скомпилирован AOT.

Перед публикацией библиотеку необходимо сначала скомпилировать с помощью компилятора AOT ( ngc ). ngc расширяет компилятор tsc , добавляя расширения для поддержки компиляции AOT в дополнение к обычная компиляция TypeScript.

При компиляции AOT выводятся три файла, которые необходимо включить для обеспечения совместимости с AOT.

Транспилированный JavaScript

Как обычно, исходный TypeScript транспилируется в обычный JavaScript.

Файлы типов

В JavaScript нет способа представления типов. Чтобы сохранить исходные типизации, ngc создаст файлы типизации .d.ts .

Файлы метаданных JSON

ngc выводит файл metadata. json для каждого компонента и NgModule . Эти файлы метаданных представляют собой информацию в исходном NgModule и Component . декораторы.

Метаданные могут ссылаться на внешние шаблоны или файлы css. Эти внешние файлы должны быть включены в библиотеку.

NgFactory

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

Вместо этого компилятор ngc в приложении-потребителе создаст файлы .ngfactory на основе на JavaScript, типизациях и метаданных, поставляемых с библиотекой.

Почему бы не опубликовать TypeScript?

Почему бы вместо этого не отправить исходный код TypeScript? В конце концов, библиотека будет частью другого шага компиляции TypeScript, когда библиотека импортируется потребляющим приложением.

Обычно не рекомендуется поставлять TypeScript со сторонними библиотеками. Потребителю потребуется воспроизвести полную среду сборки библиотеки. Не только типизация, но и, возможно, конкретная версия ngc .

Публикация простого JavaScript с типизацией и метаданными позволяет потребляющему приложению не зависеть от среды сборки библиотеки.

Приложение: Поддержка JIT

Скомпилированный код AOT является предпочтительным форматом для производственных сборок, но из-за длительной компиляции время может быть нецелесообразно использовать AOT во время разработки.

Для создания более гибкого интерфейса разработчика должна быть JIT-совместимая сборка библиотеки. также опубликовано. Формат пакета JIT — umd , что означает определение универсального модуля. Доставка пакета как umd обеспечивает совместимость с наиболее распространенными форматами загрузки модулей.

Пакет umd будет поставляться в виде единого файла, содержащего ES5 JavaScript и встроенные версии любые внешние шаблоны или css.

Приложение: Управление зависимостями

Специалисту по обслуживанию библиотеки важно правильно управлять своими зависимостями в package.json .

Существует три вида зависимостей: зависимостей , devDependencies и peerDependencies .

• зависимостей 902:50: здесь идут все остальные библиотеки, от которых зависит ваше использование. Хороший способ выяснить это - просмотреть исходный код вашей библиотеки (в src/lib только ) и перечислите все библиотеки там.
• devDependencies : библиотеки, которые вам понадобятся при разработке, тестировании и создании вашей библиотеки. иди сюда. Когда пользователь устанавливает вашу библиотеку, они не будут установлены. Пользователям не нужно разрабатывать, создавать или тестировать вашу библиотеку, им просто нужно запустить ее.
• peerDependencies : они аналогичны зависимостям , поскольку ваша библиотека ожидает, что они будут там во время выполнения. Разница в том, что вы не хотите устанавливать их новую версию, а вместо этого используете тот, что уже есть.

Хорошим примером одноранговой зависимости является @angular/core и все остальные основные библиотеки Angular. Если вы перечислили эти зависимостей , то новый - с другой версией! - можно было установить для использования вашей библиотекой. Хотя это не то, что вы хотели. Вы хотите, чтобы ваша библиотека использовала точно такой же @angular/core которое использует приложение.

Обычно вы будете использовать библиотеки @angular/* , перечисленные как в devDependencies , так и в одноранговые зависимости . Это нормально и ожидаемо, потому что при разработке вашей библиотеки также потребуется копия их установили.

Еще одна вещь, о которой следует помнить, это не допускать слишком неожиданных изменений ваших зависимостей. Различные версии библиотек могут иметь разные функции, и если вы случайно снисходительны к разрешенным версиям, ваша библиотека может перестать работать из-за изменения зависимости.