Интеграция вашей технологии с AMP
Благодарим вас за то, что интересуетесь участием в разработке AMP! Вместе мы способны трансформировать интернет в максимально удобную для пользователей среду.
Издатели создали уже более 1,4 млрд AMP-документов, размещенных на более чем 750 тысячах уникальных доменов. Подобный рост стал возможен только благодаря поддержке со стороны технологических компаний, интегрировавших свои сервисы с AMP, — таких компаний уже более 100.
Если вы провайдер технологий для интернет-издателей и рекламодателей, приглашаем вас добавить поддержку своих технологий в AMP. Ваши клиенты будут продолжать пользоваться вашей технологией, одновременно участвуя в построении «интернета будущего».
Данный документ описывает, что ожидается от третьих сторон при разработке интеграции с AMP, а также дает определение уровней интеграции.
Правила для разработчиков
Участие в разработке должно осуществляться в соответствии с универсальными инструкциями для участников проекта AMPHTML в CONTRIBUTING.md. Внешние участники должны тестировать, сопровождать и обновлять свой код в необходимом объеме.
Для возможности включения в проект код внешнего участника должен:
- Соответствовать критериям значимости англоязычной Wikipedia.
- Обеспечивать тот уровень обслуживания, который AMP обещает издателям и пользователям, или превышать его.
- Быть качественным.
- Сопровождаться каналом связи для диагностики и устранения неполадок.
- Предоставлять хорошее покрытие интеграционными тестами рабочих релизов и canary-релизов AMP.
- Реализовывать ранее не реализованную функциональность.
Для третьих сторон предусмотрено 3 уровня интеграции. Уровни различаются объемом добавляемой логики:
- Логика компонентов: код, определяющий ключевые возможности и функциональность AMP-компонента.
- Сторонняя логика: специфический код третьей стороны. Эта логика позволяет компоненту работать со сторонним сервисом.
Чем больше логики (в особенности сторонней) добавляется в репозиторий AMP, тем выше уровень интеграции.
На 1-м и 2-м уровнях интеграции третьи стороны используют общие компоненты. Если компонент, функциональность которого близка вашей бизнес-задаче, уже существует, рекомендуем использовать его. Это позволит существенно снизить объем работы и облегчить сопровождение кода в долгосрочной перспективе.
Чтобы начать, примите решение о том, какой уровень интеграции вам подходит, после чего создайте задачу на GitHub.
Интеграция 1-го уровня
В интеграции 1-го уровня используется функциональная логика существующих компонентов. Сторонняя логика загружается в виде пользовательского JavaScript в кроссдоменном элементе iframe. Например, многие рекламные сети предоставляют рекламу посредством компонента amp-ad, однако рендеринг рекламы контролируют с помощью собственной логики.
Авторы интеграции добавляют конфигурации или функции в существующие расширения, используя их API для реализации желаемой функциональности. Если подходящий компонент отсутствует, автор интеграции может предложить создать его.
Единственным элементом сторонней логики, добавляемым в репозиторий AMP, является файл конфигурации. Добавление новой стороны в существующую интеграцию 1-го уровня, как правило, не требует процесса дизайн-ревью — достаточно следовать инструкциям в документации по интеграции компонента (например, Интеграция рекламных сетей с AMP).
Что мы ожидаем от авторов интеграций
- Независимое сопровождение и обслуживание своего JavaScript-кода.
- Предоставление тестов для своей конфигурации и реагирование на проблемы.
- Предоставление разработчикам канала связи для диагностики неполадок.
- Реагирование на все сообщения об ошибках в интегрируемом сервисе.
Пример интеграции 1-го уровня
Провайдерам рекламы следует ознакомиться с разделами Обзор процесса разработки и Инструкции для разработчиков о добавлении поддержки своего сервиса в amp-ad. В зависимости от того, какую рекламную технологию предоставляет ваша компания, вам могут быть полезны данные инструкции по интеграции.
Поддержку связанных с рекламой функций, таких как amp-ad, уже добавили многие провайдеры рекламы. Вот пример пулреквеста из рекламной сети Criteo.
Интеграция 2-го уровня
В интеграции 2-го уровня используется функциональная логика существующих компонентов. Вся логика добавляется в репозиторий AMP, а загрузка пользовательского JavaScript-кода в iframe не допускается. Например, провайдеры аналитических сервисов добавляют свои конфигурации в компонент amp-analytics, однако указывают эндпойнт для отслеживания данных, например, кликов пользователей.
Для реализации нужной функциональности авторы интеграций добавляют конфигурации или возможности, такие как новые API, в существующие компоненты. Если подходящий компонент отсутствует, автор интеграции может предложить создать его.
Вся бизнес-логика добавляется в репозиторий AMP, однако из сторонней логики добавляются только файлы конфигурации. Если компонент работает с предоставленным третьей стороной файлом конфигурации, дизайн-ревью не требуется. Если сторонняя конфигурация реализует новую функциональность или новый компонент, она должна пройти дизайн-ревью AMP.
Что мы ожидаем от авторов интеграций
- Добавление стороннего сервиса в существующую интеграцию 2-го уровня, как правило, не требует проведения дизайн-ревью — достаточно следовать документации используемого компонента.
- Предложение нового компонента для интеграции 2-го уровня должно содержать функциональную логику, которая может также использоваться другими сторонними сервисами.
Примеры интеграции 2-го уровня
Аналитические инструменты AMP позволяют возвращать события на ваш сервер на основании настроенных вами триггеров. Чтобы начать работу с ними, ознакомьтесь с руководством по интеграции аналитических инструментов.
Если нужно просто добавить к определенному URL-адресу отслеживающий пиксель с динамическими параметрами, попробуйте amp-pixel. Не забудьте описать процедуру его использования в своей онлайн-документации — это пригодится разработчикам, желающим использовать вашу технологию в сочетании с AMP.
Ряд провайдеров аналитических сервисов добавили их поддержку в amp-analytics. Вот пример пулреквеста от провайдера аналитических сервисов Parse.ly.
Если вы предоставляете услуги аналитики звонков, вам может подойти компонент amp-call-tracking. Этот компонент динамически подменяет телефонный номер в гиперссылке, чтобы дать возможность отслеживать звонки путем выполнения CORS-запроса, меняющего номер.
Чтобы подробнее узнать, чем вам может быть полезен этот компонент, ознакомьтесь с его справочной документацией.
Интеграция 3-го уровня
На 3-м уровне интеграции предусмотрено создание специального компонента для третьей стороны, но только при условии, если автор интеграции не может:
- Найти существующий компонент, подходящий для своего сценария.
- Запросить усовершенствование существующих функций для соответствия своему сценарию.
- Предложить компонент, который также подходит другим сторонним сервисам.
Что мы ожидаем от авторов интеграций
- Написание и предложение дизайн-ревью.
- Тесты должны фиксировать поломки.
- При нарушении работы компонента — исправление или запрос помощи.
- Исчерпывающая документация с примерами кода.
- Сопровождение и обновление документации.
- Канал связи для AMP-разработчиков для диагностики неполадок и обращения за помощью.