Mixpanel 커넥터
Tajo를 통해 Mixpanel을 Brevo에 연결하여 제품 분석과 마케팅 자동화를 연결합니다. 사용자 프로필, 행동 이벤트, 코호트를 동기화하여 실제 제품 사용 데이터를 기반으로 한 캠페인을 만들 수 있습니다.
개요
| 속성 | 값 |
|---|---|
| 플랫폼 | Mixpanel |
| 카테고리 | 분석 (Custom) |
| 설정 복잡도 | 중간 |
| 공식 통합 | 아니오 |
| 동기화 데이터 | 이벤트, 프로필, 코호트, 그룹 |
| 사용 가능한 스킬 | 7 |
기능
- 이벤트 수집 - Mixpanel의 Ingestion API를 통해 track 이벤트를 Brevo 워크플로로 가져오기
- 사용자 프로필 동기화 - Mixpanel 사용자 프로필 속성을 Brevo 연락처 속성에 매핑
- 코호트 내보내기 - Mixpanel 코호트를 Brevo 연락처 목록으로 동기화하여 타겟 캠페인 실행
- 그룹 분석 - B2B 계정 기반 마케팅을 위한 그룹 레벨 데이터 동기화
- 아이덴티티 관리 - Mixpanel의 아이덴티티 병합을 활용하여 통합 고객 프로필 생성
- JQL 쿼리 - 특정 데이터 세트를 추출하는 맞춤 JQL 쿼리를 Brevo용으로 실행
- 조회 테이블 - Mixpanel 조회 테이블의 보강 데이터 동기화
사전 요구 사항
시작하기 전에 다음이 준비되어 있는지 확인하십시오.
- 프로젝트가 생성된 Mixpanel 계정
- 클라이언트 측 추적을 위한 Mixpanel 프로젝트 토큰
- 서버 측 API 접근에 필요한 적절한 권한의 서비스 계정
- API 접근이 가능한 Brevo 계정
- API 자격 증명이 있는 Tajo 계정
인증
서비스 계정 (권장)
Mixpanel은 API 인증에 서비스 계정 사용을 권장합니다. 서비스 계정은 사용자 이름(서비스 계정 사용자 이름)과 비밀번호(서비스 계정 시크릿)로 HTTP Basic Auth를 사용합니다.
# 서비스 계정 인증curl https://mixpanel.com/api/app/me \ -u "SERVICE_ACCOUNT_USERNAME:SERVICE_ACCOUNT_SECRET"프로젝트 토큰
프로젝트 토큰은 클라이언트 측 이벤트 추적에 사용되며, 클라이언트 코드에 포함해도 안전합니다.
// 클라이언트 측 초기화mixpanel.init("YOUR_PROJECT_TOKEN");OAuth (파트너 통합용)
여러 프로젝트에 접근하는 앱 통합의 경우:
curl https://mixpanel.com/api/2.0/engage \ -H "Authorization: Bearer YOUR_OAUTH_TOKEN"구성
기본 설정
connectors: mixpanel: enabled: true project_token: "your-project-token" service_account: username: "your-service-account-username" secret: "your-service-account-secret" project_id: "12345" data_residency: "US" # 또는 "EU"
# 데이터 동기화 옵션 sync: events: true profiles: true cohorts: true groups: false
# Brevo 목록 할당 lists: all_users: 15 engaged_users: 16 at_risk: 17이벤트 매핑
Mixpanel 이벤트를 Brevo 이벤트 유형에 매핑합니다.
event_mapping: # Mixpanel 이벤트 -> Brevo 이벤트 "Purchase": "order_completed" "Sign Up": "customer_created" "Add to Cart": "cart_updated" "Page View": "page_viewed" "$experiment_started": "experiment_started"
# 맞춤 이벤트 "Feature Activated": "feature_used" "Subscription Renewed": "subscription_renewed"프로필 속성 매핑
Mixpanel 사용자 속성을 Brevo 연락처 속성에 매핑합니다.
property_mapping: $email: email $first_name: FIRSTNAME $last_name: LASTNAME $phone: SMS $city: CITY $region: REGION $country_code: COUNTRY plan: PLAN_TYPE company: COMPANY signup_date: SIGNUP_DATE total_revenue: LTVAPI 엔드포인트
| 메서드 | 엔드포인트 | 설명 |
|---|---|---|
POST | /import | 이벤트 가져오기 (Ingestion API) |
POST | /track | 이벤트 추적 (클라이언트 측) |
POST | /engage#$set | 사용자 프로필 속성 설정 |
POST | /engage#$set_once | 아직 설정되지 않은 경우에만 속성 설정 |
POST | /engage#$delete | 사용자 프로필 삭제 |
POST | /engage#$union | 목록 속성에 합집합 추가 |
POST | /groups | 그룹 프로필 속성 설정 |
GET | /export | 원시 이벤트 데이터 내보내기 |
POST | /cohorts/list | 저장된 코호트 목록 가져오기 |
POST | /engage/query | 사용자 프로필 쿼리 |
POST | /jql | 맞춤 JQL 쿼리 실행 |
GET | /segmentation | 세그먼테이션 보고서 쿼리 |
GET | /retention | 리텐션 보고서 쿼리 |
GET | /funnels | 퍼널 보고서 쿼리 |
코드 예제
Mixpanel 커넥터 초기화
import { TajoClient } from '@tajo/sdk';
const tajo = new TajoClient({ apiKey: process.env.TAJO_API_KEY, brevoApiKey: process.env.BREVO_API_KEY});
// Mixpanel 프로젝트 연결await tajo.connectors.connect('mixpanel', { projectToken: process.env.MIXPANEL_TOKEN, serviceAccountUser: process.env.MIXPANEL_SA_USER, serviceAccountSecret: process.env.MIXPANEL_SA_SECRET, projectId: process.env.MIXPANEL_PROJECT_ID});Ingestion API를 통한 이벤트 가져오기
// Mixpanel로 이벤트 가져오기 (자동으로 Brevo에 전달됨)const response = await fetch('https://api.mixpanel.com/import', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Basic ' + btoa( `${process.env.MIXPANEL_SA_USER}:${process.env.MIXPANEL_SA_SECRET}` ) }, body: JSON.stringify([ { event: "Purchase", properties: { distinct_id: "user_123", $insert_id: "evt_abc123", time: Math.floor(Date.now() / 1000), revenue: 89.99, product_id: "SKU-001", product_name: "Widget Pro" } } ])});
// 예상 응답: { "code": 200, "status": "OK", "num_records_imported": 1 }코호트를 Brevo로 동기화
// Mixpanel 코호트를 내보내서 Brevo 목록으로 동기화const cohort = await tajo.connectors.syncCohort('mixpanel', { cohortId: 12345, targetList: 16, syncMode: 'mirror'});
console.log(cohort);// {// cohortName: "Engaged Users (Last 7 Days)",// membersCount: 3200,// syncedToBrevo: 3200,// listId: 16// }사용자 프로필 속성 설정
// Engage API를 통해 사용자 속성 설정const response = await fetch('https://api.mixpanel.com/engage#$set', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify([{ $token: process.env.MIXPANEL_TOKEN, $distinct_id: "user_123", $set: { $first_name: "Jane", $last_name: "Kim", plan: "premium", total_orders: 12, lifetime_value: 1250.00 } }])});속도 제한
| API | 제한 | 세부 사항 |
|---|---|---|
| Ingestion API | 2 GB/분 | 프로젝트당 |
| Track API | 하드 제한 없음 | 최선 노력 전달 |
| Engage API | 배치당 2,000개 업데이트 | 프로젝트당 최대 2 GB/분 |
| Query API | 시간당 60 요청 | 프로젝트당 (서비스 계정) |
| Export API | 시간당 60 요청 | 쿼리당 최대 100일 |
| JQL API | 시간당 60 요청 | 프로젝트당 |
| Cohort Export | 시간당 60 요청 | 프로젝트당 |
이벤트 중복 제거
Mixpanel은 $insert_id 속성을 사용하여 이벤트를 중복 제거합니다. 실패한 가져오기를 재시도할 때 중복 이벤트를 방지하기 위해 항상 고유한 $insert_id를 포함하십시오.
문제 해결
| 문제 | 원인 | 해결 방법 |
|---|---|---|
| 이벤트가 나타나지 않음 | 잘못된 프로젝트 토큰 | 토큰이 대상 프로젝트와 일치하는지 확인 |
| 프로필 속성 누락 | 잘못된 API 사용 | 프로필 속성에는 /track이 아닌 /engage#$set 사용 |
| 코호트 내보내기 실패 | 권한 부족 | 서비스 계정에 Admin 또는 Analyst 역할이 있는지 확인 |
| 중복 이벤트 | $insert_id 누락 | 모든 이벤트에 고유한 $insert_id를 포함 |
| 402 결제 필요 | 데이터 한도 초과 | Mixpanel 플랜 한도를 확인하고 필요한 경우 업그레이드 |
| EU 데이터가 라우팅되지 않음 | 잘못된 데이터 레지던시 | EU 프로젝트에는 api-eu.mixpanel.com 사용 |
| 아이덴티티 병합 문제 | 잘못된 distinct_id | Mixpanel의 아이덴티티 관리 모범 사례 준수 |
모범 사례
- 서비스 계정 사용 - 서버 측 인증에는 프로젝트 시크릿보다 서비스 계정 선호
$insert_id포함 - 이벤트 중복 제거를 위해 항상 고유한 insert ID 설정- 프로필 업데이트 배치 처리 - 효율성을 위해 요청당 최대 2,000개의 프로필 업데이트 전송
- EU 엔드포인트 사용 - EU 데이터 레지던시를 위해 모든 API 호출에
api-eu.mixpanel.com사용 - 예약된 일정에 따라 코호트 동기화 - 지속적인 폴링보다는 매일 또는 매주 코호트 동기화 설정
- 예약된 속성 매핑 - 프로필 데이터에는 Mixpanel의 예약된 속성(
$email,$first_name) 사용 - 수집 모니터링 - Mixpanel의 Events 페이지를 사용하여 이벤트가 올바르게 수신되고 있는지 확인
보안
- HTTPS 전용 - 모든 API 통신에 TLS 암호화 필요
- 서비스 계정 격리 - 역할 기반 권한으로 프로젝트당 범위 지정 접근
- 이벤트 중복 제거 -
$insert_id를 통한 내장 중복 제거로 데이터 무결성 문제 방지 - SOC 2 Type II - Mixpanel은 SOC 2 Type II 인증을 받음
- GDPR/CCPA - GDPR API를 통한 사용자 데이터 삭제 지원
- EU 데이터 레지던시 - 유럽 규정 준수를 위한 EU 데이터 센터 사용 가능