Pinterest Conversions API для Shopify: руководство по настройке

Pinterest Conversions API — это серверный способ Pinterest отправлять события конверсий. Ваш магазин или инструмент вроде ROASaurus отправляет события, например покупки, прямо в ваш рекламный аккаунт Pinterest, а не полагается только на Pinterest Tag в браузере покупателя. Pinterest использует эти данные для отчётности по конверсиям, оптимизации кампаний и таргетинга.

Это руководство охватывает API v5 и принимаемые им события, click id epik, хеширование данных клиента, работу дедупликации с Pinterest Tag, тестирование и настройку всего этого в Shopify.

Что такое Pinterest Conversions API?

Pinterest Tag — это скрипт в браузере покупателя. Conversions API выполняет ту же работу с сервера. В API версии 5 вы отправляете события на endpoint событий вашего рекламного аккаунта, авторизуясь токеном доступа для конверсий, который создаёте в Pinterest Ads Manager. Каждое событие указывает, где оно произошло: для интернет-магазина источник действия — web.

Pinterest просит рекламодателей, которые используют ещё и Tag, не считать конверсию дважды: для этого с каждым событием передаётся event_id. Также Pinterest просит присылать события в реальном времени или не позднее чем через час после того, как они произошли.

В Shopify у серверного подключения есть одно очевидное преимущество: покупки берутся из самого заказа. Shopify сообщает ROASaurus о каждом оплаченном заказе вебхуком, а ROASaurus отправляет его в Pinterest вскоре после оплаты, независимо от того, сработал ли Tag в браузере. Подробнее идею объясняет руководство по серверному трекингу в Shopify.

Какие события принимает Pinterest Conversions API?

У Pinterest есть фиксированный список стандартных названий событий, написанных строчными буквами с подчёркиваниями, например page_visit, add_to_cart и checkout. Можно также задать до 15 пользовательских типов событий на рекламодателя. ROASaurus сопоставляет пять событий покупателя в Shopify так:

Название может сбивать с толку. Событие checkout у Pinterest — это завершённая покупка, а не начало оформления заказа. Начало чекаута — отдельное событие initiate_checkout.

Для события checkout Pinterest рекомендует передавать сумму, валюту, id заказа, id товаров и количество позиций. ROASaurus передаёт все пять параметров, а также количество и цену каждой позиции. Pinterest просит указывать сумму до налога и доставки. В Shopify ROASaurus отправляет именно её: сумму заказа за вычетом налога и доставки, с сервера и из браузерного тега. Если платформа интернет-магазина не сообщает налог и доставку отдельно, ROASaurus отправляет итоговую сумму заказа.

Как Pinterest сопоставляет событие с человеком?

Каждое событие содержит данные пользователя. Pinterest требует хотя бы одно из трёх: хешированный адрес email, хешированный рекламный id мобильного устройства или IP-адрес вместе с user agent. У интернет-магазина нет рекламного id, поэтому нужны email либо IP-адрес и user agent. Если нет ни того, ни другого, ROASaurus пропускает событие, а не отправляет то, что Pinterest не сможет использовать.

Click id epik

Click id Pinterest может прийти из двух мест: из параметра epik в URL лендинга или из cookie _epik на вашем домене. Руководство Pinterest по API рекомендует передавать значение cookie _epik, потому что оно работает, даже когда параметр URL отсутствует или удалён, и это даёт лучшее покрытие.

ROASaurus считывает оба на вашей витрине: использует параметр URL, когда новый клик приносит его, а в остальных случаях — cookie. Он сохраняет click id вместе с посетителем и отправляет его в поле click_id каждого серверного события, включая покупку. Визиты с epik считаются визитами из Pinterest в отчётах по атрибуции ROASaurus.

POST https://api.pinterest.com/v5/ad_accounts/549755885175/events

{
  "data": [{
    "event_name": "checkout",
    "action_source": "web",
    "event_time": 1793016000,
    "event_id": "order-5512345678901",
    "event_source_url": "https://example-store.com/checkouts/…/thank-you",
    "user_data": {
      "em": ["a3f1…9c2e"],
      "ph": ["7b40…11d8"],
      "external_id": ["e05c…4a7f"],
      "client_ip_address": "203.0.113.24",
      "client_user_agent": "Mozilla/5.0 (iPhone; …)",
      "click_id": "dj0yJnU9…"
    },
    "custom_data": {
      "currency": "USD",
      "value": "84",
      "order_id": "5512345678901",
      "content_ids": ["44123456789"],
      "contents": [{ "id": "44123456789", "quantity": 2, "item_price": "42" }],
      "num_items": 2
    }
  }]
}

Как работает дедупликация с Pinterest Tag?

Если Tag и API оба сообщают о покупке, Pinterest получает два события на один заказ. Чтобы он считал их одним, нужен одинаковый id с обеих сторон: event id в Tag должен совпадать с event_id в серверном событии. Pinterest оставляет первое полученное событие и удаляет дубликаты, пришедшие в течение 48 часов.

ROASaurus формирует id покупки из id заказа Shopify. Покупка из заказа 5512345678901 получает event id order-5512345678901 — и в Tag, который срабатывает в чекауте, и в серверном событии.

Дедуплицируются все пять событий

У каждого события покупателя в ROASaurus один event id: его используют и Tag в браузере, и серверное событие. Tag использует собственные названия Pinterest для тех же событий: pagevisit, viewcontent, addtocart, initiatecheckout и checkout, которые соответствуют page_visit, view_content, add_to_cart, initiate_checkout и checkout в API. Поэтому, когда работают оба, Pinterest оставляет одну копию каждого посещения страницы, просмотра товара, добавления в корзину, начала чекаута и покупки.

Работать можно двумя способами:

• Tag и Conversions API вместе. Tag добавляет сигналы из браузера, сервер восполняет то, что Tag упускает, а Pinterest объединяет копии.
• Запустите API без Tag. Оставьте Tag ID пустым или выключите Also load the browser tag. Тогда каждое событие отправляется один раз, только с сервера.

В справочной статье о двойном учёте такие же проверки описаны для других рекламных платформ.

Как протестировать Pinterest Conversions API?

У API есть тестовый флаг. Запросы, отправленные с test=true, попадают в песочницу: Pinterest обрабатывает их как тестовые данные и не использует для отчётности и оптимизации.

1. Включите тестовый режим

   В ROASaurus откройте настройки пикселя Pinterest в разделе Tracking & platforms и отметьте Test mode (events show under Test events, max 20). Тогда каждое серверное событие отправляется с test=true. Pinterest обрабатывает не более 20 тестовых событий в одном пакете.

2. Оформите тестовый заказ

   Зайдите в свой магазин, посмотрите товар, добавьте его в корзину и оформите заказ.

3. Посмотрите результат

   Откройте Event log. Pinterest может ответить HTTP 200, даже если одно событие в запросе завершилось ошибкой, поэтому ROASaurus проверяет статус каждого события и показывает сбои там.

4. Выключите тестовый режим

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

5. Проверьте Events Overview

   В Pinterest Ads Manager откройте страницу Events Overview. Она показывает приходящие события и дедуплицированные конверсии. Pinterest рекомендует стремиться к Good Event Quality Score.

Как настроить Pinterest Conversions API в Shopify с ROASaurus

Вам нужен магазин Shopify с приложением ROASaurus и доступ к Pinterest Ads Manager. На странице интеграции с Pinterest перечислены все поля, которые отправляет ROASaurus.

1. Подключите магазин Shopify

   Перейдите в Add a store › Shopify, нажмите Install app и включите встроенное приложение ROASaurus (app embed) в редакторе тем. Оно фиксирует epik и cookie _epik на каждой странице. Каждый шаг показан в руководстве по настройке Shopify.

2. Создайте токен доступа для конверсий

   В Pinterest Ads Manager перейдите в Conversions и создайте токен доступа для конверсий. Запишите ID вашего рекламного аккаунта.

3. Добавьте пиксель Pinterest в ROASaurus

   Перейдите в Tracking & platforms, нажмите Add pixel на карточке Pinterest и заполните Ad account ID и Conversion access token.

4. Добавьте ваш Tag ID

   Для дедупликации с Tag заполните Pinterest Tag ID и оставьте отмеченным Also load the browser tag. Без Tag ID ROASaurus отправляет только серверные события и не загружает Tag.

5. Добавьте пиксель чекаута

   В Shopify admin › Settings › Customer events добавьте пользовательский пиксель с именем ROASaurus и вставьте сниппет со страницы Tracking & platforms. Он отправляет событие checkout из Tag в чекауте Shopify, передавая id заказа как event_id.

6. Выберите серверные события и протестируйте

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

При включённой настройке Respect visitor consent, которая включена по умолчанию, ROASaurus следует выбору покупателя в cookie-баннере Shopify. Если покупатель отклоняет маркетинговые cookie, ROASaurus не загружает для него Pinterest Tag, не задаёт id посетителя, поэтому его клики с ним не связываются, и не отправляет в Pinterest его события просмотра. Его оплаченный заказ всё равно уходит с сервера в Conversions API с хешированными данными заказа, а также с IP-адресом и user agent из заказа, но без click id. Что хранится и отправляется, объясняет руководство по согласию и конфиденциальности.

Подключите рекламный аккаунт Pinterest в разделе Setup › Ad spend, и ROASaurus будет каждый час загружать расходы по кампаниям, чтобы вы видели ROAS Pinterest и прибыль после рекламы в аналитике прибыли. Руководство по TikTok Events API описывает такую же настройку для TikTok, где дедуплицируется каждое событие, идущее обоими путями.

Источники

1. Pinterest Developers: Track conversion events in the API
2. Pinterest Business help: The Pinterest Conversions API
3. Pinterest Developers: Track conversions with Pinterest Tag

В ROASaurus

• Интеграция с Pinterest
• Серверный трекинг в ROASaurus
• Справка: как избежать двойного учёта

Читайте дальше