Questions about params in the Conversion API (Track ID 8453444440824824339)

Hello Kakao Pixel & SDK team,

We are integrating the Conversion API, following the Integration Guide v2.0. We have some questions about the event parameters (params) described in §2.5.5. Our observations come from test requests sent with debug: “Y” to our own test pixel (Track ID 8453444440824824339).

We asked the following questions on Kakao Customer Center, and they guided me to ask for help here

  1. Is params required?
    The guide does not say whether params is required for any event. In our tests, a Purchase event with no params at all returned 200 OK. Is params optional for every event code, including Purchase? Are any parameters required for an event to be counted as a conversion, or to be used for reporting or optimization?

  2. Must params follow the table in §2.5.5?
    The table defines which parameters can be used with each event. However, Kakao also accepted parameters outside the table:

  • A PageView event with search_string returned 200 OK, although search_string is listed for Search only.
  • Unknown keys, both inside params (for example “coupon”: “SPRING”) and at the event level, also returned 200 OK.

Could you confirm:

  • Are parameters outside the table ignored, stored, or used in any way?
  • Should we strictly follow the table, and drop any parameter that does not apply to the event code before sending?
  1. Why is currency added by default?
    We see currency on events even when we did not send it. Is a default currency applied when currency is omitted? If so, what is the default value, and does it apply to every event code, including those for which the table does not list currency?

  2. Is there a recommended limit on events per request or on products per event?
    The guide limits data to 1,000 events (§2.5.3) and states a 10-second timeout (§1.2). It does not mention any limit on the number of products per event, string lengths, or the total request size. In our tests:

┌────────────────────────────────┬───────────┬───────────────────────────────────────────────────────┐
│ Request │ Body size │ Result │
├────────────────────────────────┼───────────┼───────────────────────────────────────────────────────┤
│ 800 events × 10 products each │ ~1 MB │ 200 OK in 3.9 s │
├────────────────────────────────┼───────────┼───────────────────────────────────────────────────────┤
│ 800 events × 100 products each │ ~7.6 MB │ 200 OK in 24 s │
├────────────────────────────────┼───────────┼───────────────────────────────────────────────────────┤
│ 999 events × 100 products each │ ~9.4 MB │ the connection timed out after 37 s, with no response │
└────────────────────────────────┴───────────┴───────────────────────────────────────────────────────┘

Could you advise:

  • Is there a maximum request body size, or a maximum number of products per event?
  • What batch size and request size do you recommend so that a request completes within the 10-second timeout?
  • When a large request times out like this, may some of its events already have been collected? §1.2 notes that a timed-out request may be partially processed, which matters to us because a resend would count those events twice.

Thank you for your help.

카카오비즈니스 파트너센터 문의하기 | kakao 고객센터

Hello,

For the Pixel SDK, support is provided through the path shown in the image attached above.
Could you please confirm whether you contacted us through that path?

Thank you!

Thank you for the rapid response!

Yes, I used the same page as you provided to ask the questions related to Kakao Ads Convention API

@kakao_moment cc. @KAKAO_MOMENT_PIXEL

안녕하세요.
Convention API 관련하여 고객센터로 문의 하였으나 데브톡으로 다시 인입된 건인데요
관련하여 답변 가능 하실지 확인 부탁드립니다.

1개의 좋아요

Thanks for the help!

Will I get the related response from this thread? Do I need to submit my questions in another form?

안녕하세요 @kakaomoment_openapi , @kakao_moment , @Kakao_Pixel_SDK , @woody.ho ,

위에 처음 게재/문의드린 이슈 건에 대해서 답변해주실 수 있으신가요?

말씀해주신것처럼 Pixel SDK 문의 접수로도 남겼으나 제대로 답변을 받지 못한 상태입니다.

여기서 답변이 어려우면 어느 경로로 문의해야되는지 알려주시면 감사하겠습니다.

@Kakao_Pixel_SDK 답변 부탁드릴게요.

안녕하세요.

카카오 픽셀&SDK 담당자입니다.

문의주신 내용에 대해 순서대로 답변 전달드립니다.

1. params는 필수인가요?

params는 구매 상품 정보 등 이벤트에 관한 부가 정보를 전송하는 필드이며, 필수 항목은 아닙니다. params를 전송하지 않아도 이벤트는 정상적으로 접수될 수 있습니다(HTTP 200 응답).

다만 모먼트 전환 보고서 내 구매 이벤트의 총구매금액 및 ROAS 지표를 산출하려면 총구매금액(total_price) 전송이 필요합니다. 상품 정보 등 추가 파라미터를 함께 전송하시면 광고 전환 최적화 학습에 도움이 될 수 있으므로, 관련 정보를 보유하고 계신 경우 전송을 권장드립니다.

2. 이벤트별 파라미터 표에 없는 값을 전송해도 되나요?

요청 스키마에 정의되지 않은 키를 전송해도 이벤트 요청은 정상적으로 접수될 수 있습니다(HTTP 200 응답). 다만 정의되지 않은 키와 값은 저장되거나 활용되지 않습니다.

불필요한 데이터 전송을 방지할 수 있도록 가이드 §2.5.5의 이벤트별 파라미터 표를 참고해 해당 이벤트 코드에 맞는 파라미터만 전송해 주시기 바랍니다.

3. currency를 생략하면 어떤 값이 적용되나요?

모먼트 보고서의 구매 관련 지표인 총구매금액과 ROAS를 산출할 때 통화 기준이 필요하므로, currency를 전송하지 않으면 기본값인 KRW가 적용됩니다.

구매 금액이 원화가 아닌 경우 해당 통화 코드를 전송해 주세요. (ex. USD)

전송된 금액은 해당 통화의 환율을 기준으로 원화로 환산되어 지표 산출에 활용되며, 보고서 지표는 원화 기준으로 제공됩니다. 지원 가능한 통화 코드는 카카오 비즈니스 가이드에서 확인하실 수 있습니다.

구매 이벤트에 total_price 정보가 포함되지 않으면 (통화코드 전송 여부 관계없이) 구매 전환 건수 지표만 산출되며, 총구매금액과 ROAS 지표는 산출되지 않아 보고서에 0으로 표시됩니다.

4. 요청당 이벤트 수, 상품 수 및 요청 크기 권장 기준은 어떻게 되나요?

이벤트당 전송할 수 있는 상품 정보 개수에는 별도 제한이 없습니다. 다만, 안정적인 수집을 위해 요청 본문은 1MB 이하로 전송해 주시기 바랍니다. 타임아웃 방지를 위해 요청당 이벤트는 100건 이하, 요청 본문은 1MB 이하로 전송하는 것을 권장드립니다.

대량 배치 전송의 경우 타임아웃이 발생하면 클라이언트에서 이벤트별 처리 결과를 확인하기 어려울 수 있습니다. 따라서 이벤트 발생 즉시 실시간으로 전송하는 방식을 강력히 권장드립니다.

불가피하게 배치 전송이 필요한 경우에는 요청당 100건 이하, 1MB 이하로 나누어 전송해 주시기 바랍니다.

타임아웃이 발생하더라도 이벤트 수집 처리는 진행될 수 있습니다. 따라서 처리 여부를 확인하지 못한 요청을 다시 전송하면 이벤트가 중복 집계될 가능성이 있습니다.

감사합니다.

Hello,

This is the Kakao Pixel & SDK team.

Please find our responses to your questions below.

1. Is params required?

params is an optional field for sending additional information about an event, such as product details. An event can be accepted without params (HTTP 200 response).

However, total_price is required to calculate the purchase amount and ROAS metrics for Purchase events in Moment conversion reports. Sending additional parameters, such as product information, may also help optimize ad conversions. We recommend sending them when the information is available.

2. Are parameters not listed in the event-specific table accepted or used?

An event request may be accepted even if it contains keys that are not defined in the request schema (HTTP 200 response). However, undefined keys and values are not stored or used.

To avoid sending unnecessary data, please refer to the event-specific parameter table in §2.5.5 and send only parameters that apply to the relevant event code.

3. What happens if currency is omitted?

A currency is needed to calculate purchase-related metrics in Moment reports, including purchase amount and ROAS. If currency is omitted, the default value KRW is applied.

If the purchase amount is in a currency other than KRW, please send the corresponding currency code. The amount will be converted to KRW using the applicable exchange rate for metric calculation, and all report metrics are provided in KRW. Please refer to the Kakao Business Guide for the list of supported currency codes. [Insert guide link]

If total_price is not included in a Purchase event, only the purchase count metric is calculated. The purchase amount and ROAS metrics are not calculated and are shown as 0 in the report.

4. Are there recommended limits on events, products, or request size?

There is no separate limit on the number of product items that can be sent per event. However, for stable collection, please keep the request body within 1 MB. To help prevent timeouts, we recommend sending no more than 100 events per request and keeping the request body within 1 MB.

With large batch requests, a timeout may prevent the client from confirming the processing result for each event. We therefore recommend sending events in real time as they occur. If batch transmission is unavoidable, please split the data into requests of no more than 100 events and 1 MB each.

Event collection may still proceed even if a request times out. Therefore, resending a request when its processing status cannot be confirmed may result in duplicate event counts.

Regards,
Kakao Pixel & SDK Team

추가적으로 카카오 Conversion API 연동 관련한 기술 문의는 아래 메일 주소로 문의주시면 바로 답변드리도록 하겠습니다.

For any further technical questions regarding Kakao Conversion API integration, please contact us at the email address below. We will get back to you as soon as possible.

pixel_sdk@kakaocorp.com

감사합니다.

Thank you for your support and feedback. Let me contact you with pixel_sdk@kakaocorp.com.