언리얼 엔진 SDK - 인앱 이벤트 트래킹

팔로우
Avatar
Eyal Rabinovich
Updated
문서

인앱 이벤트 추적

인앱 이벤트를 추적하여 캠페인 성과를 분석하고 사용자 로그인, 등록, 튜토리얼 완료 또는 진행 상황 마일스톤과 같은 핵심 성과 지표(KPI)를 측정할 수 있습니다.

이벤트 구현 가이드라인

이벤트 네이밍 모범 사례

SendEvent 및 SendEventWithArgs 메서드를 사용하여 설명이 포함된 이벤트 이름과 보강된 데이터에 대한 선택적 속성을 사용하여 이벤트를 Singular로 전송하세요.

이벤트 이름 권장 사항:

  • 언어: 타사 파트너 및 분석 솔루션과의 호환성을 보장하기 위해 이벤트 이름과 속성을 영어로 전달하세요.
  • 이벤트 이름: 32자로 제한됩니다. ASCII가 아닌 문자열은 UTF-8로 변환할 때 32바이트 미만이어야 합니다.
  • 속성 및 값: ASCII 500자로 제한

UA, 마케팅 또는 비즈니스 팀은 조직의 마케팅 KPI에 따라 이벤트 목록을 컴파일해야 합니다. 인앱 이벤트 추적 방법가이드를 참조하세요 : Singular 어트리뷰션 고객을 위한 가이드에서계획을 세우세요.

이벤트 전송

간단한 이벤트 추적

로그인, 튜토리얼 완료 또는 레벨 업과 같은 사용자 행동을 추적하기 위해 사용자 지정 이벤트 이름을 사용하여 기본 사용자 이벤트를 Singular로 전송합니다.

C++ 
// Send an event without any parameters, just a name
USingularSDKBPLibrary::SendEvent(TEXT("Login"));

// Example: Track tutorial completion
USingularSDKBPLibrary::SendEvent(TEXT("TutorialComplete"));

// Example: Track level progression
USingularSDKBPLibrary::SendEvent(TEXT("LevelUp"));

메서드 서명: 

static void SendEvent(FString eventName);

속성을 사용한 이벤트 추적

추가 사용자 지정 매개변수와 함께 사용자 이벤트를 전송하여 레벨 번호, 아이템 ID 또는 사용자 행동과 같은 컨텍스트 정보를 캡처하세요.

C++ 
// Example 1: Login with user tier
TMap<FString, FString> LoginArgs;
LoginArgs.Add(TEXT("user_tier"), TEXT("premium"));
LoginArgs.Add(TEXT("login_method"), TEXT("email"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("Login"), LoginArgs);

// Example 2: Tutorial completion with metadata
TMap<FString, FString> TutorialArgs;
TutorialArgs.Add(TEXT("tutorial_name"), TEXT("BasicControls"));
TutorialArgs.Add(TEXT("completion_time"), TEXT("120"));
TutorialArgs.Add(TEXT("difficulty"), TEXT("easy"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("TutorialComplete"), TutorialArgs);

// Example 3: Level progression with game state
TMap<FString, FString> LevelArgs;
LevelArgs.Add(TEXT("level_number"), TEXT("5"));
LevelArgs.Add(TEXT("character_class"), TEXT("warrior"));
LevelArgs.Add(TEXT("total_playtime"), TEXT("3600"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("LevelUp"), LevelArgs);

// Example 4: Item purchase with details
TMap<FString, FString> PurchaseArgs;
PurchaseArgs.Add(TEXT("item_id"), TEXT("sword_legendary_001"));
PurchaseArgs.Add(TEXT("item_category"), TEXT("weapons"));
PurchaseArgs.Add(TEXT("item_rarity"), TEXT("legendary"));
USingularSDKBPLibrary::SendEventWithArgs(TEXT("ItemPurchased"), PurchaseArgs);

메소드 서명: 

static void SendEventWithArgs(FString eventName, TMap<FString, FString> args);

모범 사례: 추적 중인 데이터를 명확하게 나타내는 설명적인 속성 이름을 사용하세요. 이렇게 하면 데이터 분석이 향상되고 마케팅 팀이 보고서를 더 쉽게 이해할 수 있습니다.

인앱 구매 추적

인앱 구매(IAP), 구독 및 사용자 지정 구매원의 구매을 추적하여 캠페인 성과와 광고 비용 대비 구매률(ROAS)을 측정할 수 있습니다.

구매 데이터는 세 가지 채널을 통해 전달됩니다:

  • 인터랙티브 보고서: Singular 대시보드에서 구매 지표를 볼 수 있습니다.
  • 로그 내보내기: 사용자 지정 분석을 위해 상세한 ETL 데이터에 액세스
  • 실시간 포스트백: 구매 이벤트를 외부 플랫폼으로 전송

통화 변환: 다른 통화로 표시된 구매은 Singular 계정에 설정된 조직의 기본 통화로 자동 변환됩니다.

구매 이벤트 가이드라인

구매 이벤트 제한 사항

구매 이벤트 요구사항:

  • 이벤트 이름: 사용자 지정 구매 이벤트 이름은 32자(UTF-8로 변환할 경우 32바이트)로 제한됩니다(ASCII가 아닌 경우 32바이트).
  • 속성: 이벤트 속성 이름 및 값은 500자로 제한됩니다.
  • 통화 코드: 모두 대문자이어야 하며 3글자 ISO 4217 표준을따라야 합니다(예: USD, EUR, INR, GBP, JPY).

구매 이벤트 보내기

간단한 구매 추적

이벤트 이름, 통화 코드, 거래 금액이 포함된 구매 이벤트를 Singular로 전송하여 기본 구매 데이터를 추적하세요.

C++ 
// Example 1: Basic purchase tracking
USingularSDKBPLibrary::SendRevenue(TEXT("Purchase Completed"), TEXT("USD"), 9.99f);

// Example 2: Subscription purchase
USingularSDKBPLibrary::SendRevenue(TEXT("SubscriptionPurchase"), TEXT("USD"), 29.99f);

// Example 3: In-game currency purchase
USingularSDKBPLibrary::SendRevenue(TEXT("CoinPackagePurchase"), TEXT("EUR"), 4.99f);

// Example 4: Premium item purchase
USingularSDKBPLibrary::SendRevenue(TEXT("PremiumItemPurchase"), TEXT("GBP"), 19.99f);

메소드 서명: 

static void SendRevenue(FString eventName, FString currency, float amount);

참고: 통화를 'USD', 'EUR', 'INR'과 같은 세 글자 ISO 4217 통화 코드로 전달합니다.

속성을 사용한 구매 추적

추가 사용자 지정 매개변수와 함께 구매 이벤트를 전송하여 제품 SKU, 카테고리 또는 프로모션 코드와 같은 거래 세부 정보를 캡처하세요.

C++ 
// Example 1: Revenue with product details
TMap<FString, FString> PurchaseArgs;
PurchaseArgs.Add(TEXT("product_id"), TEXT("coin_pack_100"));
PurchaseArgs.Add(TEXT("product_name"), TEXT("100 Coin Pack"));
PurchaseArgs.Add(TEXT("product_category"), TEXT("currency"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("Purchase Completed"), 
    TEXT("USD"), 
    4.99f, 
    PurchaseArgs
);

// Example 2: Subscription with billing details
TMap<FString, FString> SubArgs;
SubArgs.Add(TEXT("subscription_tier"), TEXT("premium"));
SubArgs.Add(TEXT("billing_period"), TEXT("monthly"));
SubArgs.Add(TEXT("trial_period"), TEXT("false"));
SubArgs.Add(TEXT("renewal_count"), TEXT("3"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("SubscriptionRenewal"), 
    TEXT("USD"), 
    9.99f, 
    SubArgs
);

// Example 3: Purchase with promotional discount
TMap<FString, FString> PromoArgs;
PromoArgs.Add(TEXT("product_id"), TEXT("bundle_mega_001"));
PromoArgs.Add(TEXT("promo_code"), TEXT("SUMMER2025"));
PromoArgs.Add(TEXT("discount_amount"), TEXT("5.00"));
PromoArgs.Add(TEXT("original_price"), TEXT("19.99"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("BundlePurchase"), 
    TEXT("USD"), 
    14.99f, 
    PromoArgs
);

// Example 4: IAP with transaction metadata
TMap<FString, FString> IAPArgs;
IAPArgs.Add(TEXT("platform"), TEXT("google_play"));
IAPArgs.Add(TEXT("transaction_id"), TEXT("GPA.1234-5678-90AB"));
IAPArgs.Add(TEXT("item_type"), TEXT("consumable"));
IAPArgs.Add(TEXT("user_level"), TEXT("42"));
USingularSDKBPLibrary::SendRevenueWithArgs(
    TEXT("IAP_Consumable"), 
    TEXT("USD"), 
    2.99f, 
    IAPArgs
);

방법 서명: 

static void SendRevenueWithArgs(FString eventName, FString currency, float amount, TMap<FString, FString> args);

모범 사례: 가능한 한 많은 거래 세부 정보를 속성에 포함시켜 세분화된 구매 분석을 가능하게 하고 제품 성과에 따라 마케팅 비용을 최적화하세요.

구매 추적 모범 사례

권장 속성

포괄적인 거래 추적을 위해 다음과 같은 공통 속성을 구매 이벤트에 포함하세요:

  • product_id: 구매한 품목 또는 SKU의 고유 식별자
  • product_name: 사람이 읽을 수 있는 제품 이름
  • product_category: 제품의 카테고리 또는 유형(예: "통화", "무기", "구독")
  • transaction_id: 결제 플랫폼의 고유 거래 식별자
  • 플랫폼: 구매 플랫폼(예: "앱스토어", "구글플레이", "스팀")
  • 프로모션 코드: 할인에 사용되는 프로모션 코드
  • user_tier: 사용자 구독 또는 멤버십 티어
  • 수량: 구매한 아이템 수

구현 팁:

  • 0이 아닌 금액: 금액이 0보다 크거나 작은 경우에만 구매 이벤트를 전송합니다.
  • 일관된 이름 지정: 모든 구매 이벤트에 일관된 속성 이름을 사용하면 분석이 쉬워집니다.
  • 테스트 구매: 테스트 구매: 프로덕션 구매 데이터가 왜곡되지 않도록 테스트에 소량(예: $0.01)을 사용합니다.

하이브리드 이벤트 추적(고급)

최적의 어트리뷰션을 위해 앱에 연동된 Singular SDK를 통해 모든 이벤트와 구매을 전송하세요. 하지만, 필요한 경우 Singular는 다른 소스에서 이벤트를 수집할 수 있습니다.

Singular SDK 외부에서 전송되는 이벤트는 Singular의 서버 간 이벤트 설명서를준수해야 하며, 정확한 어트리뷰션을 위해 일치하는 디바이스 식별자를 제공해야 합니다.

중요한 어트리뷰션 고려 사항:

서버 간 요청의 디바이스 식별자가 Singular SDK에 기록된 식별자와 일치하지 않는 경우 불일치가 발생합니다:

  • 초기 이벤트: Singular SDK가 디바이스 식별자를 기록하기 전에 이벤트가 도착하면, 이벤트는 알 수 없는 디바이스에 대한 '첫 번째 세션'이 되어 오가닉 어트리뷰션이 발생하게 됩니다.
  • 불일치 식별자: Singular SDK가 서버 간 요청에 있는 식별자와 다른 디바이스 식별자를 기록한 경우, 이벤트가 잘못 어트리뷰션됩니다.

하이브리드 이벤트 추적 옵션

내부 서버에서 이벤트 전송

클라이언트 측 추적이 불충분한 경우 내부 서버에서 구매 데이터를 수집하여 캠페인 성과 및 ROI를 분석합니다.

요구 사항

  • 기기 식별자 캡처: 인앱 등록 또는 로그인 이벤트 중에 디바이스 식별자를 캡처하여 전달한 다음 이 데이터를 서버에 사용자 ID와 함께 저장합니다. 사용자가 새 앱 세션을 생성할 때 식별자를 업데이트하여 정확한 어트리뷰션을 보장합니다.
  • 플랫폼별 식별자: 플랫폼과 일치하는 디바이스 식별자를 사용하여 서버 측 이벤트를 전송합니다(예: iOS 디바이스의 경우 IDFA 또는 IDFV, 안드로이드 디바이스의 경우 GAID).
  • 실시간 업데이트: Singular 내부 BI 포스트백 메커니즘을 사용하여 이벤트를 엔드포인트에 실시간으로 푸시합니다. 내부 BI 포스트백 FAQ를참조하세요.
  • 구현 세부 사항: 서버 간 연동 가이드의 "구매 추적"섹션을 검토하세요 .

구매 제공업체에서 이벤트 보내기

RevenueCat 또는 어댑터와 같은 타사 구매 제공업체를 연동하여 구매 및 구독 구매을 Singular로 전송할 수 있습니다.

지원되는 제공업체

참고: 어트리뷰션 정확도를 유지하기 위해 구매 제공자를 사용할 때, Singular SDK가 캡처하는 것과 일치하는 올바른 기기 식별자를 전송하도록 구성했는지 확인하세요.

세그먼트에서 이벤트 보내기

세그먼트에 "클라우드 모드" 대상을 추가하여 세그먼트가 Singular SDK와 병행하여 이벤트를 Singular로 전송할 수 있도록 설정하세요.

자세한 설정 지침은 Singular-세그먼트 연동구현 가이드를 참조하세요.

구성 참고: 세그먼트 연동을 사용하려면 클라우드 모드 대상 설정을 통해 이벤트가 올바른 디바이스 식별자 및 어트리뷰션 컨텍스트를 사용하여 Singular로 올바르게 라우팅되도록 해야 합니다.