Integración con Google BigQuery

Se necesita la ayuda de un desarrollador

Necesitará la ayuda de su equipo de desarrollo o del administrador de Google Cloud para configurar la integración. Por favor, comparta esta guía con ellos.

La integración con Google BigQuery transmite eventos de mensajes seleccionados de Pushwoosh a su conjunto de datos de BigQuery. Úsela para analizar eventos del ciclo de vida de push, email y SMS en BigQuery, crear informes personalizados o conectar los datos a sus flujos de trabajo de análisis posteriores.

Resumen de la integración

Prerrequisitos

Prepare lo siguiente antes de abrir la configuración de la integración.

1. Use un proyecto de Google Cloud con la facturación habilitada. Se admiten los créditos de la prueba gratuita. BigQuery Sandbox no es suficiente porque la API de escritura de almacenamiento (Storage Write API) requiere facturación.

2. Asegúrese de tener una cuenta de Pushwoosh de pago.

Precios

Usted paga directamente a Google por el uso de BigQuery. Pushwoosh no cobra por la integración en sí.

Para conocer las tarifas actuales, los niveles gratuitos y los detalles regionales, consulte los precios de BigQuery.

Los costos pueden incluir:

• Ingesta de datos: Pushwoosh transmite eventos con la API de escritura de almacenamiento de BigQuery (Storage Write API).
• Almacenamiento: BigQuery almacena las filas escritas en su tabla de destino.
• Consultas: BigQuery cobra por las consultas según el modelo de precios que haya seleccionado.

Tipo de integración

Fuente: Los datos se envían desde Pushwoosh a su conjunto de datos de BigQuery.

Plataformas compatibles

Pushwoosh transmite eventos desde las plataformas iOS, Android, Huawei, Chrome, Safari, Firefox y Web.

Entidades sincronizadas

Los eventos seleccionados del ciclo de vida de push, email y SMS se transmiten a BigQuery. Pushwoosh escribe una fila por cada evento seleccionado en la tabla de destino.

Casos de uso

• Análisis de mensajes casi en tiempo real: analice los eventos del ciclo de vida de push, email y SMS en BigQuery poco después de que se procesen en Pushwoosh.
• Informes personalizados: cree informes de BigQuery para tipos de eventos, aplicaciones, campañas e identificadores de mensajes seleccionados.
• Flujos de trabajo de datos posteriores: conecte los datos de eventos de Pushwoosh a sus flujos de trabajo de análisis, informes o procesamiento de datos.

Cómo funciona la integración

Después de guardar la configuración, Pushwoosh comienza a transmitir los eventos de mensajes seleccionados a su tabla de BigQuery casi en tiempo real. Por cada evento de mensaje que fluye a través de Pushwoosh, el sistema comprueba si el tipo de evento está seleccionado en su configuración.

Si lo está, Pushwoosh añade una nueva fila a su tabla de destino. Si la tabla aún no existe, Pushwoosh la crea automáticamente utilizando el esquema que se describe a continuación. Los eventos suelen aparecer en BigQuery en un plazo de 30 segundos después de ser procesados en Pushwoosh.

Configurar la integración en Google Cloud

Elija un proyecto de Google Cloud

Inicie sesión en la Consola de Google Cloud, luego elija o cree el proyecto que será el propietario del conjunto de datos de BigQuery.

Consejo

Anote el ID del proyecto. Utilice el identificador corto, por ejemplo mi-empresa-12345, no el nombre del proyecto legible por humanos.

Habilite las API requeridas

En la Consola de Google Cloud, vaya a API y servicios → Biblioteca y habilite estas API:

• API de BigQuery
• API de almacenamiento de BigQuery

Pushwoosh utiliza estas API para crear la tabla de destino y transmitir eventos a BigQuery.

Crear una cuenta de servicio

Pushwoosh utiliza la cuenta de servicio para escribir eventos en su conjunto de datos de BigQuery.

1. Vaya a IAM y administración → Cuentas de servicio.

2. Haga clic en Crear cuenta de servicio.

3. En Nombre de la cuenta de servicio, introduzca un nombre, por ejemplo, pushwoosh-bigquery.

   Google Cloud genera automáticamente el ID de la cuenta de servicio a partir del nombre.

   

4. Haga clic en Crear y continuar.

Otorgar roles de IAM

1. Otorgue a la cuenta de servicio estos roles de IAM:

   • Editor de datos de BigQuery: permite a Pushwoosh crear la tabla y añadir filas.
   • Usuario de BigQuery: permite a Pushwoosh utilizar la API de escritura de almacenamiento (Storage Write API).
   

Nota

Puede adjuntar los roles a nivel de proyecto o a nivel de conjunto de datos. El acceso a nivel de proyecto es el más fácil de configurar. El acceso a nivel de conjunto de datos es más restrictivo y se recomienda para producción.

2. Haga clic en Continuar.

3. Haga clic en Hecho.

Crear una clave JSON

Pushwoosh utiliza la clave JSON para autenticarse como la cuenta de servicio.

1. Abra la cuenta de servicio que ha creado.

2. Vaya a Claves → Añadir clave → Crear nueva clave.

3. Seleccione JSON.

Google Cloud descarga el archivo de clave JSON en su ordenador.

Precaución

Guarde el archivo de clave JSON en un lugar seguro. Cualquiera que tenga este archivo puede escribir en su proyecto de BigQuery. No lo suba a git ni lo comparta por chat. Pushwoosh almacena la clave encriptada en reposo y no la expone a través de la interfaz de usuario después de la carga.

Crear un conjunto de datos

El conjunto de datos es donde Pushwoosh almacena la tabla de eventos transmitidos.

1. En la Consola de Google Cloud, abra BigQuery.

2. En el Explorador, seleccione el proyecto que preparó para la integración.

3. Haga clic en Crear conjunto de datos.

4. En ID del conjunto de datos, introduzca un ID de conjunto de datos, por ejemplo pushwoosh_data.

5. En Ubicación de los datos, seleccione la región del conjunto de datos.

6. Haga clic en Crear conjunto de datos.

Configurar la integración en Pushwoosh

1. En su cuenta de Pushwoosh, vaya a Ajustes → Integraciones de terceros para la aplicación que desea conectar.

2. Busque Google BigQuery en la lista de servicios disponibles y haga clic en Configurar.

3. Rellene los campos de configuración.

• ID del proyecto de GCP: introduzca el ID del proyecto de Google Cloud, por ejemplo mi-empresa-12345.
• JSON de la cuenta de servicio: pegue el contenido completo del archivo de clave JSON que descargó de Google Cloud.
• ID del conjunto de datos: una vez que se hayan rellenado el ID del proyecto de GCP y el JSON de la cuenta de servicio, Pushwoosh obtendrá los conjuntos de datos a los que su cuenta de servicio puede acceder. Seleccione el conjunto de datos de destino. Si el menú desplegable está vacío, compruebe que la cuenta de servicio tiene acceso y que el conjunto de datos existe en el proyecto que especificó.
• Región del conjunto de datos: seleccione la región de su conjunto de datos de BigQuery.
• Nombre de la tabla: déjelo en blanco para usar la tabla predeterminada pushwoosh_events. Pushwoosh crea la tabla con el esquema que se describe a continuación.
• Eventos: seleccione los eventos que desea transmitir. Puede cambiar esta lista más tarde.
• Transmitir eventos a BigQuery: habilite este interruptor. Desactívelo para pausar la transmisión sin eliminar la configuración.

4. Haga clic en Probar conexión.

Pushwoosh valida las credenciales con BigQuery sin escribir datos.

Puede ver uno de estos estados de conexión:

• Conexión exitosa: las credenciales funcionan y la cuenta de servicio puede acceder al conjunto de datos.
• auth_failed: la clave JSON no es válida o ha sido revocada.
• dataset_not_found: el ID del conjunto de datos es incorrecto o la cuenta de servicio no puede acceder a él.
• missing_permission: a la cuenta de servicio le falta uno de los roles requeridos.

5. Haga clic en Aplicar.

Pushwoosh guarda la configuración y comienza a usarla en unos 30 segundos. Después de eso, los eventos seleccionados comienzan a transmitirse a BigQuery.

Verificar la integración

1. Envíe un push de prueba o active otro mensaje que produzca uno de los tipos de eventos que seleccionó.

2. Espere unos 30 segundos.

3. Abra BigQuery Studio.

4. Vaya a su proyecto, luego abra el conjunto de datos y la tabla de destino que configuró. Si dejó el Nombre de la tabla en blanco, abra pushwoosh_events.

5. Haga clic en Vista previa.

Debería ver la fila del evento en la tabla.

Esquema de la tabla

Pushwoosh escribe cada evento seleccionado como una fila separada en la tabla de destino. Para que las consultas sean más rápidas y fáciles de filtrar, la tabla está particionada por día usando timestamp y agrupada por app_id y event_kind.

Nombre del campo	Tipo	Descripción
event_kind	STRING	Tipo de evento de Pushwoosh, por ejemplo Push Sent o Email Opened.
message_id	STRING	Código de mensaje de Pushwoosh, como el identificador de la campaña o del mensaje.
device_id	STRING	ID de hardware de Pushwoosh del dispositivo que produjo el evento.
user_id	STRING	Su ID de usuario externo si se conoce. Vacío para dispositivos anónimos.
timestamp	TIMESTAMP	Hora del evento en UTC.
app_id	STRING	Código de aplicación de Pushwoosh.
platform	STRING	Plataforma de origen, por ejemplo ios, android o web.
properties	JSON	Campos de eventos adicionales. Use JSON_VALUE para consultar campos, como se muestra a continuación.

Consultar propiedades

La columna properties almacena campos de eventos adicionales como JSON. Use JSON_VALUE para extraer campos individuales en sus consultas.

Por ejemplo, para ver qué campañas generaron más aperturas en los últimos 7 días, haga clic en + para crear una nueva consulta, pegue el siguiente SQL y haga clic en Ejecutar.

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

Para revisar los recuentos de eventos de la última hora, ejecute esta consulta:

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

Actualizar la integración

Rotar la clave de la cuenta de servicio

1. En la Consola de Google Cloud, vaya a IAM y administración → Cuentas de servicio.

2. Abra su cuenta de servicio.

3. Vaya a Claves y cree una nueva clave JSON.

4. Mantenga la clave antigua activa hasta que confirme que la nueva clave funciona.

5. En Pushwoosh, abra el modal de configuración de Google BigQuery.

6. Pegue el nuevo JSON en JSON de la cuenta de servicio.

7. Haga clic en Aplicar.

Pushwoosh valida la nueva clave, reemplaza la credencial almacenada y comienza a usarla después de la siguiente recarga de configuración, que tarda unos 30 segundos.

Después de confirmar que los eventos siguen fluyendo, elimine la clave antigua en la Consola de Google Cloud.

Cambiar el conjunto de datos o la tabla de destino

1. En Pushwoosh, vaya a Ajustes → Integraciones de terceros.

2. Abra la configuración de Google BigQuery.

3. Seleccione un conjunto de datos diferente o introduzca un nuevo nombre de tabla.

4. Haga clic en Aplicar.

Pushwoosh reabre el flujo con el nuevo destino en unos 30 segundos. Las filas ya escritas permanecen en la tabla antigua. Pushwoosh no rellena los datos históricos.

Para mantener sin cambios la clave de la cuenta de servicio almacenada cuando actualice otros ajustes, deje el campo JSON de la cuenta de servicio vacío antes de hacer clic en Aplicar.

Solución de problemas

Problema	Qué comprobar
La prueba de conexión falla con auth_failed	El JSON de la cuenta de servicio está mal formado o la clave ha sido revocada en Google Cloud. Cree una nueva clave y pegue de nuevo el archivo JSON completo. El archivo comienza con {, termina con } y contiene un bloque private_key.
La prueba de conexión falla con dataset_not_found	El ID del conjunto de datos está mal escrito o no existe en el proyecto que especificó. Los ID de los conjuntos de datos distinguen entre mayúsculas y minúsculas. Seleccione el conjunto de datos del menú desplegable para evitar errores tipográficos.
La prueba de conexión falla con missing_permission	A la cuenta de servicio le falta el rol de Editor de datos de BigQuery o de Usuario de BigQuery. Otorgue ambos roles a nivel de proyecto, o otórguelos a nivel de conjunto de datos para un acceso más restrictivo.
La prueba de conexión se realiza con éxito, pero no aparecen filas en BigQuery	Espere al menos 30 segundos. Compruebe que el tipo de evento que está enviando está seleccionado en Eventos. Por ejemplo, si solo está seleccionado Push abierto y nadie abre el push, no aparecerán filas.
La configuración parece correcta, pero el modal muestra campos vacíos	Recargue la página. La configuración se obtiene cada vez que se abre el modal y el servicio subyacente la almacena en caché durante 30 segundos. Si acaba de guardar la configuración, espere un momento y vuelva a abrir el modal.

Nota

Pushwoosh registra Push enviado, Email enviado y SMS enviado independientemente del estado de entrega para que los agregados de BigQuery coincidan con las estadísticas canónicas de Pushwoosh. Para Entregado, Abierto, Rebotado y Suscripción cancelada, Pushwoosh solo registra los eventos exitosos.

Preguntas frecuentes

¿Puedo usar una cuenta gratuita de Google Cloud?

Sí, siempre que la facturación esté habilitada en el proyecto. Los créditos de la prueba gratuita son suficientes para ejecutar esta integración con volúmenes típicos durante todo el período de prueba. BigQuery Sandbox sin facturación no funcionará porque la API de escritura de almacenamiento (Storage Write API) requiere facturación.

¿Pushwoosh ve mis datos de BigQuery?

No. La credencial de la cuenta de servicio que usted carga autoriza a Pushwoosh a escribir en el conjunto de datos que seleccione. Pushwoosh no lee de su conjunto de datos y no tiene acceso al resto de su proyecto.

¿Puedo exportar a varios conjuntos de datos de BigQuery?

Se admite un destino por aplicación. Si necesita los mismos eventos en dos conjuntos de datos, configure una consulta programada de BigQuery en su proyecto para copiar datos de pushwoosh_events a otra tabla.

¿Puedo cambiar el esquema de la tabla?

El esquema es fijo para todos los clientes. Si necesita columnas adicionales, extráigalas del JSON de properties en sus propias vistas o consultas programadas.

¿Qué sucede si deshabilito la integración temporalmente?

Desactive Transmitir eventos a BigQuery y haga clic en Aplicar. Pushwoosh dejará de añadir eventos para esta aplicación en unos 30 segundos.

Los eventos producidos mientras la integración está desactivada no se almacenan en búfer ni se rellenan cuando la vuelve a activar. Pushwoosh conserva la configuración, incluidas las credenciales, el conjunto de datos y la selección de eventos.

¿Cómo elimino la integración por completo?

Póngase en contacto con support@pushwoosh.com para eliminar la configuración de la integración. El conjunto de datos y las filas ya escritas en BigQuery permanecerán en su cuenta de Google Cloud.

¿Hay garantías de entrega?

La integración utiliza una entrega de “al menos una vez”. En condiciones normales de funcionamiento, los duplicados son raros. Un reinicio del proceso entre una adición y una confirmación puede producir un pequeño número de filas duplicadas. Elimine los duplicados en SQL si su canalización posterior requiere resultados de “exactamente una vez”.

¿Por qué no hay un evento de Clic en Push?

Actualmente, Pushwoosh expone Push enviado, Push entregado y Push abierto para las notificaciones push en esta integración. No hay disponible un paso dedicado para el clic en push. El email y el SMS tienen sus propios eventos de ciclo de vida.