> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.onesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google BigQuery

> Exporte datos de eventos de mensajería a BigQuery e importe eventos personalizados desde BigQuery para activar campañas personalizadas.

export const PLATFORM_0 = "BigQuery"

export const DATA_TYPE_0 = "event table columns"

export const COLUMN_HEADER_0 = "BigQuery Column"

export const PROPERTIES_DESCRIPTION_0 = "Additional columns as JSON"

## 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](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (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

<Steps>
  <Step title="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.

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="Cree una cuenta de servicio">
    Visite la [página Crear cuenta de servicio](https://console.cloud.google.com/iam-admin/serviceaccounts/create) y haga clic en **Create Service Account.**

    <Frame>
      <img src="https://mintcdn.com/onesignal/0qspEXXeJ8zJbkJ-/images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png?fit=max&auto=format&n=0qspEXXeJ8zJbkJ-&q=85&s=038779c4d976ba56a17a32f2e6646573" width="2388" height="558" data-path="images/docs/7fe257f51fcacd15a07c4f4f23bf8bf2f9f22c2f1c171ad8b8648624de4de304-BQ1-2.png" />
    </Frame>
  </Step>

  <Step title="Complete los campos">
    Asígnele cualquier nombre e ID de cuenta de servicio que elija.

    <Frame>
      <img src="https://mintcdn.com/onesignal/MUgio66t0sYhGEvj/images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png?fit=max&auto=format&n=MUgio66t0sYhGEvj&q=85&s=37236688a79f1c16c0d6fdad15b03245" width="1344" height="870" data-path="images/docs/6437e9849e23f18ec6f90e03c3821817566e7f150125f440a58fbe5fd2b42e0b-BQ1-3.png" />
    </Frame>
  </Step>

  <Step title="Asigne el rol 'BigQuery User'">
    Otorgue a la cuenta de servicio el rol "BigQuery User".

    <Frame>
      <img src="https://mintcdn.com/onesignal/56ctKxZSV4m5VEkn/images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png?fit=max&auto=format&n=56ctKxZSV4m5VEkn&q=85&s=1df75028d3632a3ed413c10c1de9b94a" width="549" height="395" data-path="images/docs/b1bff32d7f010b488b60347e01ecb1fbde182602f19f16d3d89914d1de1c0635-BQ1-4.png" />
    </Frame>
  </Step>

  <Step title="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.
  </Step>
</Steps>

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

### 2. Activar la integración en OneSignal

<Steps>
  <Step title="Vaya a OneSignal > Data > Integrations > BigQuery" />

  <Step title="Pegue su clave JSON de cuenta de servicio" />

  <Step title="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.
  </Step>

  <Step title="Haga clic en Save y espere la confirmación" />
</Steps>

<Note>
  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.
</Note>

### 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.

<Frame caption="Conjunto de datos de BigQuery que contiene eventos de mensajes exportados">
  <img src="https://mintcdn.com/onesignal/9_Q1FZLh6C0BFLq-/images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png?fit=max&auto=format&n=9_Q1FZLh6C0BFLq-&q=85&s=08cf57a8bd91f9447909ad619077935f" width="1552" height="1052" data-path="images/docs/c40ec987eadef5dd1c16cb47fb71c2c666b30ea8667624584ecbc481c12ef026-BQ5.png" />
</Frame>

## 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 receipt](/docs/en/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.impression`     | In-App message shown.                                                      |
|       In-App Clicked      |       `message.iam.clicked`      | In-App message clicked.                                                    |
|     In-App Page Viewed    |   `message.iam.page_displayed`   | 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](/docs/en/email-message-reports).         |
|     Email Link Clicked    |      `message.email.clicked`     | Link in email clicked.                                                     |
|     Email Unsubscribed    |   `message.email.unsubscribed`   | Recipient unsubscribed.                                                    |
|   Email Reported As Spam  | `message.email.reported_as_spam` | Marked as spam. See [Email Deliverability](/docs/en/email-deliverability). |
|       Email Bounced       |      `message.email.bounced`     | Bounce due to permanent delivery failure.                                  |
|        Email Failed       |      `message.email.failed`      | Delivery failed.                                                           |
|      Email Suppressed     |    `message.email.suppressed`    | 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](#message-event-kinds)                       |
|            `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)                        |
|                 `failure_reason`                |     String     | Reason for failure (for push failed and email failed events) |
| `_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](/docs/en/event-streams) for outbound message events (Plan limitations and overages apply)
* Access to [Custom Events](/docs/en/custom-events) for inbound event syncing (Plan limitations and overages apply)
* [Updated Account Plan](https://onesignal.com/pricing) (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**

<Steps>
  <Step title="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.
  </Step>

  <Step title="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:

    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Agregar integración en OneSignal">
    In OneSignal, go to **Data > Integrations** and click **Add Integration**.

    <Frame caption="Agregar integración de BigQuery">
      <img src="https://mintcdn.com/onesignal/IHzVtEbivOs2EktQ/images/integrations/bigquery-add-integration.png?fit=max&auto=format&n=IHzVtEbivOs2EktQ&q=85&s=6877dc14cfe8f9c1677404353927e4f8" width="1944" height="1764" data-path="images/integrations/bigquery-add-integration.png" />
    </Frame>

    * **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
  </Step>

  <Step title="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
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

### Event data mapping

Map your {PLATFORM_0} {DATA_TYPE_0} to OneSignal's custom events format:

| OneSignal Field | {COLUMN_HEADER_0} | 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`      | {PROPERTIES_DESCRIPTION_0} | No       |

### Configuración avanzada

#### Consultas SQL personalizadas

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

```sql theme={null}
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.

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

***

## 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.

***

## Recursos relacionados

* [Crear claves de cuenta de servicio en GCP](https://cloud.google.com/iam/docs/creating-managing-service-account-keys#creating)
* [Documentación de Journeys de OneSignal](./journeys-overview)
* [Documentación de exportación de datos de OneSignal](./exporting-data)

***