AMP

Интеграция вашей технологии с 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. В зависимости от того, какую рекламную технологию предоставляет ваша компания, вам могут быть полезны данные инструкции по интеграции.

Поддержку связанных с рекламой функций, таких как amp-ad, уже добавили многие провайдеры рекламы. Вот пример пулреквеста из рекламной сети Criteo.

Интеграция 2-го уровня

В интеграции 2-го уровня используется функциональная логика существующих компонентов. Вся логика добавляется в репозиторий AMP, а загрузка пользовательского JavaScript-кода в iframe не допускается. Например, провайдеры аналитических сервисов добавляют свои конфигурации в компонент amp-analytics, однако указывают эндпойнт для отслеживания данных, например, кликов пользователей.

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

Вся бизнес-логика добавляется в репозиторий AMP, однако из сторонней логики добавляются только файлы конфигурации. Если компонент работает с предоставленным третьей стороной файлом конфигурации, дизайн-ревью не требуется. Если сторонняя конфигурация реализует новую функциональность или новый компонент, она должна пройти дизайн-ревью AMP.

Что мы ожидаем от авторов интеграций

  • Добавление стороннего сервиса в существующую интеграцию 2-го уровня, как правило, не требует проведения дизайн-ревью — достаточно следовать документации используемого компонента.
  • Предложение нового компонента для интеграции 2-го уровня должно содержать функциональную логику, которая может также использоваться другими сторонними сервисами.

Примеры интеграции 2-го уровня

amp-analytics

Аналитические инструменты AMP позволяют возвращать события на ваш сервер на основании настроенных вами триггеров. Чтобы начать работу с ними, ознакомьтесь с руководством по интеграции аналитических инструментов.

Если нужно просто добавить к определенному URL-адресу отслеживающий пиксель с динамическими параметрами, попробуйте amp-pixel. Не забудьте описать процедуру его использования в своей онлайн-документации — это пригодится разработчикам, желающим использовать вашу технологию в сочетании с AMP.

Ряд провайдеров аналитических сервисов добавили их поддержку в amp-analytics. Вот пример пулреквеста от провайдера аналитических сервисов Parse.ly.

amp-call-tracking

Если вы предоставляете услуги аналитики звонков, вам может подойти компонент amp-call-tracking. Этот компонент динамически подменяет телефонный номер в гиперссылке, чтобы дать возможность отслеживать звонки путем выполнения CORS-запроса, меняющего номер.

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

Интеграция 3-го уровня

На 3-м уровне интеграции предусмотрено создание специального компонента для третьей стороны, но только при условии, если автор интеграции не может:

  • Найти существующий компонент, подходящий для своего сценария.
  • Запросить усовершенствование существующих функций для соответствия своему сценарию.
  • Предложить компонент, который также подходит другим сторонним сервисам.

Что мы ожидаем от авторов интеграций

  • Написание и предложение дизайн-ревью.
  • Тесты должны фиксировать поломки.
  • При нарушении работы компонента — исправление или запрос помощи.
  • Исчерпывающая документация с примерами кода.
  • Сопровождение и обновление документации.
  • Канал связи для AMP-разработчиков для диагностики неполадок и обращения за помощью.