Google BigQuery

개요

OneSignal + BigQuery 통합은 두 가지 강력한 데이터 파이프라인을 지원합니다:

내보내기: OneSignal의 메시징 이벤트 데이터(푸시, 이메일, SMS, 인앱)를 BigQuery로 자동으로 전송하여 분석 및 보고합니다.
가져오기: BigQuery 데이터 세트의 사용자 지정 사용자 이벤트를 OneSignal로 동기화하여 자동화된 Journeys 및 개인화된 메시징을 트리거합니다.

함께 사용하면 이러한 통합을 통해 사용자 참여 데이터를 완전히 제어하여 고급 분석 및 실시간 행동 기반 메시징을 지원합니다.

OneSignal 이벤트를 BigQuery로 내보내기

메시징 성능 및 참여 이벤트(예: 전송, 열기, 클릭)를 BigQuery로 전송하여:

사용자 지정 대시보드 및 보고서 구축
채널 전반에 걸친 전달 및 참여 추세 추적
분석을 위해 OneSignal 데이터를 다른 비즈니스 데이터와 결합

요구 사항

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)

청구가 활성화된 Google Cloud Platform 프로젝트
GCP 프로젝트에서 활성화된 BigQuery
BigQuery 쓰기 권한이 있는 서비스 계정

설정 단계

1. 서비스 계정 만들기

Google Cloud Platform 계정에 로그인

로그인한 후 적절한 프로젝트가 선택되었는지 확인합니다.

서비스 계정 만들기

서비스 계정 만들기 페이지를 방문하고 서비스 계정 만들기를 클릭합니다.

필드 작성

원하는 이름과 서비스 계정 ID를 지정합니다.

'BigQuery User' 역할 할당

서비스 계정에 “BigQuery User” 역할을 부여합니다.

이 계정에 대한 JSON 키 만들기

새 서비스 계정 > 키 > 키 추가 > 새 키 만들기로 이동하여 JSON을 선택합니다. 파일을 저장합니다.

이 JSON 키 파일의 전체 내용을 OneSignal에 붙여넣어 통합을 활성화합니다.

2. OneSignal에서 통합 활성화

OneSignal > 데이터 > 통합 > BigQuery로 이동

서비스 계정 JSON 키 붙여넣기

설정 구성

동기화 빈도: 15분마다 동기화 가능
데이터 세트/테이블 이름: 소문자, 숫자 및 밑줄만 포함해야 하며 숫자로 시작할 수 없습니다.
이벤트 유형: 특정 메시지 이벤트 선택(예: 전송됨, 열림, 클릭됨)
- 참고: 여러 이벤트 유형을 선택하거나 나중에 선택한 이벤트를 업데이트할 수 있습니다.

저장을 클릭하고 확인 대기

초기 데이터 동기화는 BigQuery에 나타나는 데 15-30분이 걸릴 수 있습니다.대기하는 동안 푸시, 이메일, 인앱 또는 SMS를 통해 메시지를 보내 선택한 이벤트를 트리거하세요.

3. BigQuery에서 데이터 보기

BigQuery 콘솔을 열고 데이터 세트(예: onesignal_events_<app-id>)를 찾아 동기화된 메시지 이벤트를 탐색합니다.

BigQuery dataset containing exported message events

메시지 이벤트 및 속성

메시지 이벤트 종류

속성: event_kind 유형: String 메시지 및 이벤트의 종류(예: message.push.received, message.push.sent).

메시지 이벤트 (OneSignal)	`event_kind`	설명
Push Sent	`message.push.sent`	푸시 알림이 성공적으로 전송되었습니다.
Push Received	`message.push.received`	전달된 푸시(전달 확인 참조).
Push Clicked	`message.push.clicked`	사용자가 푸시를 클릭했습니다.
Push Failed	`message.push.failed`	전달 실패. 메시지 보고서를 참조하세요.
Push Unsubscribed	`message.push.unsubscribed`	사용자가 푸시 구독을 취소했습니다.
In-App Impression	`message.iam.impression`	인앱 메시지가 표시되었습니다.
In-App Clicked	`message.iam.clicked`	인앱 메시지를 클릭했습니다.
In-App Page Viewed	`message.iam.page_displayed`	인앱 페이지가 표시되었습니다.
Email Sent	`message.email.sent`	이메일이 전달되었습니다.
Email Received	`message.email.received`	수신자의 메일 서버가 이메일을 수락했습니다.
Email Opened	`message.email.opened`	이메일이 열렸습니다. 이메일 보고서를 참조하세요.
Email Link Clicked	`message.email.clicked`	이메일의 링크를 클릭했습니다.
Email Unsubscribed	`message.email.unsubscribed`	수신자가 구독을 취소했습니다.
Email Reported As Spam	`message.email.reported_as_spam`	스팸으로 표시되었습니다. 이메일 전달 가능성을 참조하세요.
Email Bounced	`message.email.bounced`	영구적인 전달 실패로 인한 반송.
Email Failed	`message.email.failed`	전달이 실패했습니다.
Email Suppressed	`message.email.suppressed`	억제 목록으로 인해 억제되었습니다.
SMS Sent	`message.sms.sent`	SMS가 전송되었습니다.
SMS Delivered	`message.sms.delivered`	SMS가 성공적으로 전달되었습니다.
SMS Failed	`message.sms.failed`	SMS 전달이 실패했습니다.
SMS Undelivered	`message.sms.undelivered`	SMS가 거부되었거나 도달할 수 없습니다.

이벤트 데이터 스키마

사용자가 생성한 각 메시지 이벤트에 대해 다음 메타데이터가 레코드에 첨부됩니다.

열 이름	유형	설명
`event_id`	UUID	이벤트의 고유 식별자
`event_timestamp`	Timestamp	이벤트 발생 시간
`event_kind`	String	이벤트 종류
`subscription_device_type`	String	장치 유형(예: iOS, Android, Web, Email, SMS)
`language`	String	구독 언어 코드
`version`	String	통합 버전
`device_os`	String	장치 운영 체제 버전
`device_type`	Number	숫자 장치 유형
`token`	String	푸시 토큰, 전화번호 또는 이메일
`subscription_id`	UUID	구독 ID
`subscribed`	Boolean	구독 상태
`onesignal_id`	UUID	OneSignal 사용자 ID
`last_active`	String	마지막 활성 타임스탬프
`sdk`	String	OneSignal SDK 버전
`external_id`	String	통합 사용자 ID와 일치해야 하는 외부 사용자 ID
`app_id`	UUID	OneSignal의 앱 ID
`template_id`	UUID	템플릿 ID(해당하는 경우)
`message_id`	UUID	메시지 배치/요청 ID
`message_name`	String	메시지 이름
`message_title`	String	메시지 제목(영어만)
`message_contents`	String	잘린 메시지 본문(영어만)
`failure_reason`	String	실패 이유(푸시 실패 및 이메일 실패 이벤트용)
`_created`, `_id`, `_index`, `_fivetran_synced`	내부 사용	Fivetran 동기화 메타데이터

참고 사항

저장/활성화 후 동기화는 완료하는 데 추가로 15-30분이 소요될 수 있습니다.
비활성화하면 비활성화 후 최종 동기화가 한 번 더 발생할 수 있습니다.
효율적인 데이터 동기화를 보장하기 위해 시스템은 스테이징 데이터 세트를 자동으로 생성하고 관리합니다. 이러한 데이터 세트는 fivetran_{두 개의 무작위 단어}_staging과 같은 패턴으로 이름이 지정되며, 기본 스키마에 통합되기 전에 처리 중에 데이터를 임시로 저장합니다. 이러한 스테이징 데이터 세트는 간소화된 워크플로를 유지하는 데 필수적이며 자동으로 다시 생성되므로 삭제하면 안 됩니다.

BigQuery에서 이벤트 가져오기

BigQuery의 행동 이벤트 데이터를 OneSignal로 전송하여:

사용자 활동을 기반으로 Journeys 트리거
행동 데이터를 기반으로 메시징 개인화

요구 사항

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)

BigQuery 및 이벤트 데이터 테이블이 있는 GCP 프로젝트
읽기 권한이 있는 서비스 계정
BigQuery 데이터 세트에 행동 데이터가 포함된 이벤트 데이터 테이블

설정 단계

BigQuery 서비스 계정 만들기

OneSignal은 연결을 만들 때 자동으로 서비스 계정을 생성합니다. 또는 자체 서비스 계정 키 JSON 파일을 제공할 수 있습니다.자체 서비스 계정을 만드는 경우 아래에 나열된 필수 권한이 있는지 확인하세요.

필수 권한 부여

OneSignal 서비스 계정에는 다음 BigQuery IAM 역할이 필요합니다:

bigquery.dataViewer - 이벤트 데이터가 포함된 데이터 세트 및 테이블에 대한 읽기 액세스
bigquery.jobUser - 데이터 쿼리를 위한 작업 생성 권한
bigquery.metadataViewer - 프로젝트 수준 메타데이터 액세스(권장)

Google Cloud Console 또는 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

OneSignal에 통합 추가

OneSignal에서 Data > Integrations으로 이동하여 Add Integration을 클릭합니다.

동기화 엔진: 대규모 데이터 세트 또는 복잡한 이벤트 데이터 쿼리에는 고급 동기화가 권장됩니다. 기본 동기화로 시작한 다음 필요한 경우 나중에 고급 동기화로 전환할 수 있습니다.
Google Cloud 프로젝트 ID: BigQuery 데이터 세트가 포함된 GCP 프로젝트
데이터 세트 지역: BigQuery 데이터 세트가 저장된 위치
서비스 계정 키 (선택 사항): 자체 서비스 계정을 사용하는 경우 JSON 키 파일

이벤트 데이터 소스 구성

이벤트 데이터가 포함된 BigQuery 데이터 세트 및 테이블을 지정합니다:

데이터 세트: BigQuery 데이터 세트 이름(예: analytics_events)
테이블/뷰: 이벤트 레코드가 포함된 테이블 또는 뷰
이벤트 쿼리: 이벤트 데이터를 필터링하거나 변환하기 위한 선택적 SQL 쿼리

이벤트 테이블에는 다음에 대한 열이 포함되어야 합니다:

이벤트 이름/유형
사용자 식별자
이벤트 타임스탬프
추가 이벤트 속성

연결 테스트

연결 테스트를 클릭하여 OneSignal이 BigQuery 프로젝트에 액세스하고 이벤트 데이터를 읽을 수 있는지 확인합니다.

이벤트 데이터 매핑

를 OneSignal의 사용자 지정 이벤트 형식에 매핑합니다:

OneSignal 필드	설명	필수
`name`	`event_name`	이벤트 식별자	Yes
`external_id`	`user_id`	사용자 식별자	Yes
`timestamp`	`event_timestamp`	이벤트가 발생한 시간	No
`properties`	`event_data`	No

Sync Key는 동기화 중 각 행의 고유 식별자로 지정하는 열입니다. OneSignal은 이를 사용하여 행이 이미 처리되었는지 감지하므로, 데이터를 다시 동기화해도 중복 이벤트가 생성되지 않습니다. 행마다 고유한 텍스트 값을 가진 열을 선택하세요. 불리언 값이나 여러 행에서 반복되는 값은 사용하지 마세요.

고급 구성

사용자 지정 SQL 쿼리

OneSignal로 동기화하기 전에 사용자 지정 SQL을 사용하여 이벤트 데이터를 필터링하거나 변환합니다:

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)

교차 프로젝트 액세스

이벤트 데이터가 여러 BigQuery 프로젝트에 걸쳐 있는 경우 참조된 테이블 또는 뷰가 포함된 각 프로젝트에 OneSignal 서비스 계정 액세스를 부여합니다.

최적의 성능을 위해 BigQuery 연결 지역이 특정 테이블 지역과 일치해야 합니다.

FAQ

동기화가 실패하는 이유는 무엇인가요?

동기화가 실패하는 몇 가지 일반적인 이유가 있습니다:

서비스 계정에 필요한 권한이 없습니다
소스 데이터 세트가 기본 동기화에 비해 너무 크며 고급 동기화를 사용해야 합니다

위의 설정 단계를 검토하고 올바르게 따랐는지 확인하세요. 여전히 문제가 있는 경우 support@onesignal.com에 문의하세요.

동일한 콘텐츠에 대해 여러 메시지 ID가 표시되는 이유는 무엇인가요?

일반적으로 메시지 템플릿이 여러 전송 또는 트리거된 플로우에서 재사용될 때 발생합니다.

OneSignal은 얼마나 자주 데이터를 동기화하나요?

내보내기 및 가져오기 통합 모두 15분마다 동기화할 수 있습니다.

BigQuery 뷰를 사용할 수 있나요?

예. 서비스 계정이 뷰에서 참조된 모든 테이블에 액세스할 수 있는지 확인하기만 하면 됩니다.

시작하기 & 설정

메시지 채널

Journeys

오디언스 & 사용자 지정 이벤트

분석 & 통합

개인 정보 보호 & 보안

개요