Интеграция с Google Analytics

Требуется помощь разработчика

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

Передавайте один и тот же User ID в Google Analytics 4 и Pushwoosh, и оба инструмента будут считать человека, который посещает ваш сайт или приложение, одним пользователем. Тогда вы сможете отправлять сообщения пользователям, которых анализируете в Google Analytics, и строить сегменты Pushwoosh на основе данных Google Analytics.

Обзор интеграции

Тип интеграции

Назначение: аудитории Google Analytics и экспорт Google Analytics в BigQuery становятся сегментами Pushwoosh. User ID передается с вашего сайта или из приложения в каждый инструмент отдельно. Pushwoosh не отправляет данные в Google Analytics.

Предварительные требования

• Аккаунт Pushwoosh и Pushwoosh SDK (Web, Android или iOS) на сайте или в приложении, из которого вы передаете User ID.
• Ресурс Google Analytics 4, который собирает данные с того же сайта или из того же приложения.

Для импорта аудиторий Google Analytics также нужны:

• Сервисный аккаунт Google Cloud и его JSON-ключ. См. Create and delete service account keys.
• Google Analytics Data API и Admin API, включенные в проекте этого сервисного аккаунта.
• Роль Viewer для сервисного аккаунта в ресурсе Google Analytics. См. Add, edit, and delete users and user groups.

Для запросов к экспорту BigQuery также нужны:

• Ресурс Google Analytics 4, связанный с BigQuery. См. Set up BigQuery Export.
• Ключ сервисного аккаунта с ролями BigQuery Data Viewer и BigQuery Job User. См. BigQuery roles and permissions.

Как работает интеграция?

Pushwoosh сопоставляет пользователей по их ID:

1. Ваш сайт или приложение передает один и тот же User ID в Google Analytics и в Pushwoosh.
2. Pushwoosh считывает User ID из аудитории Google Analytics или из вашего экспорта BigQuery.
3. Пользователь попадает в сегмент, когда его ID совпадает с User ID в Pushwoosh.

Сегмент обновляется по-разному в зависимости от источника:

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

Настройка интеграции

Настройка состоит из двух частей. Сначала разработчики передают User ID с вашего сайта или из приложения. Затем вы строите сегмент на основе данных Google Analytics в Control Panel.

1. Вместе с разработчиками выберите User ID.
2. Разработчики передают его в Google Analytics и в Pushwoosh с вашего сайта или из мобильного приложения.
3. При необходимости постройте сегмент Pushwoosh на основе данных Google Analytics. Затем его можно использовать как любой другой сегмент.

Передайте User ID в Google Analytics и Pushwoosh

Эту часть выполняют ваши разработчики. Поделитесь с ними разделами ниже.

Выберите User ID

Используйте идентификатор, который уже есть у каждого пользователя в вашей собственной системе, например ID аккаунта из вашей базы данных. Одно и то же значение передается в Google Analytics как его user ID и в Pushwoosh как User ID.

Не используйте персональные данные в User ID

Правила Google Analytics запрещают передавать персональные данные в user ID. Не используйте адрес электронной почты, номер телефона или другие персональные данные.

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

Передайте User ID с вашего сайта

Передайте ID в Google Analytics в параметре user_id вашего тега Google. Если вы используете Google Tag Manager, вместо этого задайте поле user_id в конфигурации тега Google. Подробнее — в разделе Send user IDs документации Google.

JavaScript

gtag('config', 'G-XXXXXXXXXX', {
  'user_id': 'USER_ID'
});

Передайте тот же ID в Pushwoosh с помощью Web Push SDK:

JavaScript

Pushwoosh.push((api) => {
  api.registerUser('USER_ID');
});

Передайте User ID из мобильного приложения

Мобильные приложения отправляют данные в Google Analytics 4 через Firebase. Установите ID с помощью метода Firebase Analytics setUserId (см. Set a user ID в документации Firebase) и установите то же значение с помощью Pushwoosh SDK.

Android

Java

FirebaseAnalytics.getInstance(context).setUserId("USER_ID");
Pushwoosh.getInstance().setUserId("USER_ID");

iOS

Swift

Analytics.setUserID("USER_ID")
Pushwoosh.sharedInstance().setUserId("USER_ID")

Создайте сегмент на основе данных Google Analytics

Эту часть вы выполняете в Control Panel после того, как разработчики начнут передавать User ID. Pushwoosh может превратить данные Google Analytics в сегмент двумя способами, оба — через внешние сегменты:

• Импорт аудитории Google Analytics: выберите аудиторию, которую вы уже создали в Google Analytics. Ни SQL, ни BigQuery не нужны.
• Запрос к экспорту BigQuery: напишите собственный SQL-запрос к сырым событиям, которые Google Analytics экспортирует в BigQuery, — для условий, которые нельзя выразить аудиторией.

Импорт аудитории Google Analytics

Попросите разработчика или администратора Google Cloud выполнить эти шаги в Google Cloud и Google Analytics:

1. Подготовьте сервисный аккаунт и его JSON-ключ. См. Create and delete service account keys в документации Google Cloud.
2. В проекте Google Cloud, к которому относится сервисный аккаунт, включите Google Analytics Data API и Google Analytics Admin API.
3. В Google Analytics перейдите в Admin → Property access management и добавьте email сервисного аккаунта с ролью Viewer. Роль, выданная в Google Cloud IAM, не дает доступа к Google Analytics.

Затем выполните эти шаги в Control Panel:

1. Создайте внешний сегмент, выбрав в Тип базы данных значение Google Analytics 4 audience.

2. Введите ID ресурса GA4. Его можно найти в Google Analytics в разделе Admin → Property details.

3. Вставьте JSON-ключ из первого списка в поле Service account JSON.

4. Нажмите Загрузить аудитории и выберите Аудитория.

   

5. Нажмите Проверить подключение.

6. Нажмите Создать.

Pushwoosh обновляет сегмент, когда считывает его целиком, например когда вы отправляете в него кампанию или Journey или рассчитываете его размер:

• Если данным меньше 24 часов, Pushwoosh использует их как есть, потому что Google Analytics обновляет состав аудитории примерно раз в сутки.
• Если им больше 24 часов, Pushwoosh использует текущие данные и обновляет сегмент в фоне.
• Если им больше 72 часов, Pushwoosh ждет, пока обновление завершится.

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

Запрос к экспорту BigQuery

Если вы экспортируете данные Google Analytics 4 в BigQuery, вы можете отбирать пользователей по любому SQL-условию над их событиями, например всех, кто совершил покупку за последние 30 дней.

Попросите разработчика или администратора Google Cloud выполнить эти шаги в Google Cloud и Google Analytics:

1. Свяжите ресурс Google Analytics 4 с проектом BigQuery и включите ежедневный экспорт. Следуйте инструкции Set up BigQuery Export в документации Google.

   После этого Google Analytics записывает события каждого дня в таблицу events_YYYYMMDD в наборе данных analytics_<property ID>. User ID, который вы передали в предыдущих разделах, находится в столбце user_id.

2. Создайте ключ сервисного аккаунта с ролями BigQuery Data Viewer и BigQuery Job User. Проверить подключение и Проверить запрос запускают тестовое задание запроса в вашем проекте, поэтому без BigQuery Job User они завершаются ошибкой.

Затем в Control Panel создайте внешний сегмент, выбрав в Тип базы данных значение Google BigQuery. Укажите ключ сервисного аккаунта для подключения и запрос, который возвращает User ID нужных пользователей.

Например, этот запрос возвращает пользователей, совершивших покупку за последние 30 дней. Замените my-project на ID вашего проекта Google Cloud, а analytics_123456789 — на имя вашего набора данных:

SQL

SELECT DISTINCT user_id
FROM `my-project.analytics_123456789.events_*`
WHERE event_name = 'purchase'
  AND user_id IS NOT NULL
  AND _TABLE_SUFFIX >= FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 30 DAY))

Сегмент отражает активность по предыдущий день включительно, потому что Google Analytics экспортирует данные раз в сутки.

Как узнать, что интеграция работает?

• User ID: в Pushwoosh перейдите в Аудитория → Карточка пользователя и найдите по User ID один из ID, которые вы передали в Google Analytics. Если пользователь найден, у обоих инструментов одинаковый ID.
• Сегменты: в разделе Аудитория → Внешние сегменты у сегмента статус валиден. Чтобы узнать, сколько пользователей совпало, проверьте размер сегмента.

Устранение неполадок

Загрузить аудитории или Проверить подключение показывает ошибку

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

• Service account JSON — это ключ сервисного аккаунта. Другие файлы учетных данных Google отклоняются.
• ID ресурса GA4 — это номер из Admin → Property details.
• У сервисного аккаунта есть роль Viewer в Google Analytics в разделе Admin → Property access management. Роль, выданная в Google Cloud IAM, не учитывается.
• Google Analytics Admin API включен в проекте Google Cloud сервисного аккаунта.

Список аудиторий пуст

У ресурса еще нет аудиторий. Создайте аудиторию в Google Analytics в разделе Admin → Audiences, затем снова нажмите Загрузить аудитории.

В сегмент никто не попадает

• Убедитесь, что Google Analytics Data API включен. Проверить подключение его не проверяет, но Pushwoosh нужен этот API, чтобы считывать участников аудитории.
• Убедитесь, что ваш сайт или приложение передает один и тот же User ID в Google Analytics и в Pushwoosh. В сегмент попадают только пользователи, чей user ID в Google Analytics совпадает с User ID в Pushwoosh. Пользователи, которых Google Analytics знает только по анонимному client ID, в сегмент не попадают.

Проверить подключение или Проверить запрос не проходит для BigQuery

Обе проверки запускают тестовое задание запроса в вашем проекте Google Cloud, не считывая данные. Проверьте, что:

• У сервисного аккаунта есть обе роли: BigQuery Data Viewer и BigQuery Job User. Без BigQuery Job User ни одна из проверок не запустится.
• Запрос использует ID вашего проекта и имя набора данных analytics_<property ID>, а экспорт уже записал хотя бы одну ежедневную таблицу events_YYYYMMDD.
• Запрос возвращает ровно один столбец с именем user_id.