Google BigQuery

Descripción general

La integración de OneSignal + BigQuery admite dos potentes pipelines de datos:

Exportar: Envíe automáticamente datos de eventos de mensajería (push, correo electrónico, SMS, en la aplicación) desde OneSignal a BigQuery para análisis y reportes.
Importar: Sincronice eventos personalizados de usuario desde sus conjuntos de datos de BigQuery a OneSignal para activar Journeys automatizados y mensajería personalizada.

Juntas, estas integraciones le brindan control completo sobre los datos de participación del usuario, impulsando análisis avanzados y mensajería en tiempo real basada en el comportamiento.

Exportar eventos de OneSignal a BigQuery

Envíe eventos de rendimiento y participación de mensajería (por ejemplo, envíos, aperturas, clics) a BigQuery para:

Construir paneles personalizados e informes
Rastrear tendencias de entrega y participación entre canales
Combinar datos de OneSignal con otros datos comerciales para análisis

Requisitos

Access to Event Streams for outbound message events (Plan limitations and overages apply)
Access to Custom Events for inbound event syncing (Plan limitations and overages apply)
Updated Account Plan (not available on free apps)

Proyecto de Google Cloud Platform con facturación habilitada
BigQuery habilitado en su proyecto de GCP
Cuenta de servicio con permisos de escritura de BigQuery

Pasos de configuración

1. Crear una cuenta de servicio

Inicie sesión en su cuenta de Google Cloud Platform

Después de iniciar sesión, asegúrese de que el proyecto correcto esté seleccionado.

Cree una cuenta de servicio

Visite la página Crear cuenta de servicio y haga clic en Create Service Account.

Complete los campos

Asígnele cualquier nombre e ID de cuenta de servicio que elija.

Asigne el rol 'BigQuery User'

Otorgue a la cuenta de servicio el rol “BigQuery User”.

Cree una clave JSON para esta cuenta

Vaya a su nueva cuenta de servicio > Keys > Add Key > Create new key > seleccione JSON. Guarde el archivo.

Pegará todo el contenido de este archivo de clave JSON en OneSignal para activar la integración.

2. Activar la integración en OneSignal

Vaya a OneSignal > Data > Integrations > BigQuery

Pegue su clave JSON de cuenta de servicio

Configure los ajustes

Sync Frequency: Tan frecuentemente como cada 15 minutos
Dataset/Table Names: Solo debe contener letras minúsculas, números y guiones bajos, y no puede comenzar con un número.
Event Types: Seleccione eventos de mensajes específicos (por ejemplo, sent, opened, clicked)
- Nota: Puede seleccionar múltiples tipos de eventos o actualizar eventos seleccionados más adelante.

Haga clic en Save y espere la confirmación

La sincronización inicial de datos puede tardar de 15 a 30 minutos en aparecer en BigQuery.Mientras espera, envíe mensajes a través de push, correo electrónico, en la aplicación o SMS para activar los eventos seleccionados.

3. Ver datos en BigQuery

Abra su consola de BigQuery y localice el conjunto de datos (por ejemplo, onesignal_events_<app-id>) para explorar los eventos de mensajes sincronizados.

Conjunto de datos de BigQuery que contiene eventos de mensajes exportados

Message events and properties

Message event kinds

Property: event_kind Type: String The kind of message and event (e.g. message.push.received, message.push.sent).

Message Event (OneSignal)	`event_kind`	Description
Push Sent	`message.push.sent`	Push notification successfully sent.
Push Received	`message.push.received`	Delivered push (see Confirmed Delivery).
Push Clicked	`message.push.clicked`	User clicked the push.
Push Failed	`message.push.failed`	Delivery failure. See message reports.
Push Unsubscribed	`message.push.unsubscribed`	User unsubscribed from push.
In-App Impression	`message.iam.displayed`	In-App message shown.
In-App Clicked	`message.iam.clicked`	In-App message clicked.
In-App Page Viewed	`message.iam.pagedisplayed`	In-App page shown.
Email Sent	`message.email.sent`	Email delivered.
Email Received	`message.email.received`	Email accepted by recipient’s mail server.
Email Opened	`message.email.opened`	Email opened. See Email Reports.
Email Link Clicked	`message.email.clicked`	Link in email clicked.
Email Unsubscribed	`message.email.unsubscribed`	Recipient unsubscribed.
Email Marked Spam	`message.email.resporedasspam`	Marked as spam. See Email Deliverability.
Email Bounced	`message.email.hardbounced`	Bounce due to permanent delivery failure.
Email Failed	`message.email.failed`	Delivery failed.
Email Suppressed	`message.email.supressed`	Suppressed due to suppression list.
SMS Sent	`message.sms.sent`	SMS sent.
SMS Delivered	`message.sms.delivered`	SMS successfully delivered.
SMS Failed	`message.sms.failed`	SMS failed to deliver.
SMS Undelivered	`message.sms.undelivered`	SMS rejected or unreachable.

Event data schema

For each message event generated by a user, the following metadata will be attached to the record.

Column Name	Type	Description
`event_id`	UUID	Unique identifier for the event
`event_timestamp`	Timestamp	Time of event occurrence
`event_kind`	String	The Event Kind
`subscription_device_type`	String	Device type (e.g., iOS, Android, Web, Email, SMS)
`language`	String	Subscription language code
`version`	String	Integration version
`device_os`	String	Device operating system version
`device_type`	Number	Numeric device type
`token`	String	Push token, phone number, or email
`subscription_id`	UUID	Subscription ID
`subscribed`	Boolean	Subscription status
`onesignal_id`	UUID	OneSignal user ID
`last_active`	String	Last active timestamp
`sdk`	String	OneSignal SDK version
`external_id`	String	External user ID that should match the integration user ID
`app_id`	UUID	App ID from OneSignal
`template_id`	UUID	Template ID (if applicable)
`message_id`	UUID	Message batch/request ID
`message_name`	String	Name of the message
`message_title`	String	Message title (English only)
`message_contents`	String	Truncated message body (English only)
`_created`, `_id`, `_index`, `_fivetran_synced`	Internal use	Fivetran sync metadata

Notes

Syncs after saving/activating may take an additional 15-30 minutes to complete.
Deactivating may still result in one final sync after deactivation.
To ensure efficient data synchronization, our system automatically creates and manages staging datasets. These datasets, named with a pattern like fivetran_{two random words}_staging, temporarily store data during processing before it’s integrated into your main schema. These staging datasets are essential for maintaining a streamlined workflow and should not be deleted, as they will be automatically recreated.

Importar eventos desde BigQuery

Envíe datos de eventos de comportamiento desde BigQuery a OneSignal para:

Activar Journeys basados en la actividad del usuario
Personalizar la mensajería basada en datos de comportamiento

Requisitos

Access to Event Streams for outbound message events (Plan limitations and overages apply)
Access to Custom Events for inbound event syncing (Plan limitations and overages apply)
Updated Account Plan (not available on free apps)

Proyecto de GCP con BigQuery y tablas de datos de eventos
Cuenta de servicio con permisos de lectura
Tablas de datos de eventos que contengan datos de comportamiento en conjuntos de datos de BigQuery

Pasos de configuración

Crear cuenta de servicio de BigQuery

OneSignal generará una cuenta de servicio automáticamente cuando cree la conexión. Alternativamente, puede proporcionar su propio archivo JSON de clave de cuenta de servicio.Si crea su propia cuenta de servicio, asegúrese de que tenga los permisos requeridos enumerados a continuación.

Otorgar permisos requeridos

La cuenta de servicio de OneSignal necesita estos roles de IAM de BigQuery:

bigquery.dataViewer - Acceso de lectura a conjuntos de datos y tablas que contienen datos de eventos
bigquery.jobUser - Permiso para crear trabajos para consultas de datos
bigquery.metadataViewer - Acceso a metadatos a nivel de proyecto (recomendado)

Otorgue permisos usando Google Cloud Console o CLI:

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.dataViewer

gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
  --member serviceAccount:ONESIGNAL_SERVICE_ACCOUNT_EMAIL \
  --role roles/bigquery.jobUser

Agregar integración en OneSignal

In OneSignal, go to Data > Integrations and click Add Integration.

Agregar integración de BigQuery

Sync Engine: Se recomienda sincronización avanzada para conjuntos de datos grandes o consultas de datos de eventos complejas. Puede comenzar con sincronización básica y cambiar a sincronización avanzada más adelante si es necesario.
Google Cloud Project ID: Su proyecto de GCP que contiene conjuntos de datos de BigQuery
Dataset Region: Ubicación donde se almacenan sus conjuntos de datos de BigQuery
Service Account Key (opcional): Archivo de clave JSON si usa su propia cuenta de servicio

Configurar fuente de datos de eventos

Especifique el conjunto de datos y la tabla de BigQuery que contienen sus datos de eventos:

Dataset: Nombre del conjunto de datos de BigQuery (por ejemplo, analytics_events)
Table/View: Tabla o vista que contiene registros de eventos
Event Query: Consulta SQL opcional para filtrar o transformar datos de eventos

Su tabla de eventos debe contener columnas para:

Nombre/tipo de evento
Identificador de usuario
Marca de tiempo del evento
Propiedades adicionales del evento

Probar la conexión

Haga clic en Test Connection para verificar que OneSignal pueda acceder a su proyecto de BigQuery y leer datos de eventos.

Event data mapping

Map your to OneSignal’s custom events format:

OneSignal Field	Description	Required
`name`	`event_name`	Event identifier	Yes
`external_id`	`user_id`	User identifier	Yes
`timestamp`	`event_timestamp`	When event occurred	No
`properties`	`event_data`	No

Configuración avanzada

Consultas SQL personalizadas

Use SQL personalizado para filtrar o transformar datos de eventos antes de sincronizar con OneSignal:

SELECT
  event_name,
  user_id,
  event_timestamp,
  STRUCT(
    product_id,
    purchase_amount,
    category
  ) as payload
FROM `project.dataset.events`
WHERE event_timestamp >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 7 DAY)

Acceso entre proyectos

Si sus datos de eventos abarcan múltiples proyectos de BigQuery, otorgue a la cuenta de servicio de OneSignal acceso a cada proyecto que contenga tablas o vistas referenciadas.

La región de conexión de BigQuery debe coincidir con la región de tabla específica para un rendimiento óptimo.

Preguntas frecuentes

¿Por qué falla mi sincronización?

Hay algunas razones comunes por las que su sincronización puede estar fallando:

La cuenta de servicio no tiene los permisos requeridos
El conjunto de datos de origen es demasiado grande para una sincronización básica y necesita usar sincronización avanzada

Revise los pasos de configuración anteriores y asegúrese de haberlos seguido correctamente. Si aún tiene problemas, comuníquese con support@onesignal.com.

¿Por qué veo múltiples IDs de mensajes para el mismo contenido?

Esto generalmente ocurre cuando se reutiliza una plantilla de mensaje en múltiples envíos o flujos activados.

¿Con qué frecuencia sincroniza datos OneSignal?

Tanto las integraciones de exportación como de importación pueden sincronizarse tan frecuentemente como cada 15 minutos.

¿Puedo usar vistas de BigQuery?

Sí. Solo asegúrese de que la cuenta de servicio tenga acceso a todas las tablas referenciadas en la vista.

Primeros pasos & configuraciones

Canales de mensajería

Journeys

Audiencia & eventos personalizados

Analítica & Integraciones

Privacidad & Seguridad

Descripción general