Google BigQuery 통합

개발자 지원 필요

통합을 설정하려면 개발팀 또는 Google Cloud 관리자의 도움이 필요합니다. 이 가이드를 그들과 공유해 주세요.

Google BigQuery 통합은 선택한 Pushwoosh 메시지 이벤트를 BigQuery 데이터 세트로 스트리밍합니다. 이를 사용하여 BigQuery에서 푸시, 이메일, SMS 라이프사이클 이벤트를 분석하고, 맞춤 보고서를 작성하거나, 데이터를 다운스트림 분석 워크플로우에 연결할 수 있습니다.

통합 개요

전제 조건

통합 설정을 열기 전에 다음을 준비하세요.

1. 결제가 활성화된 Google Cloud 프로젝트를 사용하세요. 무료 체험 크레딧이 지원됩니다. Storage Write API는 결제가 필요하므로 BigQuery 샌드박스로는 충분하지 않습니다.

2. 유료 Pushwoosh 계정이 있는지 확인하세요.

가격

BigQuery 사용 요금은 Google에 직접 지불합니다. Pushwoosh는 통합 자체에 대해 요금을 부과하지 않습니다.

현재 요금, 무료 등급 및 지역별 세부 정보는 BigQuery 가격을 참조하세요.

비용에는 다음이 포함될 수 있습니다:

• 데이터 수집: Pushwoosh는 BigQuery Storage Write API를 사용하여 이벤트를 스트리밍합니다.
• 스토리지: BigQuery는 대상 테이블에 작성된 행을 저장합니다.
• 쿼리: BigQuery는 선택한 가격 모델에 따라 쿼리 요금을 부과합니다.

통합 유형

소스: 데이터는 Pushwoosh에서 BigQuery 데이터 세트로 전송됩니다.

지원되는 플랫폼

Pushwoosh는 iOS, Android, Huawei, Chrome, Safari, Firefox 및 웹 플랫폼에서 이벤트를 스트리밍합니다.

동기화된 엔티티

선택한 푸시, 이메일, SMS 라이프사이클 이벤트가 BigQuery로 스트리밍됩니다. Pushwoosh는 선택한 이벤트당 하나의 행을 대상 테이블에 작성합니다.

사용 사례

• 거의 실시간 메시지 분석: Pushwoosh에서 처리된 직후 BigQuery에서 푸시, 이메일, SMS 라이프사이클 이벤트를 분석합니다.
• 맞춤 보고: 선택한 이벤트 종류, 애플리케이션, 캠페인 및 메시지 식별자에 대한 BigQuery 보고서를 작성합니다.
• 다운스트림 데이터 워크플로우: Pushwoosh 이벤트 데이터를 분석, 보고 또는 데이터 처리 워크플로우에 연결합니다.

통합 작동 방식

구성을 저장하면 Pushwoosh는 선택한 메시지 이벤트를 거의 실시간으로 BigQuery 테이블로 스트리밍하기 시작합니다. Pushwoosh를 통해 흐르는 모든 메시지 이벤트에 대해 시스템은 이벤트 종류가 구성에서 선택되었는지 확인합니다.

선택된 경우 Pushwoosh는 대상 테이블에 새 행을 추가합니다. 테이블이 아직 존재하지 않으면 Pushwoosh는 아래 설명된 스키마를 사용하여 자동으로 생성합니다. 이벤트는 일반적으로 Pushwoosh에서 처리된 후 30초 이내에 BigQuery에 나타납니다.

Google Cloud에서 통합 설정

Google Cloud 프로젝트 선택

Google Cloud Console에 로그인한 다음 BigQuery 데이터 세트를 소유할 프로젝트를 선택하거나 생성합니다.

팁

프로젝트 ID를 기록해 두세요. 사람이 읽을 수 있는 프로젝트 이름이 아닌 my-company-12345와 같은 짧은 식별자를 사용하세요.

필수 API 활성화

Google Cloud Console에서 API 및 서비스 → 라이브러리로 이동하여 다음 API를 활성화합니다:

• BigQuery API
• BigQuery Storage API

Pushwoosh는 이러한 API를 사용하여 대상 테이블을 만들고 이벤트를 BigQuery로 스트리밍합니다.

서비스 계정 생성

Pushwoosh는 서비스 계정을 사용하여 BigQuery 데이터 세트에 이벤트를 작성합니다.

1. IAM 및 관리자 → 서비스 계정으로 이동합니다.

2. 서비스 계정 만들기를 클릭합니다.

3. 서비스 계정 이름에 pushwoosh-bigquery와 같은 이름을 입력합니다.

   Google Cloud는 이름에서 서비스 계정 ID를 자동으로 생성합니다.

   

4. 만들고 계속하기를 클릭합니다.

IAM 역할 부여

1. 서비스 계정에 다음 IAM 역할을 부여합니다:

   • BigQuery 데이터 편집자: Pushwoosh가 테이블을 만들고 행을 추가할 수 있도록 합니다.
   • BigQuery 사용자: Pushwoosh가 Storage Write API를 사용할 수 있도록 합니다.
   

참고

역할은 프로젝트 수준 또는 데이터 세트 수준에서 연결할 수 있습니다. 프로젝트 수준 액세스가 가장 설정하기 쉽습니다. 데이터 세트 수준 액세스는 더 제한적이며 프로덕션 환경에 권장됩니다.

2. 계속을 클릭합니다.

3. 완료를 클릭합니다.

JSON 키 생성

Pushwoosh는 JSON 키를 사용하여 서비스 계정으로 인증합니다.

1. 생성한 서비스 계정을 엽니다.

2. 키 → 키 추가 → 새 키 만들기로 이동합니다.

3. JSON을 선택합니다.

Google Cloud가 JSON 키 파일을 컴퓨터에 다운로드합니다.

주의

JSON 키 파일을 안전하게 보관하세요. 이 파일을 가진 사람은 누구나 BigQuery 프로젝트에 쓸 수 있습니다. git에 커밋하거나 채팅을 통해 공유하지 마세요. Pushwoosh는 키를 저장 시 암호화하며 업로드 후 UI를 통해 노출하지 않습니다.

데이터 세트 생성

데이터 세트는 Pushwoosh가 스트리밍된 이벤트 테이블을 저장하는 곳입니다.

1. Google Cloud Console에서 BigQuery를 엽니다.

2. 탐색기에서 통합을 위해 준비한 프로젝트를 선택합니다.

3. 데이터 세트 만들기를 클릭합니다.

4. 데이터 세트 ID에 pushwoosh_data와 같은 데이터 세트 ID를 입력합니다.

5. 데이터 위치에서 데이터 세트 지역을 선택합니다.

6. 데이터 세트 만들기를 클릭합니다.

Pushwoosh에서 통합 구성

1. Pushwoosh 계정에서 연결하려는 애플리케이션의 설정 → 타사 통합으로 이동합니다.

2. 사용 가능한 서비스 목록에서 Google BigQuery를 찾아 구성을 클릭합니다.

3. 구성 필드를 채웁니다.

• GCP 프로젝트 ID: Google Cloud의 프로젝트 ID(예: my-company-12345)를 입력합니다.
• 서비스 계정 JSON: Google Cloud에서 다운로드한 JSON 키 파일의 전체 내용을 붙여넣습니다.
• 데이터 세트 ID: GCP 프로젝트 ID와 서비스 계정 JSON이 채워지면 Pushwoosh는 서비스 계정이 액세스할 수 있는 데이터 세트를 가져옵니다. 대상 데이터 세트를 선택합니다. 드롭다운이 비어 있으면 서비스 계정에 액세스 권한이 있고 지정한 프로젝트에 데이터 세트가 있는지 확인하세요.
• 데이터 세트 지역: BigQuery 데이터 세트의 지역을 선택합니다.
• 테이블 이름: 기본 pushwoosh_events 테이블을 사용하려면 비워 둡니다. Pushwoosh는 아래 설명된 스키마로 테이블을 만듭니다.
• 이벤트: 스트리밍할 이벤트를 선택합니다. 이 목록은 나중에 변경할 수 있습니다.
• BigQuery로 이벤트 스트리밍: 이 토글을 활성화합니다. 구성을 삭제하지 않고 스트리밍을 일시 중지하려면 끕니다.

4. 연결 테스트를 클릭합니다.

Pushwoosh는 데이터를 쓰지 않고 BigQuery에 대해 자격 증명을 확인합니다.

다음 연결 상태 중 하나가 표시될 수 있습니다:

• 연결 성공: 자격 증명이 작동하고 서비스 계정이 데이터 세트에 액세스할 수 있습니다.
• auth_failed: JSON 키가 유효하지 않거나 해지되었습니다.
• dataset_not_found: 데이터 세트 ID가 잘못되었거나 서비스 계정이 액세스할 수 없습니다.
• missing_permission: 서비스 계정에 필요한 역할 중 하나가 없습니다.

5. 적용을 클릭합니다.

Pushwoosh는 구성을 저장하고 약 30초 이내에 사용하기 시작합니다. 그 후 선택한 이벤트가 BigQuery로 스트리밍되기 시작합니다.

통합 확인

1. 테스트 푸시를 보내거나 선택한 이벤트 종류 중 하나를 생성하는 다른 메시지를 트리거합니다.

2. 약 30초 정도 기다립니다.

3. BigQuery Studio를 엽니다.

4. 프로젝트로 이동한 다음 구성한 데이터 세트와 대상 테이블을 엽니다. 테이블 이름을 비워 둔 경우 pushwoosh_events를 엽니다.

5. 미리보기를 클릭합니다.

테이블에 이벤트 행이 표시되어야 합니다.

테이블 스키마

Pushwoosh는 선택한 각 이벤트를 대상 테이블에 별도의 행으로 작성합니다. 쿼리를 더 빠르고 쉽게 필터링할 수 있도록 테이블은 timestamp를 사용하여 일별로 파티셔닝되고 app_id 및 event_kind로 클러스터링됩니다.

필드 이름	유형	설명
event_kind	STRING	Pushwoosh 이벤트 종류, 예: Push Sent 또는 Email Opened.
message_id	STRING	캠페인 또는 메시지 식별자와 같은 Pushwoosh 메시지 코드.
device_id	STRING	이벤트를 생성한 장치의 Pushwoosh 하드웨어 ID.
user_id	STRING	알려진 경우 외부 사용자 ID. 익명 장치의 경우 비어 있습니다.
timestamp	TIMESTAMP	UTC 기준 이벤트 시간.
app_id	STRING	Pushwoosh 애플리케이션 코드.
platform	STRING	소스 플랫폼, 예: ios, android 또는 web.
properties	JSON	추가 이벤트 필드. 아래와 같이 JSON_VALUE를 사용하여 필드를 쿼리합니다.

속성 쿼리

properties 열은 추가 이벤트 필드를 JSON으로 저장합니다. JSON_VALUE를 사용하여 쿼리에서 개별 필드를 추출합니다.

예를 들어, 지난 7일 동안 가장 많은 열람을 유도한 캠페인을 보려면 **+**를 클릭하여 새 쿼리를 만들고 아래 SQL을 붙여넣은 다음 실행을 클릭합니다.

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

지난 한 시간 동안의 이벤트 수를 검토하려면 다음 쿼리를 실행합니다:

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

통합 업데이트

서비스 계정 키 순환

1. Google Cloud Console에서 IAM 및 관리자 → 서비스 계정으로 이동합니다.

2. 서비스 계정을 엽니다.

3. 키로 이동하여 새 JSON 키를 만듭니다.

4. 새 키가 작동하는지 확인할 때까지 이전 키를 활성 상태로 유지합니다.

5. Pushwoosh에서 Google BigQuery 구성 모달을 엽니다.

6. 새 JSON을 서비스 계정 JSON에 붙여넣습니다.

7. 적용을 클릭합니다.

Pushwoosh는 새 키를 확인하고 저장된 자격 증명을 교체하며 약 30초가 걸리는 다음 구성 재로드 후 사용하기 시작합니다.

이벤트가 계속 흐르는 것을 확인한 후 Google Cloud Console에서 이전 키를 삭제합니다.

대상 데이터 세트 또는 테이블 변경

1. Pushwoosh에서 설정 → 타사 통합으로 이동합니다.

2. Google BigQuery 설정을 엽니다.

3. 다른 데이터 세트를 선택하거나 새 테이블 이름을 입력합니다.

4. 적용을 클릭합니다.

Pushwoosh는 약 30초 이내에 새 대상으로 스트림을 다시 엽니다. 이미 작성된 행은 이전 테이블에 남아 있습니다. Pushwoosh는 과거 데이터를 백필하지 않습니다.

다른 설정을 업데이트할 때 저장된 서비스 계정 키를 변경하지 않으려면 적용을 클릭하기 전에 서비스 계정 JSON을 비워 둡니다.

문제 해결

문제	확인할 사항
auth_failed로 연결 테스트 실패	서비스 계정 JSON이 잘못되었거나 Google Cloud에서 키가 해지되었습니다. 새 키를 만들고 전체 JSON 파일을 다시 붙여넣으세요. 파일은 {로 시작하고 }로 끝나며 private_key 블록을 포함합니다.
dataset_not_found로 연결 테스트 실패	데이터 세트 ID에 오타가 있거나 지정한 프로젝트에 존재하지 않습니다. 데이터 세트 ID는 대소문자를 구분합니다. 오타를 피하려면 드롭다운에서 데이터 세트를 선택하세요.
missing_permission으로 연결 테스트 실패	서비스 계정에 BigQuery 데이터 편집자 또는 BigQuery 사용자가 없습니다. 프로젝트 수준에서 두 역할을 모두 부여하거나, 더 제한적인 액세스를 위해 데이터 세트 수준에서 부여하세요.
연결 테스트는 통과했지만 BigQuery에 행이 나타나지 않음	최소 30초 기다리세요. 보내는 이벤트 종류가 이벤트에서 선택되었는지 확인하세요. 예를 들어, Push Opened만 선택되었고 아무도 푸시를 열지 않으면 행이 나타나지 않습니다.
구성은 올바르게 보이지만 모달에 빈 필드가 표시됨	페이지를 새로고침하세요. 구성은 각 모달이 열릴 때마다 가져오며 기본 서비스에 의해 30초 동안 캐시됩니다. 설정을 방금 저장했다면 잠시 기다렸다가 모달을 다시 여세요.

참고

Pushwoosh는 BigQuery 집계가 정식 Pushwoosh 통계와 일치하도록 전송 상태에 관계없이 Push Sent, Email Sent, SMS Sent를 기록합니다. Delivered, Opened, Bounced, Unsubscribed의 경우 Pushwoosh는 성공적인 이벤트만 기록합니다.

FAQ

무료 Google Cloud 계정을 사용할 수 있나요?

예, 프로젝트에서 결제가 활성화되어 있는 한 가능합니다. 무료 체험 크레딧은 전체 체험 기간 동안 일반적인 볼륨으로 이 통합을 실행하기에 충분합니다. Storage Write API는 결제가 필요하므로 결제 없는 BigQuery 샌드박스는 작동하지 않습니다.

Pushwoosh가 내 BigQuery 데이터를 볼 수 있나요?

아니요. 업로드하는 서비스 계정 자격 증명은 Pushwoosh가 선택한 데이터 세트에 쓰도록 승인합니다. Pushwoosh는 데이터 세트에서 읽지 않으며 프로젝트의 나머지 부분에 액세스할 수 없습니다.

여러 BigQuery 데이터 세트로 내보낼 수 있나요?

애플리케이션당 하나의 대상이 지원됩니다. 두 데이터 세트에 동일한 이벤트가 필요한 경우 프로젝트에서 BigQuery 예약 쿼리를 설정하여 pushwoosh_events에서 다른 테이블로 데이터를 복사하세요.

테이블 스키마를 변경할 수 있나요?

스키마는 모든 고객에게 고정되어 있습니다. 추가 열이 필요한 경우 자체 뷰 또는 예약된 쿼리에서 properties JSON에서 추출하세요.

통합을 일시적으로 비활성화하면 어떻게 되나요?

BigQuery로 이벤트 스트리밍을 끄고 적용을 클릭하세요. Pushwoosh는 약 30초 이내에 이 애플리케이션에 대한 이벤트 추가를 중지합니다.

통합이 꺼져 있는 동안 생성된 이벤트는 다시 켤 때 버퍼링되거나 백필되지 않습니다. Pushwoosh는 자격 증명, 데이터 세트 및 이벤트 선택을 포함한 구성을 유지합니다.

통합을 완전히 삭제하려면 어떻게 해야 하나요?

통합 구성을 삭제하려면 support@pushwoosh.com에 문의하세요. 데이터 세트와 이미 BigQuery에 작성된 행은 Google Cloud 계정에 남아 있습니다.

전송 보장이 있나요?

통합은 최소 한 번 전송을 사용합니다. 정상적인 작동 하에서는 중복이 드뭅니다. 추가와 커밋 사이에 프로세스가 다시 시작되면 소수의 중복 행이 생성될 수 있습니다. 다운스트림 파이프라인에 정확히 한 번 결과가 필요한 경우 SQL에서 중복을 제거하세요.

Push Clicked 이벤트가 없는 이유는 무엇인가요?

Pushwoosh는 현재 이 통합에서 푸시 알림에 대해 Push Sent, Push Delivered, Push Opened를 노출합니다. 전용 푸시 클릭 단계는 사용할 수 없습니다. 이메일과 SMS에는 자체 라이프사이클 이벤트가 있습니다.