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

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

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

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

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

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

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

1. Используйте проект Google Cloud с включенным биллингом. Поддерживаются кредиты Free Trial. 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.

Совет

Запишите Project 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 перейдите в Settings → 3rd Party Integrations для приложения, которое вы хотите подключить.

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

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

• GCP Project ID: введите ID проекта из Google Cloud, например my-company-12345.
• Service Account JSON: вставьте полное содержимое файла ключа JSON, который вы скачали из Google Cloud.
• Dataset ID: как только поля GCP Project ID и Service Account JSON будут заполнены, Pushwoosh получит наборы данных, к которым имеет доступ ваш сервисный аккаунт. Выберите целевой набор данных. Если выпадающий список пуст, проверьте, имеет ли сервисный аккаунт доступ и существует ли набор данных в указанном вами проекте.
• Dataset region: выберите регион вашего набора данных BigQuery.
• Table name: оставьте пустым, чтобы использовать таблицу по умолчанию pushwoosh_events. Pushwoosh создаст таблицу со схемой, описанной ниже.
• Events: выберите события, которые вы хотите передавать. Вы можете изменить этот список позже.
• Stream events to BigQuery: включите этот переключатель. Выключите его, чтобы приостановить потоковую передачу, не удаляя конфигурацию.

4. Нажмите Test connection.

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

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

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

5. Нажмите Apply.

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

Проверьте интеграцию

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

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

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

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

5. Нажмите Preview.

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

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

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

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

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

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

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

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 в поле Service Account JSON.

7. Нажмите Apply.

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

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

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

1. В Pushwoosh перейдите в Settings → 3rd Party Integrations.

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

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

4. Нажмите Apply.

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

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

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

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

Примечание

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

FAQ

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

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

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

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

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

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

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

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

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

Выключите Stream events to BigQuery и нажмите Apply. Pushwoosh прекратит добавление событий для этого приложения примерно через 30 секунд.

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

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

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

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

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

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

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