인앱 이벤트 추적

인앱 이벤트를 추적하여 캠페인 성과를 분석하고 사용자 로그인, 회원가입, 튜토리얼 완료, 진행 단계 마일스톤 등 핵심 성과 지표(KPI)를 측정하세요.

표준 이벤트 및 속성

표준 이벤트 사용하기

Singular은 리포팅 및 최적화를 위해 광고 네트워크에서 인식하는 표준 이벤트 를 지원합니다. 자동 인식과 간편한 설정을 위해 가능한 한 표준 이벤트 이름을 사용하세요.

UA, 마케팅 또는 비즈니스 팀이 조직의 마케팅 KPI를 기준으로 이벤트 목록을 작성해야 합니다. 계획 수립에는 인앱 이벤트 추적 방법: Singular 어트리뷰션 고객을 위한 가이드 를 참고하세요.

각 이벤트는 다양한 속성을 지원합니다. 구현 세부 정보는 이벤트별 권장 표준 속성 을 참고하세요.

이벤트 전송

이벤트 구현 가이드라인

사용자 액션 및 행동을 추적하려면 event 또는 eventWithArgs 메서드를 사용하여 Singular로 이벤트를 전송하세요.

표준 이벤트: 표준 이벤트 목록에서 이벤트의 iOS 이름 을 사용하세요. 예: EVENT_SNG_LOGIN
커스텀 이벤트: 표준 이벤트와 일치하지 않는 앱 고유 이벤트의 경우, 문자 제한을 준수하는 임의의 설명적인 문자열을 사용하세요

커스텀 이벤트 제한사항:

언어: 서드파티 파트너 및 분석 솔루션과의 호환성을 보장하기 위해 이벤트 이름과 속성은 영어로 전달하세요
이벤트 이름: 최대 32자의 ASCII 문자로 제한됩니다. 비 ASCII 문자열은 UTF-8로 변환 시 32바이트 미만이어야 합니다
속성 및 값: 최대 500자의 ASCII 문자로 제한됩니다

event 메서드

간단한 추적 시나리오를 위해 추가 정보 없이 사용자 이벤트를 보고합니다.

메서드 시그니처:

+ (void)event:(NSString *)name;

+event: 는 void 를 반환합니다. 호출 시점에서 성공/실패 신호가 없습니다. 이름이 nil 이거나 비어 있을 때, 또는 +start: 가 아직 호출되지 않았을 때 SDK는 이벤트를 조용히 삭제합니다. 문제를 확인하려면 로그를 검토하세요.

사용 예시

// Example 1: Standard event
Singular.event(EVENT_SNG_LOGIN)

// Example 2: Custom event
Singular.event("signup")

// Example 1: Standard event
[Singular event:EVENT_SNG_LOGIN];

// Example 2: Custom event
[Singular event:@"signup"];

eventWithArgs 메서드

구조화된 데이터를 위해 딕셔너리 형식을 사용하여 추가 정보와 함께 사용자 이벤트를 보고합니다.

메서드 시그니처:

+ (void)event:(NSString *)name withArgs:(NSDictionary *)args;

참고: args 파라미터는 하나 이상의 키-값 쌍을 포함하는 NSDictionary입니다. 키는 문자열이어야 하며 값은 NSDictionary에서 허용되는 모든 타입이 될 수 있습니다.

사용 예시

// Example 1: Standard event with recommended attributes
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_CONTENT_TYPE] = "video"
dic[ATTRIBUTE_SNG_ATTR_CONTENT_ID] = "32"
dic[ATTRIBUTE_SNG_ATTR_CONTENT] = "Telugu"
dic[ATTRIBUTE_SNG_ATTR_SUCCESS] = "yes"

Singular.event(EVENT_SNG_TUTORIAL_COMPLETE, withArgs: dic)

// Example 2: Custom event with custom attributes
var bonusData: [AnyHashable: Any] = [
    "level": 10,
    "points": 500
]
Singular.event("Bonus Points Earned", withArgs: bonusData)

// Example 1: Standard event with recommended attributes
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"video" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_TYPE];
[dic setValue:@"32" forKey:ATTRIBUTE_SNG_ATTR_CONTENT_ID];
[dic setValue:@"Telugu" forKey:ATTRIBUTE_SNG_ATTR_CONTENT];
[dic setValue:@"yes" forKey:ATTRIBUTE_SNG_ATTR_SUCCESS];

[Singular event:EVENT_SNG_TUTORIAL_COMPLETE withArgs:dic];

// Example 2: Custom event with custom attributes
NSMutableDictionary *bonusData = [[NSMutableDictionary alloc] init];
[bonusData setValue:@10 forKey:@"level"];
[bonusData setValue:@500 forKey:@"points"];

[Singular event:@"Bonus Points Earned" withArgs:bonusData];

인앱 수익 추적

인앱 구매(IAP), 구독, 커스텀 수익 소스에서 발생하는 수익을 추적하여 캠페인 성과와 광고 비용 대비 수익률(ROAS)을 측정하세요.

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

인터랙티브 리포트: Singular 대시보드에서 수익 지표를 확인합니다
익스포트 로그: 커스텀 분석을 위한 상세 ETL 데이터에 액세스합니다
실시간 포스트백: 외부 플랫폼으로 수익 이벤트를 전송합니다

수익 이벤트 제한사항:

이벤트 이름: 커스텀 수익 이벤트 이름은 최대 32자의 ASCII 문자로 제한됩니다(비 ASCII의 경우 UTF-8로 변환 시 32바이트)
속성: 이벤트 속성 이름과 값은 최대 500자의 ASCII 문자로 제한됩니다
통화 코드: 모두 대문자여야 하며 세 글자 ISO 4217 표준 을 따라야 합니다(예: USD, EUR, INR)

모범 사례

표준 명명: Singular의 표준 이벤트 및 속성 명명 규칙 을 사용하세요
언어: 광고 네트워크 포스트백 호환성 향상을 위해 커스텀 수익 이벤트 이름은 영어로 전송하세요
0이 아닌 금액: 금액이 0보다 크거나 작을 때만 수익 이벤트를 전송하세요

비구독 인앱 구매

SKPaymentTransaction 연동

StoreKit의 SKPaymentTransaction 객체를 iapComplete 메서드에 전달하여 강화된 리포팅과 거래 검증을 활용하세요.

이점:

풍부한 데이터: Singular은 포괄적인 리포트를 위한 완전한 거래 세부 정보를 수신합니다
사기 방지: 거래 영수증을 통해 검증이 가능하여 인앱 사기에 대응합니다

참고:

필수 객체: iapComplete 메서드는 SKPaymentTransaction 객체를 필요로 합니다
통화 변환: 서로 다른 통화의 수익은 조직의 기본 통화로 자동 변환됩니다
커스텀 이벤트 이름: 리포트에서 수익을 이벤트 유형별로 분류하려면 withName 파라미터를 사용하세요

iapComplete 메서드

자동 검증과 강화된 데이터를 위해 SKPaymentTransaction 객체와 함께 수익 이벤트를 전송합니다.

메서드 시그니처:

+ (void)iapComplete:(id)transaction;
+ (void)iapComplete:(id)transaction withName:(NSString *)name;

사용 예시

// Get the SKPaymentTransaction object
let transaction: SKPaymentTransaction = ...

// Send transaction without custom event name
Singular.iapComplete(transaction)

// Send transaction with custom event name
Singular.iapComplete(transaction, withName: "MyCustomRevenue")

// Get the SKPaymentTransaction object
SKPaymentTransaction *transaction = ...;

// Send transaction without custom event name
[Singular iapComplete:transaction];

// Send transaction with custom event name
[Singular iapComplete:transaction withName:@"MyCustomRevenue"];

구독 수익

구독 이벤트 구현

구독 구매 및 갱신을 추적하여 사용자 행동과 반복 수익 발생에 대한 인사이트를 확보하세요.

구현 가이드: Singular SDK로 구독을 추적하는 상세 지침은 종합 구독 이벤트 기술 구현 가이드 를 참고하세요.

구매 검증 없는 커스텀 수익

수동 수익 추적

SKPaymentTransaction 객체 없이 통화, 금액, 선택적 제품 세부 정보를 전달하여 수익을 추적합니다. 이 방법은 검증을 위한 거래 영수증을 제공하지 않는다는 점에 유의하세요.

중요: 이러한 메서드를 사용할 경우 Singular은 거래를 검증할 수 없습니다. 가능한 한 위에서 설명한 SKPaymentTransaction 메서드를 사용할 것을 강력히 권장합니다.

revenue 메서드

통화, 금액, 선택적 제품 세부 정보와 함께 수익 이벤트를 전송합니다.

메서드 시그니처:

+ (void)revenue:(NSString *)currency amount:(double)amount;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
     productSKU:(NSString *)productSKU
    productName:(NSString *)productName
productCategory:(NSString *)productCategory
productQuantity:(int)productQuantity
   productPrice:(double)productPrice;

+ (void)revenue:(NSString *)currency
         amount:(double)amount
 withAttributes:(NSDictionary *)attributes;

사용 예시

// Without product details
Singular.revenue("USD", amount: 1.99)

// With product details
Singular.revenue("EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.revenue("USD", amount: 19.95, withAttributes: dic)

// Without product details
[Singular revenue:@"USD" amount:1.99];

// With product details
[Singular revenue:@"EUR"
           amount:5.00
       productSKU:@"SKU1928375"
      productName:@"Reservation Fee"
  productCategory:@"Fee"
  productQuantity:1
     productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular revenue:@"USD" amount:19.99 withAttributes:dic];

customRevenue 메서드

지정된 이벤트 이름, 통화, 금액, 선택적 거래 속성과 함께 커스텀 수익 이벤트를 전송합니다.

메서드 시그니처:

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
           productSKU:(NSString *)productSKU
          productName:(NSString *)productName
      productCategory:(NSString *)productCategory
      productQuantity:(int)productQuantity
         productPrice:(double)productPrice;

+ (void)customRevenue:(NSString *)eventName
             currency:(NSString *)currency
               amount:(double)amount
       withAttributes:(NSDictionary *)attributes;

사용 예시

// Without product details
Singular.customRevenue("MyCustomRevenue", currency: "USD", amount: 1.99)

// With product details
Singular.customRevenue("MyCustomRevenue",
    currency: "EUR",
    amount: 5.00,
    productSKU: "SKU1928375",
    productName: "Reservation Fee",
    productCategory: "Fee",
    productQuantity: 1,
    productPrice: 5.00)

// With product details in a dictionary
var dic: [AnyHashable: Any] = [:]
dic[ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION] = "100% Organic Cotton Mixed Plaid Flannel Shirt"
dic[ATTRIBUTE_SNG_ATTR_ITEM_PRICE] = "$69.95"
dic[ATTRIBUTE_SNG_ATTR_RATING] = "5 Star"
dic[ATTRIBUTE_SNG_ATTR_SEARCH_STRING] = "Flannel Shirt"

Singular.customRevenue("CustomRevenueWithArgsDic",
    currency: "USD",
    amount: 44.99,
    withAttributes: dic)

// Without product details
[Singular customRevenue:@"MyCustomRevenue" currency:@"USD" amount:1.99];

// With product details
[Singular customRevenue:@"MyCustomRevenue"
               currency:@"EUR"
                 amount:5.00
             productSKU:@"SKU1928375"
            productName:@"Reservation Fee"
        productCategory:@"Fee"
        productQuantity:1
           productPrice:5.00];

// With product details in a dictionary
NSMutableDictionary *dic = [[NSMutableDictionary alloc] init];
[dic setValue:@"100% Organic Cotton Mixed Plaid Flannel Shirt"
       forKey:ATTRIBUTE_SNG_ATTR_ITEM_DESCRIPTION];
[dic setValue:@"$69.95" forKey:ATTRIBUTE_SNG_ATTR_ITEM_PRICE];
[dic setValue:@"5 Star" forKey:ATTRIBUTE_SNG_ATTR_RATING];
[dic setValue:@"Flannel Shirt" forKey:ATTRIBUTE_SNG_ATTR_SEARCH_STRING];

[Singular customRevenue:@"MyCustomRevenue"
               currency:@"USD"
                 amount:44.99
         withAttributes:dic];

StoreKit2 지원

StoreKit2 수익 추적

StoreKit2 프레임워크를 사용하는 앱의 경우, 거래 및 제품 JSON 표현과 함께 customRevenue 메서드를 사용하세요.

이제 SDK 버전 12.13 이상에서 StoreKit2 검증이 지원됩니다. 이 메서드들은 거래 및 제품 객체에 대해 jsonRepresentation 형식을 필요로 합니다.

메서드 시그니처:

+ (void)customRevenue:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

+ (void)customRevenue:(NSString *)eventName
transactionJsonRepresentation:(NSData *)transactionJsonRepresentation
productJsonRepresentation:(NSData *)productJsonRepresentation;

사용 예시

// Fetch transaction and product from StoreKit2
let transaction = ... // Valid StoreKit2 transaction
let product = ... // Valid StoreKit2 product

// Custom Revenue with default __iap__ event name
Singular.customRevenue(
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Custom Revenue with custom event name
Singular.customRevenue(
    "PaymentSuccess",
    transactionJsonRepresentation: transaction.jsonRepresentation,
    productJsonRepresentation: product.jsonRepresentation)

// Fetch transaction and product from StoreKit2
SKTransaction *transaction = ...;  // Valid StoreKit2 transaction
SKProduct *product = ...;          // Valid StoreKit2 product

// Convert JSON representations to NSData
NSData *transactionData = [transaction.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];
NSData *productData = [product.jsonRepresentation
    dataUsingEncoding:NSUTF8StringEncoding];

// Custom Revenue with default __iap__ event name
[Singular customRevenue:transactionData
    productJsonRepresentation:productData];

// Custom Revenue with custom event name
[Singular customRevenue:@"PaymentSuccess"
    transactionJsonRepresentation:transactionData
    productJsonRepresentation:productData];

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

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

Singular SDK 외부에서 전송되는 이벤트는 Singular의 Server-to-Server 이벤트 문서 를 준수해야 하며 올바른 어트리뷰션을 위해 일치하는 디바이스 식별자를 제공해야 합니다.

중요:

server-to-server 요청의 디바이스 식별자가 Singular SDK가 기록한 식별자와 일치하지 않으면 불일치가 발생합니다:

조기 이벤트: Singular SDK가 디바이스 식별자를 기록하기 전에 이벤트가 도착하면, 해당 이벤트가 알 수 없는 디바이스의 "첫 세션"이 되어 오가닉 어트리뷰션으로 처리됩니다
불일치 식별자: Singular SDK가 server-to-server 요청의 식별자와 다른 디바이스 식별자를 기록한 경우, 이벤트가 잘못 어트리뷰션됩니다

하이브리드 이벤트 추적 가이드

내부 서버에서 이벤트 전송

캠페인 성과와 ROI를 분석하기 위해 내부 서버에서 수익 데이터를 수집하세요.

요구사항:

디바이스 식별자 캡처: 인앱 회원가입 또는 로그인 이벤트 시 디바이스 식별자를 캡처하고 전달한 다음, 이 데이터를 User ID와 함께 서버에 저장하세요. 올바른 어트리뷰션을 보장하기 위해 사용자가 새 앱 세션을 생성할 때 식별자를 업데이트하세요
플랫폼별 식별자: 플랫폼에 맞는 디바이스 식별자와 함께 서버 측 이벤트를 전송하세요(예: iOS 디바이스의 경우 IDFA 또는 IDFV)
실시간 업데이트: Singular Internal BI 포스트백 메커니즘을 사용하여 이벤트를 실시간으로 엔드포인트에 푸시하세요. Internal BI Postback FAQ 를 참고하세요
구현 세부 정보: Server-to-Server 연동 가이드의 "Tracking Revenue" 섹션을 검토하세요

수익 제공업체에서 이벤트 전송

RevenueCat 또는 adapty 같은 서드파티 수익 제공업체를 연동하여 구매 및 구독 수익을 Singular로 전송하세요.

지원되는 제공업체:

RevenueCat: RevenueCat 문서 에서 자세히 알아보세요
adapty: adapty 문서 에서 자세히 알아보세요

Segment에서 이벤트 전송

Segment에 "Cloud-Mode" 데스티네이션을 추가하여 Singular SDK와 병행하여 Segment가 Singular로 이벤트를 전송하도록 활성화하세요.

상세 설정 지침은 구현 가이드 Singular-Segment 연동 을 따르세요.