# **AppsFlyer Web SDK — промпт для ИИ-внедрения**

Скопируйте промпт ниже в ИИ-инструмент для написания кода, который может редактировать ваш проект (Cursor, Claude Code, Codex, Copilot). Перед копированием замените два плейсхолдера:

  - <WEB_SDK_ID> — в AppsFlyer перейдите в Мои приложения, выберите свое веб-приложение (ваш домен с префиксом website-) и скопируйте Web SDK ID (также называется Web Dev Key) из раздела Аутентификация SDK.
  - <PRODUCTION_URL> — URL-адрес вашего сайта, который используется для проверки после развертывания.

Внедрите AppsFlyer Web SDK (пиксель веб-атрибуции) на этом сайте, включая события, важные для измерения эффективности маркетинга.


Мой Web SDK ID: <WEB_SDK_ID>

URL моего рабочего сайта: <PRODUCTION_URL>

## ШАГ 0 — Проверка конфигурации

Если указанный выше идентификатор Web SDK отсутствует или вместо него все еще используется заполнитель, ответьте ТОЛЬКО кратким запросом на предоставление идентификатора (в AppsFlyer: My Apps > приложение с префиксом «website-» > SDK authentication > Web SDK ID) и остановитесь.
 Не пишите код, пока идентификатор не будет предоставлен.
 Если URL рабочего сайта не указан, запросите его в том же ответе — он необходим для проверки после развертывания.


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


## Шаг 1 - Сначала проанализируйте сайт

Прежде чем писать код, изучите кодовую базу и самостоятельно составьте план событий — не просите меня перечислять события:

1. Определите фреймворк (обычный HTML, React, Next.js, Vue и т. д.) и место, где документ <head> управляется.

2. Определите действия-конверсии на основе кода. Проверьте в следующем порядке, от более надежного к менее надежному:

   - Существующие вызовы аналитики: события gtag()/GA4, Segment analytics.track(), fbq('track'), dataLayer.push (включая объекты eCommerce) — они покажут и действия, и то, где уже хранятся значения (сумма, валюта, идентификатор заказа).

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


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

   - Формы и CTA: формы для лидов, начало подписки/пробного периода, загрузки.

   Для продуктов, не связанных с электронной коммерцией, и инструментов: если на сайте нет процессов покупки, работы с корзиной, оформления заказа, регистрации или входа, не создавайте события электронной коммерции или аутентификации, которых на самом деле нет. Определите реальные действия пользователей в продукте (например, создание, копирование, экспорт, скачивание, отправку, выбор шаблона или изменение параметров) и сопоставьте их с пользовательскими событиями с понятными описательными названиями.


3. Сопоставьте каждое найденное действие со стандартным названием AppsFlyer:

   - завершенный заказ / "Заказ завершен" /purchase_success -> af_purchase (с eventRevenue)

   - регистрация/ зарегистрироваться/ учетная запись создана -> af_complete_registration

   - вход/ signin -> af_login

   - добавить в корзину / "Product Added" -> af_add_to_cart (af_price, без eventRevenue)

   - оформить заказ / "Checkout Started" -> af_initiated_checkout (af_price, без eventRevenue)

   - просмотр товара или контента -> af_content_view

   - оформление подписки -> af_subscribe; free trial started -> af_start_trial

   - поиск-> af_search

   Все, у чего нет стандартного эквивалента, сохраняет описательное пользовательское название.

4. Для каждого события определите в коде точный источник следующих данных: фактически списанная сумма (для af_purchase), валюта, идентификатор заказа/транзакции и идентификатор пользователя. Повторно используйте те же источники данных, из которых считывает существующая аналитика.

5. Проверьте, есть ли существующая платформа управления согласием (CMP), например OneTrust или Didomi. Также отметьте любые собственные настройки согласия или конфиденциальности, которые сохраняются на сайте, и спросите меня, как они должны ограничивать измерение, вместо того чтобы решать это за меня.


Примечание: существующая аналитика используется только как источник данных для определения событий - реализуйте события AppsFlyer как прямые вызовы AF(), а не передавайте их через Segment/GA4 с используемыми там названиями.

Затем покажите мне предлагаемый план событий в виде таблицы (название события AppsFlyer, триггер + файл, источник revenue/af_price, источник идентификатора дедупликации) и дождитесь моего подтверждения перед реализацией.
 Отмечайте любое событие, для которого вам не удалось найти источник значения, вместо того чтобы гадать.

## Шаг 2 — Установите SDK-сниппет

Добавьте этот фрагмент кода ближе к началу <head> на каждой странице, указав мой идентификатор Web SDK:

<script>

!function(t,e,n,s,a,c,i,o,p){t.AppsFlyerSdkObject=a,t.AF=t.AF||function(){

(t.AF.q=t.AF.q||[]).push([Date.now()].concat(Array.prototype.slice.call(arguments)))},

t.AF.id=t.AF.id||i,t.AF.plugins={},o=e.createElement(n),p=e.getElementsByTagName(n)[0],o.async=1,

o.src="https://websdk.appsflyer.com?"+(c.length>0?"st="+c.split(",").sort().join(",")+"&":"")+(i.length>0?"af_id="+i:""),

p.parentNode.insertBefore(o,p)}(window,document,"script",0,"AF","pba",{pba: {webAppId: "<WEB_SDK_ID>"}})

</script>

Жесткие правила:

- Используйте сниппет дословно. НЕ переписывайте его в виде пользовательского компонента или модуля-обертки. SDK, интегрированные через обертку, могут отправлять пользовательские события, в то время как автоматическое событие посещения (событие LOAD в SDK) не срабатывает - в результате на сайте отображается ноль посещений и атрибуция становится невозможной.


- SDK должен загружаться ровно ОДИН раз при каждой загрузке страницы. В React/Next.js предусмотрите защиту от повторного рендеринга и двойного монтирования (например, загружайте SDK в корневом шаблоне HTML/document, а не внутри компонента, который монтируется повторно).
 Многократная загрузка может привести к тому, что SDK перестанет работать.

* Если сайт уже загружает AppsFlyer SDK через менеджер тегов (GTM), НЕ добавляйте его также в код - должен использоваться один загрузчик, а не два.
 Сообщите мне, если найдете существующий тег AppsFlyer.

- НЕ внедряйте событие просмотра страницы или посещения вручную. SDK автоматически регистрирует посещения при загрузке; самодельное событие "page_view" никогда не будет учитываться как посещение.

- Ключ конфигурации — webAppId (а не appId).

- Если на сайте применяется строгая политика безопасности контента (Content Security Policy, CSP) с nonce, добавьте nonce в тег встроенного фрагмента кода И убедитесь, что политика включает 'strict-dynamic' - фрагмент кода динамически внедряет скрипт SDK, и без 'strict-dynamic' политика, использующая только nonce, блокирует его.

## Шаг 3 — Внедрите события

Формат вызова события:

AF('pba', 'event', {

  eventType: 'EVENT',            // always the literal string 'EVENT'

  eventName: 'af_purchase',

  eventRevenue: 49.99,           // top level - only on realized revenue

  eventRevenueCurrency: 'USD',   // top level - 3-letter ISO code, defaults to USD if omitted

  eventValue: {                  // JSON metadata, max 1000 characters

    "af_order_id": "TXN-12345",

    "af_customer_event_id": "evt-abc-001"

  }

});

Event rules - follow these exactly:

1.. Используйте стандартные названия событий AppsFlyer, чтобы кроссплатформенная отчетность и воронки были согласованы: af_purchase, af_complete_registration, af_login, af_add_to_cart, af_initiated_checkout, af_content_view, af_subscribe. Если есть мобильное приложение, используйте ТЕ ЖЕ названия событий, что и в мобильном SDK. Никогда не добавляйте суффиксы платформы, например "_web".

   Исключение — отдельные строки покупок: если сайт явно продаёт отдельные уровни или категории продуктов, для которых нужны отдельные разбивки в дэшборде (например, два продукта по подписке), предложите в плане событий раздельные названия (af_purchase_<tier>) вместо одного общего события и укажите почему. Сегментация только через eventValue не отображается в стандартных представлениях дэшборда. Никогда не отправляйте ОДНОВРЕМЕННО событие для конкретного уровня и общее событие для одной и той же покупки - это приводит к дублированию данных.


2. Доход указывайте ТОЛЬКО в поле eventRevenue верхнего уровня и ТОЛЬКО для событий, в которых деньги действительно были переведены (завершенная покупка, завершенная подписка, подтвержденное бронирование). Значения внутри eventValue (af_revenue, revenue, price, amount, total) НИКОГДА не учитываются как доход — указание дохода там является ошибкой реализации №1 и приводит к доходу $0 по каждой покупке.

3. Всегда отправляйте eventRevenueCurrency вместе с eventRevenue, если валюта не USD, иначе любая сумма будет записана как USD.

4. Отправляйте фактическую сумму одной транзакции как обычное число: без символов валют, без указания центов как целых единиц, без дублирования общей суммы корзины и суммы товара, без пожизненной ценности клиента.

5. Для денежных значений, которые НЕ являются фактически полученным доходом (стоимость добавления в корзину, стоимость начала оформления заказа, просмотренная цена), НЕ задавайте eventRevenue. Укажите сумму в "af_price", а валюту — в "af_currency" внутри eventValue. Если отправлять eventRevenue и для af_initiated_checkout, и для af_purchase, доход будет учитываться дважды.

6. Для покупок добавляйте "af_order_id" (идентификатор транзакции) внутри eventValue. Если на этом этапе в кодовой базе нет реального идентификатора транзакции, укажите это в плане событий вместо того, чтобы подставлять заполнитель.


7. Добавляйте уникальный "af_customer_event_id" внутри eventValue для каждого события конверсии. Одно и то же событие с одним и тем же ID никогда не должно отправляться дважды - создавайте ID отдельно для каждого действия и предусмотрите защиту от повторного срабатывания обработчика при повторном рендеринге SPA.
 Это также устраняет дублирование, если какой-либо серверный поток (S2S) отправляет те же конверсии.

8. Одно событие на одно действие пользователя. Не отправляйте одно и то же действие под двумя разными названиями и не передавайте одно и то же действие одновременно через AppsFlyer и через промежуточный слой пересылки под разными названиями.


9. Для корзин с несколькими товарами добавьте массив "af_order_info" внутри eventValue - по одному объекту для каждого товара с ключами: sku, revenue (цена за единицу), qty, content_name, content_type, content_category, brand.
 При покупке eventRevenue верхнего уровня по-прежнему содержит общую сумму заказа.

10. События должны срабатывать после того, как на странице загрузится сниппет SDK. Если конверсия завершается на странице подтверждения или благодарности, запускайте событие при загрузке этой страницы; для действий внутри страницы (кликов по кнопкам в SPA) запускайте его из обработчика действия.

11. Передавайте только необходимые данные - исключайте нерелевантные поля:

    - НЕ включайте eventRevenue или eventRevenueCurrency, если в рамках этого события фактически не было денежной транзакции. Никогда не отправляйте eventRevenue: 0 или валюту по умолчанию «на всякий случай».

    - НЕ включайте eventCategory, eventLabel и любые поля в стиле GA/Segment. Они не входят в API событий Web SDK AppsFlyer.

    - Внутри eventValue опускайте ключи, значения которых представляют собой пустую строку, null, undefined или false (если только само значение false не имеет смысла для этого свойства).

    - Если параметр не относится к конкретному событию, не включайте его в payload вообще. Предпочтительно использовать минимальный объект, содержащий только необходимые поля.


    - Пустые столбцы дохода/валюты в отчетах AppsFlyer не означают, что клиент должен отправлять нули или значения по умолчанию: просто не передавайте эти поля.

## ШАГ 4 - Задайте идентификатор пользователя клиента (CUID)

Сразу после того, как пользователь войдет в систему или зарегистрируется (а также при загрузке страниц, где пользователь уже аутентифицирован), вызовите:

AF('pba', 'setCustomerUserId', '<the user's internal ID, as a string>');

Правила:

- Используйте ТОТ ЖЕ идентификатор, который мобильные приложения передают в setCustomerUserId, если мобильные приложения существуют: именно он связывает путь пользователя между вебом и мобильными приложениями.

- Используйте непрозрачный внутренний идентификатор. Никогда: адрес электронной почты, номер телефона или другие PII.

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

- Сам по себе setCustomerUserId не создает событие, доступное для отчетности. Также отправляйте af_complete_registration при регистрации и af_login при входе после установки CUID, чтобы эти события содержали CUID.


## ШАГ 5 - Согласие (только если есть CMP)

Если на сайте есть платформа управления согласием:

- Инициализируйте SDK  с отключенным измерением {pba: {webAppId: "<WEB_SDK_ID>", measurementStatus: false}}

- После получения согласия: window.AF_SDK.PLUGINS.PBA.enableMeasurement()

- После отзыва согласия: window.AF_SDK.PLUGINS.PBA.disableMeasurement()
Примечания:

- Эти методы плагина становятся доступны только после полной загрузки скрипта SDK, в отличие от AF(), который представляет собой очередь-заглушку и доступен сразу.
 Обеспечьте правильную последовательность выполнения.


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

Если CMP нет, используйте обычный сниппет (по умолчанию измерение включено).

## Шаг 6 — Проверка

### 6a. Локальная верификация (во время внедрения)

Запустите проект, откройте его в браузере (с помощью Playwright/Puppeteer или браузерного инструмента, если он доступен) и зафиксируйте КАК данные запроса, ТАК И HTTP-статус ответа для каждого запроса к доменам AppsFlyer.
 Проверьте:

- Запрос загрузчика SDK возвращает статус 200 и выполняется ровно один раз при каждой загрузке страницы (переходите между страницами и повторно рендерите компоненты, чтобы убедиться в отсутствии повторной загрузки).

- При загрузке страницы отправляется запрос с eventType "LOAD" и заполненным afWebUserId, а его ответ имеет статус 2xx - это посещение; без него атрибуция невозможна.

- Каждая реализованная конверсия создает ровно один запрос события, каждый из которых возвращает статус 2xx, при этом для покупок eventRevenue и eventRevenueCurrency находятся на верхнем уровне, а af_customer_event_id присутствует и является уникальным.



- После имитации входа последующие запросы содержат идентификатор пользователя клиента.

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


Если вы не можете запустить браузер, выполните статическую проверку: фрагмент кода имеет единственную точку вставки, которая не может монтироваться дважды; каждый обработчик события срабатывает ровно один раз для каждого действия; revenue и currency передаются в полях верхнего уровня; setCustomerUserId доступен для каждого сценария входа аутентифицированного пользователя.
 Прямо укажите, что статус ответа получить не удалось.

### 6b. Проверка после развертывания на реальном домене (обязательно)

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

- Загрузите рабочий URL и убедитесь, что фрагмент кода присутствует в HTML-коде, ФАКТИЧЕСКИ ОТДАВАЕМОМ сервером.

- Загрузите рабочую страницу в браузере и повторите для нее все проверки из раздела 6a.

- Убедитесь, что параметр запроса af_id в исходящих запросах содержит Web SDK ID в точности без изменений - неверный или обрезанный ID означает, что события отправляются с идентификатором, которого нет в моем аккаунте, и в результате они просто никуда не попадут.

- Используйте специальный идентификатор пользователя для QA (например, qa_<yyyymmdd>_01), чтобы впоследствии можно было отдельно найти данные этого тестового запуска в необработанных данных.

Если развертывание еще не выполнено, сообщите мне, что проверка 6b еще не выполнена, и предоставьте точные команды и проверки, которые нужно запустить после развертывания.


### 6c. Запись QA

Подготовьте таблицу проверочного запуска, чтобы затем можно было сопоставить строки в сырых данных AppsFlyer — по одной строке на событие: метка времени UTC, имя события, CUID, af_order_id, af_customer_event_id, статус HTTP. Укажите время начала и окончания всего запуска в UTC, а также время развертывания в UTC, если оно вам известно.

## Шаг 7 — Обратная проверка данных

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

- Визиты записываются автоматически и отображаются в данных уровня событий как строки SESSION с ПУСТЫМ именем события и нулевым доходом — так устроена схема, это не ошибка. Первые посещения и повторные посещения отображаются в данных уровня конверсии (FIRST_VISIT / REVISIT), а не как именованные события. Экспорт данных по сеансам никогда не будет содержать события в приложении, независимо от того, насколько правильно выполнена интеграция.

- Реализованные конверсии отображаются как отдельные строки с заполненным именем события (af_purchase, af_login и т. д.), а доход указывается только в строках покупки.

- Данные, полученные за период ДО развертывания, не могут содержать новые события. Укажите время развертывания в UTC и сообщите мне, что запрашивать данные нужно только за период после этого времени. Укажите, что поля времени атрибуции могут содержать гораздо более раннее время, чем время события, и относиться к предыдущему посещению, а не к этому запуску.


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


- Укажите точный фильтр, который нужно использовать, чтобы найти QA-запуск из 6c (временное окно плюс QA CUID), и опишите, как выглядит корректный результат.

- Если события возвращают статус 2xx, но по-прежнему не появляются после истечения периода задержки, четко укажите, что это проблема на стороне аккаунта (событие не включено для веб-приложения, область отчетности или доступ к данным), а не с ошибкой в коде, и перечислите, что мне следует проверить в интерфейсе AppsFlyer.

## Выходные данные

Когда закончите, предоставьте:

- Таблицу всех реализованных событий: название, место срабатывания (файл), обработка дохода, идентификатор дедупликации.

- Где был установлен сниппет и как гарантируется его однократная загрузка.

- Где вызывается setCustomerUserId.

- Таблица результатов QA из раздела 6c и четкое разделение того, что вы проверили самостоятельно (с указанием статусов ответов), и того, что остается мне проверить вручную по чек-листу QA (какую страницу открыть, какое действие выполнить, какой запрос и статус ожидать).

- Инструкции из шага 7 по получению данных из системы.

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

Не реализуйте ничего сверх описанной здесь интеграции AppsFlyer Web SDK.