전환 이벤트 전송

네이버 앱 전환 추적 SDK에서는 다양한 전환 이벤트를 수집합니다. 이 중 '앱 설치'와 '앱 실행' 이벤트는 SDK에서 자동으로 수집합니다. 그 외에는 해당 이벤트가 발생하면 수동으로 구현합니다.

각 이벤트 이름은 NTrackerConversionEvent struct/object에 정의되어 있습니다.

이벤트 목록은 다음과 같습니다.

이벤트 설명	수집 방식	이벤트 이름	API
앱 설치	자동	-	앱을 처음 실행하면 자동 전송
앱 실행	자동	-	앱을 실행하고 SDK가 초기화되면 자동 전송
구매 완료	수동	-	`trackPurchaseEvent`
앱 내 구매 완료	수동	-	`trackInAppPurchaseEvent`
장바구니 담기	수동	Cart	`trackConversionEvent`
위시리스트 추가	수동	WishList
신청 완료	수동	Application
소식 받기/구독	수동	Subscribe
예약 완료	수동	Reservation
콘텐츠 보기	수동	ViewContent
레벨 달성	수동	LevelEnd
튜토리얼 완료	수동	Tutorial
회원 가입 완료	수동	SignUp
사용자 정의(#1~#10)	수동	CustomEvent[001~010]

광고 전환을 위한 이벤트 전송 시 주의 사항

성과형 디스플레이 광고(DA)에서 광고 전환을 제공하려면 다음 사항에 주의해야 합니다.

이벤트 이름

trackConversionEvent API로 이벤트를 전송할 때 이벤트 이름(event name)을 반드시 입력해야 합니다.

전환 가치

전환 가치(value)는 총 전환 매출액을 의미하며, 통화 단위는 KRW입니다. 자동으로 수집되는 이벤트를 제외한 모든 이벤트에서 전환 가치를 전송할 수 있습니다.

• '구매 완료', '앱 내 구매 완료' 이벤트 전송 시 전환 가치를 포함하려면 반드시 실제 결제한 금액의 총액을 입력해야 합니다. 그 외 전환 이벤트의 전환 가치 필드는 선택 사항으로, 전환 이벤트별로 측정할 전환 가치를 설정합니다.
• '구매 완료', '앱 내 구매 완료' 이벤트 전송 시 NTrackerConversionItem으로 상품 세부 정보를 함께 전송할 경우 전환 가치(value)와 구매 항목(items)의 payAmount 합계가 일치해야 합니다.
• '구매 완료', '앱 내 구매 완료' 외 일반 이벤트를 전송할 때 전환 가치를 포함하려면, 전환 가치(value) 필드값의 통화 기준이 KRW여야 합니다.
• 단기간에 너무 많은 전환이 보고되면 어뷰징으로 감지되어 성과형 DA에서 전환 보고가 제한될 수 있습니다. 어뷰징 판단 기준은 내부 로직에 따라 변경될 수 있습니다.

이벤트 종류에 따른 상품 세부 정보 전송

NTrackerConversionItem에는 이벤트에 포함된 세부 항목의 일반 정보를 담을 수 있습니다. '구매 완료', '앱 내 구매 완료' 이벤트의 경우 NTrackerConversionItem을 이용해 구매 항목 정보(상품 세부 정보)를 전달하는 것을 권장합니다. 사용 방법은 이벤트 전송 코드 예를 참고하세요.

특히, '구매 완료', '앱 내 구매 완료' 이벤트에서 USD 통화로 결제할 가능성이 있으면, 전환 가치(value) 필드는 입력하지 않고 NTrackerConversionItem으로 items 하위에 결제 금액과 통화를 지정해서 전송해야 합니다. 단, 전환 가치(value)와 items 하위 payAmount가 모두 전달되면, 전환 가치(value)만 전환 매출액에 포함됩니다.

'장바구니 담기', '위시리스트 추가', '콘텐츠 보기' 등의 이벤트 전송 시 NTrackerConversionItem으로 상품 세부 정보를 전달할 수 있으나, 현재는 성과형 DA 리포트 및 최적화에 사용되지 않습니다. 향후 전환 최적화 및 성과형 DA 내 대시보드 기능을 이용해 items 하위 정보를 사용할 수 있게 지원할 예정입니다.

NTrackerConversionItem으로 구매 항목 정보를 전달할 때 quantity, payAmount는 필수 필드이고, 그 외는 선택 필드입니다.

• quantity는 해당 상품(또는 서비스)의 전환 수량을 의미합니다.
• payAmount는 해당 상품이 발생시킨 총 전환 가치를 의미합니다. 예를 들어, 가격이 1,000원인 item A가 3개 구매되었을 때, 해당 item의 payAmount는 3,000원입니다.
• payAmount가 KRW가 아니면 ext1에 currency code(ISO 4217)를 입력합니다. currency code를 설정하지 않으면 'KRW'로 계산합니다.
• quantity, payAmount 외 선택 필드는 정해진 형식 없이 각 서비스에서 임의로 지정하여 사용할 수 있습니다.

주의

• 해외 결제가 허용되는 경우, currency code를 반드시 지정해야 합니다.
• 현재 KRW, USD만 지원되며, 다른 currency code(예: EUR)가 입력되면 전환 가치를 0으로 처리합니다.

이벤트 전송 코드 예

다음은 다양한 이벤트를 전송하는 코드 예입니다.

• 구매 완료 이벤트 전송
• 앱 내 구매 완료 이벤트 전송
• 일반 이벤트 전송 - items를 포함하지 않는 경우
• 일반 이벤트 전송 - items를 포함하는 경우
• 사용자 정의 이벤트 전송

'구매 완료' 이벤트 전송

'구매 완료'나 '앱 내 구매 완료' 이벤트는 각각 trackPurchaseEvent, trackInAppPurchaseEvent API로 전환 가치(value)와 구매 항목(items)을 전송합니다.

• 전환 가치(value)는 구매 항목(items)의 payAmount의 합계와 일치해야 합니다.
• USD 결제 가능성을 고려해 전환 가치 없이 구매 항목만 전송하는 경우, 항목의 currency code(ext1)와 pay amount(payAmount)로 플랫폼 내부에서 전환 가치(전환 매출액)를 계산해서 제공합니다.

이 절의 이벤트 전송 코드 예에서는 다음과 같이 구매가 발생했다고 가정합니다.

	상품 단가	구매 수량	총 구매 비용
item1	100	1	100
item2	200	2	400
item3	300	3	900

iOS

// 환율 정보는 'ext1'에 입력합니다. 'KRW'인 경우 생략할 수 있습니다.
let items = [
    NTrackerConversionItem(quantity: 1, payAmount: 100, id: "item1", ext1: "KRW"),
    NTrackerConversionItem(quantity: 2, payAmount: 400, id: "item2", ext1: "KRW"),
    NTrackerConversionItem(quantity: 3, payAmount: 900, id: "item3", ext1: "KRW")
]

// 전환 가치와 구매 항목을 전송하는 경우
NTrackerExt.trackPurchaseEvent(value: 1_400, items: items)

// 전환 가치를 전송하지 않는 경우: 전환 가치는 모든 items의 payAmount 합계인 1,400원으로 계산합니다.
NTrackerExt.trackPurchaseEvent(items: items)

// 전환 가치만 전송하는 경우
NTrackerExt.trackPurchaseEvent(value: 1_400)

Android

// 환율 정보는 'ext1'에 입력합니다. 'KRW'인 경우 생략할 수 있습니다.
val items = arrayOf(
    NTrackerConversionItem(1, 100.0, "item1", null, null, "KRW"),
    NTrackerConversionItem(2, 400.0, "item2", null, null, "KRW"),
    NTrackerConversionItem(3, 900.0, "item3", null, null, "KRW")
)

// 전환 가치와 구매 항목을 전송하는 경우
NTrackerExt.trackPurchaseEvent(1_400, items)

// 전환 가치를 전송하지 않는 경우: 전환 가치는 모든 items의 payAmount 합계인 1,400원으로 계산합니다.
NTrackerExt.trackPurchaseEvent(items)

// 전환 가치만 전송하는 경우
NTrackerExt.trackPurchaseEvent(1_400)

'앱 내 구매 완료' 이벤트 전송

'앱 내 구매 완료' 이벤트의 전송 방식 및 정보는 '구매 완료' 이벤트와 유사합니다.

OS에서 제공하는 상품과 구매 데이터를 이용하는 경우 전송 방법은 다음과 같습니다. 다음의 코드 예에서 NTrackerConversionItem에 넣는 항목을 참고해 각 서비스의 상황에 맞게 활용하세요.

iOS

이 코드 예에서는 SKProduct와 SKPaymentTransaction의 정보로 '앱 내 구매 완료' 이벤트를 전송합니다.

func sendIAP(product: SKProduct, transaction: SKPaymentTransaction) {
    let quantity = transaction.payment.quantity
    let payAmount = product.price.doubleValue
    let itemId = product.productIdentifier
    let itemName = product.localizedTitle
    let currency = product.priceLocale.currencyCode

    let ntrackerItem = NTrackerConversionItem(quantity: quantity, payAmount: payAmount, id: itemId, name: itemName, ext1: currency)
    
    NTrackerExt.trackInAppPurchaseEvent(items: [ntrackerItem])
}

Android

이 코드 예에서는 ProductDetails와 Purchase의 정보로 '앱 내 구매 완료' 이벤트를 전송합니다. 상품 및 구매 정보를 제공하는 클래스는 BillingClient에 따라 일부 다를 수 있습니다. 이 문서에서는 BillingClient 5를 기준으로 설명합니다.

fun sendIAB(purchase: Purchase, product: ProductDetails) {
    val quantity = purchase.quantity
    val itemId = product.productId
    val itemName = product.name
    val payAmount = product.oneTimePurchaseOfferDetails.priceAmountMicros / 1_000_000
    val currency = product.oneTimePurchaseOfferDetails.priceCurrencyCode

    val ntrackerItem = NTrackerConversionItem(quantity, payAmount.toDouble(), itemId, itemName, null, null, currency)
    NTrackerExt.trackInAppPurchaseEvent(arrayOf(ntrackerItem))
}

일반 이벤트 전송 - items를 포함하지 않는 경우

'구매 완료', '앱 내 구매 완료' 이벤트 외 일반 이벤트를 전송할 때 items를 포함하지 않는 경우, 다음과 같이 event name과 value를 전송합니다.

iOS

// '소식 받기/구독' 전환 이벤트의 전환 가치를 1,000원으로 전송하는 경우
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.Subscribe, value: 1_000)

Android

// '소식 받기/구독' 전환 이벤트의 전환 가치를 1,000원으로 전송하는 경우
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.Subscribe, 1_000)

일반 이벤트 전송 - items를 포함하는 경우

일반 이벤트도 items를 포함해서 전송할 수 있습니다. 예를 들어, '장바구니 담기' 이벤트는 장바구니에 담은 항목의 정보를 전송할 수 있습니다. 단, value 없이 items 하위 payAmount만 전송할 경우, 성과형 DA에서 전환 가치는 0으로 보고됩니다. items 하위의 payAmount 합산 정보는 '구매 완료', '앱 내 구매 완료' 이벤트에만 사용됩니다.

iOS

let items = [
    NTrackerConversionItem(quantity: 1, payAmount: 100, id: "item1", ext1: "KRW"),
    NTrackerConversionItem(quantity: 2, payAmount: 400, id: "item2", ext1: "KRW")
]

// 장바구니에 담은 items를 함께 전송
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.Cart, value: 900, items: items)

Android

val items = arrayOf(
    NTrackerConversionItem(1, 100.0, "item1", null, null, "KRW"),
    NTrackerConversionItem(2, 400.0, "item2", null, null, "KRW")
)

// 장바구니에 담은 items를 함께 전송
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.Cart, 900, items)

사용자 정의 이벤트 전송

전환 이벤트가 사전에 정의된 항목에 없으면 'custom' 이벤트를 사용합니다. 'custom' 이벤트는 1~10까지 사용할 수 있고, 각 서비스에서 임의로 사용할 수 있습니다. 일반 이벤트와 동일하게, event name과 value를 전송합니다.

iOS

// 'Custom' 전환 이벤트의 전환 가치를 1,000원으로 전송하는 경우
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.CustomEvent001, value: 1_000)

Android

// 'Custom' 전환 이벤트의 전환 가치를 1,000원으로 전송하는 경우
NTrackerExt.trackConversionEvent(NTrackerConversionEvent.CustomEvent001, 1_000)