> ## 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.
# Pub/Sub
> Sincroniza eventos personalizados desde Google Pub/Sub a OneSignal para activar Journeys automatizados y campañas de mensajería personalizadas basadas en el comportamiento del usuario en tiempo real.
export const PLATFORM_0 = "Pub/Sub"
export const DATA_TYPE_0 = "message fields"
export const COLUMN_HEADER_0 = "Pub/Sub Message Field"
export const PROPERTIES_DESCRIPTION_0 = "JSON object with event details"
## Descripción general
La integración OneSignal + Google Pub/Sub permite la sincronización en tiempo real de eventos personalizados desde tus topics de Pub/Sub a OneSignal para activar campañas de mensajería automatizadas y Journeys basados en el comportamiento del usuario.
Pub/Sub es el servicio de mensajería escalable de Google que permite a las aplicaciones enviar y recibir mensajes entre componentes independientes. OneSignal actúa como suscriptor de tus topics de Pub/Sub, permitiéndote sincronizar mensajes de eventos desde Pub/Sub para activar experiencias de usuario personalizadas.
***
## 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)
### Google Pub/Sub
* **Proyecto de Google Cloud** con Pub/Sub habilitado
* **Topics de Pub/Sub** que contengan mensajes de eventos
* **Permisos IAM** para otorgar acceso a cuenta de servicio
* **Mensajes con formato JSON** en tus topics
***
## Configuración
In OneSignal, go to **Data > Integrations** and click **Add Integration**.
1. Selecciona **Google Pub/Sub** de la lista
2. Ingresa el **ID del Proyecto GCP** donde se encuentran tus topics de Pub/Sub
3. Elige el método de autenticación:
* **Auto-generated Service Account** (recomendado): OneSignal crea y gestiona la cuenta de servicio
* **Existing Service Account**: Proporciona tu propio archivo JSON de clave de cuenta de servicio
4. Haz clic en **Connect**
OneSignal creará una nueva cuenta de servicio y te proporcionará la dirección de email de la cuenta de servicio.
Otorga el rol **`roles/pubsub.editor`** a esta cuenta de servicio en tu proyecto GCP:
```bash theme={null}
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID \
--member serviceAccount:SERVICE_ACCOUNT_EMAIL \
--role roles/pubsub.editor
```
OneSignal usa este rol para:
* Crear suscripciones a tus topics de eventos
* Consumir mensajes de eventos desde topics
* Crear topics de error (Dead Letter Queue) para procesamiento fallido
Una vez que hayas otorgado los permisos necesarios, haz clic en **Save** en OneSignal para verificar la conexión.
OneSignal validará que puede acceder a tus topics de Pub/Sub y está listo para procesar mensajes de eventos.
***
## Esquema de datos de eventos
Antes de poder usar un topic de Pub/Sub para eventos personalizados, debes definir el esquema de los mensajes de eventos.
En OneSignal, ve a **Data > Integrations** y selecciona tu conexión de Pub/Sub.
OneSignal extrae automáticamente la lista de topics desde tu proyecto. Haz clic en **Refresh topics** para actualizar manualmente la lista.
1. Haz clic en el nombre del topic que contiene tus datos de eventos
2. Selecciona **JSON** como el formato de mensaje (único formato soportado)
3. Haz clic en **Import sample message** y proporciona un mensaje de evento de muestra
4. Revisa el esquema detectado para asegurar el mapeo correcto de campos
5. Haz clic en **Save Dataset**
### Formato de mensaje de evento
Tus mensajes de Pub/Sub deben seguir esta estructura JSON para eventos personalizados de OneSignal:
```json theme={null}
{
"event_name": "purchase_completed",
"user_id": "user_12345",
"timestamp": "2023-12-01T10:30:00Z",
"properties": {
"product_id": "prod_abc123",
"price": 29.99,
"category": "electronics",
"payment_method": "credit_card"
},
"session_id": "session_789"
}
```
### 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 |
No incluyas PII de clientes o datos sensibles en mensajes de muestra. OneSignal almacena muestras de mensajes como parte de la definición del dataset.
***
## Procesamiento de eventos en tiempo real
A diferencia de las integraciones por lotes, Pub/Sub permite el procesamiento de eventos casi en tiempo real:
* **Baja latencia**: Los eventos se procesan en segundos después de ser publicados en topics
* **Suscripciones automáticas**: OneSignal crea suscripciones dedicadas para cada topic
* **Manejo de errores**: Los eventos fallidos se envían a topics de Dead Letter Queue para investigación
* **Procesamiento escalable**: Maneja flujos de eventos de alto volumen automáticamente
***
## Configuración avanzada
### Dead Letter Queue
OneSignal crea automáticamente topics de error para eventos que fallan en el procesamiento:
* **Creación automática**: Los topics de error se crean por suscripción
* **Almacenamiento de eventos fallidos**: Los eventos que no pueden procesarse se almacenan para depuración
* **Revisión manual**: Accede a eventos fallidos a través de Google Cloud Console para solución de problemas
### Reconocimiento de mensajes
OneSignal maneja el reconocimiento de mensajes de Pub/Sub automáticamente:
* **Procesamiento exitoso**: Los mensajes se reconocen después de la creación exitosa del evento
* **Procesamiento fallido**: Los mensajes se reconocen negativamente y se envían a Dead Letter Queue
* **Lógica de reintento**: Manejo de reintentos integrado para fallas transitorias
***
## Limitaciones
* Solo se soporta el formato de mensaje JSON
* Las muestras de mensajes se almacenan como parte de las definiciones de dataset (evitar PII)
* Requiere permisos `roles/pubsub.editor` a nivel de proyecto
* El tamaño máximo de mensaje sigue los límites de Google Pub/Sub (10MB)
***
## FAQ
### ¿Qué tan rápido se procesan los eventos?
Los eventos se procesan típicamente en segundos después de ser publicados en tu topic de Pub/Sub, permitiendo la activación de Journey casi en tiempo real.
### ¿Qué sucede si OneSignal no puede procesar un evento?
Los eventos fallidos se envían automáticamente a un topic de Dead Letter Queue que OneSignal crea. Puedes revisar estos eventos en Google Cloud Console para depuración.
### ¿Puedo usar múltiples topics para diferentes tipos de eventos?
Sí, puedes definir esquemas para múltiples topics dentro del mismo proyecto GCP. Cada topic puede contener diferentes tipos de eventos con sus propias definiciones de esquema.