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

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

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

Интеграция с Google BigQuery передает выбранные события сообщений Pushwoosh в ваш набор данных BigQuery. Используйте ее для анализа событий жизненного цикла push-уведомлений, email и SMS в BigQuery, создания пользовательских отчетов или подключения данных к вашим последующим аналитическим рабочим процессам.

Эта интеграция отправляет данные только в одном направлении: из Pushwoosh в BigQuery. Чтобы импортировать сегмент пользователей BigQuery в Pushwoosh, см. Внешние сегменты.

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

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

Подготовьте следующее, прежде чем начать настройку интеграции.

1. Используйте проект Google Cloud с включенным биллингом. Поддерживаются кредиты бесплатной пробной версии. BigQuery Sandbox недостаточно, так как Storage Write API требует включенного биллинга.

2. Убедитесь, что у вас есть платный аккаунт Pushwoosh.

Цены

Вы платите Google напрямую за использование BigQuery. Pushwoosh не взимает плату за саму интеграцию.

Актуальные тарифы, бесплатные уровни и региональные особенности см. в разделе Цены на BigQuery.

Затраты могут включать:

• Прием данных: Pushwoosh передает события с помощью BigQuery Storage Write API.
• Хранение: BigQuery хранит строки, записанные в вашу целевую таблицу.
• Запросы: BigQuery взимает плату за запросы в соответствии с выбранной вами моделью ценообразования.

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

Источник: Данные отправляются из Pushwoosh в ваш набор данных BigQuery.

Поддерживаемые платформы

Pushwoosh передает события с платформ iOS, Android, Huawei, Chrome, Safari, Firefox и Web.

Синхронизируемые сущности

Выбранные события жизненного цикла push-уведомлений, email и SMS передаются в BigQuery. Pushwoosh записывает одну строку для каждого выбранного события в целевую таблицу.

Сценарии использования

• Аналитика сообщений в режиме, близком к реальному времени: анализируйте события жизненного цикла push-уведомлений, email и SMS в BigQuery вскоре после их обработки в Pushwoosh.
• Пользовательская отчетность: создавайте отчеты BigQuery для выбранных типов событий, приложений, кампаний и идентификаторов сообщений.
• Последующие рабочие процессы с данными: подключайте данные о событиях Pushwoosh к вашим аналитическим, отчетным или обрабатывающим рабочим процессам.

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

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

Если да, Pushwoosh добавляет новую строку в вашу целевую таблицу. Если таблица еще не существует, Pushwoosh создает ее автоматически, используя схему, описанную ниже. События обычно появляются в BigQuery в течение 30 секунд после обработки в Pushwoosh.

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

Выберите проект Google Cloud

Войдите в Google Cloud Console, затем выберите или создайте проект, который будет владеть набором данных BigQuery.

Совет

Запишите ID проекта. Используйте короткий идентификатор, например my-company-12345, а не читаемое человеком название проекта.

Включите необходимые API

В Google Cloud Console перейдите в APIs & Services → Library и включите эти API:

• BigQuery API
• BigQuery Storage API

Pushwoosh использует эти API для создания целевой таблицы и передачи событий в BigQuery.

Создайте сервисный аккаунт

Pushwoosh использует сервисный аккаунт для записи событий в ваш набор данных BigQuery.

1. Перейдите в IAM & Admin → Service Accounts.

2. Нажмите Create service account.

3. В поле Service account name введите имя, например, pushwoosh-bigquery.

   Google Cloud автоматически генерирует Service account ID из имени.

   

4. Нажмите Create and continue.

Предоставьте роли IAM

1. Предоставьте сервисному аккаунту следующие роли IAM:

   • BigQuery Data Editor: позволяет Pushwoosh создавать таблицу и добавлять строки.
   • BigQuery User: позволяет Pushwoosh использовать Storage Write API.
   

Примечание

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

2. Нажмите Continue.

3. Нажмите Done.

Создайте JSON-ключ

Pushwoosh использует JSON-ключ для аутентификации в качестве сервисного аккаунта.

1. Откройте созданный вами сервисный аккаунт.

2. Перейдите в Keys → Add key → Create new key.

3. Выберите JSON.

Google Cloud загрузит файл JSON-ключа на ваш компьютер.

Осторожно

Храните файл JSON-ключа в безопасности. Любой, у кого есть этот файл, может записывать данные в ваш проект BigQuery. Не добавляйте его в git и не делитесь им в чате. Pushwoosh хранит ключ в зашифрованном виде и не отображает его в пользовательском интерфейсе после загрузки.

Создайте набор данных

Набор данных — это место, где Pushwoosh будет хранить таблицу с передаваемыми событиями.

1. В Google Cloud Console откройте BigQuery.

2. В Explorer выберите проект, который вы подготовили для интеграции.

3. Нажмите Create dataset.

4. В поле Dataset ID введите ID набора данных, например pushwoosh_data.

5. В поле Data location выберите регион набора данных.

6. Нажмите Create dataset.

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

1. В вашем аккаунте Pushwoosh перейдите в Настройки → Интеграции со сторонними сервисами для приложения, которое вы хотите подключить.

2. Найдите Google BigQuery в списке доступных сервисов и нажмите Настроить.

3. Заполните поля конфигурации.

• ID проекта GCP: введите ID проекта из Google Cloud, например my-company-12345.
• JSON сервисного аккаунта: вставьте полное содержимое файла JSON-ключа, который вы скачали из Google Cloud.
• ID набора данных: как только поля ID проекта GCP и JSON сервисного аккаунта будут заполнены, Pushwoosh получит список наборов данных, к которым имеет доступ ваш сервисный аккаунт. Выберите целевой набор данных. Если выпадающий список пуст, проверьте, имеет ли сервисный аккаунт доступ и существует ли набор данных в указанном вами проекте.
• Регион набора данных: выберите регион вашего набора данных BigQuery.
• Имя таблицы: оставьте пустым, чтобы использовать таблицу по умолчанию pushwoosh_events. Pushwoosh создаст таблицу со схемой, описанной ниже.
• События: выберите события, которые вы хотите передавать. Вы можете изменить этот список позже.
• Передавать события в BigQuery: включите этот переключатель. Выключите его, чтобы приостановить передачу, не удаляя конфигурацию.

4. Нажмите Проверить соединение.

Pushwoosh проверит учетные данные в BigQuery, не записывая данные.

Вы можете увидеть один из следующих статусов соединения:

• Соединение успешно: учетные данные работают, и сервисный аккаунт имеет доступ к набору данных.
• auth_failed: JSON-ключ недействителен или отозван.
• dataset_not_found: ID набора данных указан неверно или сервисный аккаунт не имеет к нему доступа.
• missing_permission: у сервисного аккаунта отсутствует одна из требуемых ролей.

5. Нажмите Применить.

Pushwoosh сохранит конфигурацию и начнет использовать ее примерно в течение 30 секунд. После этого выбранные события начнут передаваться в BigQuery.

Проверка интеграции

1. Отправьте тестовое push-уведомление или вызовите другое сообщение, которое генерирует один из выбранных вами типов событий.

2. Подождите около 30 секунд.

3. Откройте BigQuery Studio.

4. Перейдите в свой проект, затем откройте набор данных и целевую таблицу, которые вы настроили. Если вы оставили поле Имя таблицы пустым, откройте pushwoosh_events.

5. Нажмите Предпросмотр.

Вы должны увидеть строку события в таблице.

Схема таблицы

Pushwoosh записывает каждое выбранное событие как отдельную строку в целевой таблице. Чтобы ускорить запросы и упростить фильтрацию, таблица разделена по дням с использованием timestamp и кластеризована по app_id и event_kind.

Имя поля	Тип	Описание
event_kind	STRING	Тип события Pushwoosh, например Push Sent или Email Opened.
message_id	STRING	Код сообщения Pushwoosh, такой как идентификатор кампании или сообщения.
device_id	STRING	Hardware ID устройства Pushwoosh, которое сгенерировало событие.
user_id	STRING	Ваш внешний ID пользователя, если он известен. Пусто для анонимных устройств.
timestamp	TIMESTAMP	Время события в UTC.
app_id	STRING	Код приложения Pushwoosh.
platform	STRING	Исходная платформа, например ios, android или web.
properties	JSON	Дополнительные поля события. Используйте JSON_VALUE для запроса полей, как показано ниже.

Запрос свойств

Столбец properties хранит дополнительные поля события в формате JSON. Используйте JSON_VALUE для извлечения отдельных полей в ваших запросах.

Например, чтобы увидеть, какие кампании привели к наибольшему количеству открытий за последние 7 дней, нажмите +, чтобы создать новый запрос, вставьте SQL-код ниже и нажмите Выполнить.

SELECT
  event_kind,
  JSON_VALUE(properties, '$.campaign_id') AS campaign_id,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE event_kind = 'Push Opened'
  AND timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)
GROUP BY 1, 2
ORDER BY events DESC

Чтобы просмотреть количество событий за последний час, выполните этот запрос:

SELECT
  event_kind,
  COUNT(*) AS events
FROM `your-project.your_dataset.pushwoosh_events`
WHERE timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR)
GROUP BY event_kind
ORDER BY events DESC

Обновление интеграции

Ротация ключа сервисного аккаунта

1. В Google Cloud Console перейдите в IAM & Admin → Service Accounts.

2. Откройте ваш сервисный аккаунт.

3. Перейдите в Keys и создайте новый JSON-ключ.

4. Оставьте старый ключ активным, пока не убедитесь, что новый ключ работает.

5. В Pushwoosh откройте модальное окно конфигурации Google BigQuery.

6. Вставьте новый JSON в поле JSON сервисного аккаунта.

7. Нажмите Применить.

Pushwoosh проверит новый ключ, заменит сохраненные учетные данные и начнет использовать его после следующей перезагрузки конфигурации, что займет около 30 секунд.

После того как вы убедитесь, что события по-прежнему передаются, удалите старый ключ в Google Cloud Console.

Изменение целевого набора данных или таблицы

1. В Pushwoosh перейдите в Настройки → Интеграции со сторонними сервисами.

2. Откройте настройки Google BigQuery.

3. Выберите другой набор данных или введите новое имя таблицы.

4. Нажмите Применить.

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

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

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

Проблема	Что проверить
Проверка соединения не удалась с ошибкой auth_failed	JSON сервисного аккаунта имеет неверный формат или ключ был отозван в Google Cloud. Создайте новый ключ и снова вставьте полный JSON-файл. Файл начинается с {, заканчивается } и содержит блок private_key.
Проверка соединения не удалась с ошибкой dataset_not_found	ID набора данных написан с ошибкой или не существует в указанном вами проекте. ID наборов данных чувствительны к регистру. Выберите набор данных из выпадающего списка, чтобы избежать опечаток.
Проверка соединения не удалась с ошибкой missing_permission	У сервисного аккаунта отсутствует роль BigQuery Data Editor или BigQuery User. Предоставьте обе роли на уровне проекта или на уровне набора данных для более ограниченного доступа.
Проверка соединения прошла успешно, но в BigQuery не появляются строки	Подождите не менее 30 секунд. Убедитесь, что тип события, которое вы отправляете, выбран в Событиях. Например, если выбрано только Push Opened и никто не открывает push-уведомление, строки не появятся.
Конфигурация выглядит правильно, но модальное окно показывает пустые поля	Перезагрузите страницу. Конфигурация запрашивается при каждом открытии модального окна и кэшируется на 30 секунд базовым сервисом. Если вы только что сохранили настройки, подождите немного и откройте модальное окно снова.

Примечание

Pushwoosh записывает Push Sent, Email Sent и SMS Sent независимо от статуса доставки, чтобы агрегированные данные в BigQuery соответствовали канонической статистике Pushwoosh. Для Delivered, Opened, Bounced и Unsubscribed Pushwoosh записывает только успешные события.

FAQ

Можно ли использовать бесплатный аккаунт Google Cloud?

Да, если для проекта включен биллинг. Кредитов бесплатной пробной версии достаточно для работы этой интеграции при типичных объемах в течение всего пробного периода. BigQuery Sandbox без биллинга не будет работать, так как Storage Write API требует включенного биллинга.

Видит ли Pushwoosh мои данные в BigQuery?

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

Можно ли экспортировать данные в несколько наборов данных BigQuery?

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

Можно ли изменить схему таблицы?

Схема является фиксированной для всех клиентов. Если вам нужны дополнительные столбцы, извлеките их из JSON-объекта properties в своих собственных представлениях или запланированных запросах.

Что произойдет, если я временно отключу интеграцию?

Отключите Передавать события в BigQuery и нажмите Применить. Pushwoosh прекратит добавление событий для этого приложения примерно в течение 30 секунд.

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

Как полностью удалить интеграцию?

Свяжитесь с support@pushwoosh.com, чтобы удалить конфигурацию интеграции. Набор данных и строки, уже записанные в BigQuery, останутся в вашем аккаунте Google Cloud.

Есть ли гарантии доставки?

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

Почему нет события “Push Clicked”?

В настоящее время Pushwoosh предоставляет в этой интеграции события Push Sent, Push Delivered и Push Opened для push-уведомлений. Отдельного шага для клика по push-уведомлению нет. Для Email и SMS есть свои события жизненного цикла.