Naver Ads

Naver Search Ads has a public advertiser account, a public management API, and a browser conversion script. It does not publish a server-to-server conversion upload API. Use this adapter as pixel-only in ad-conversion-hub, not as a real-capi adapter.

Account and access

Naver uses a self-serve advertiser flow. A new Search Ads member uses a real-name Naver ID to create an individual or business account in the Naver integrated advertiser center. The center requires a verified member who is at least 19.

Create a site Biz Channel and wait for PC or mobile review to reach exposure available. Then apply for tracking:

1. Open Search Ads > Tools > Conversion Tracking Management.
2. Select + Apply for conversion tracking.
3. Choose self-install or NHN DATA installation.
4. Use the installation email to get the site's Naver common key.

The official process says the site must pass review, the site must allow JavaScript, and self-installed tracking needs a separate review request. The common key is normally available in the installation email or in Tools > Conversion Tracking. See the Search Ads application and installation guide.

Smart Store and Brand Store usually need no separate application. A different advertiser and store owner can require manual application. GFA tracking needs separate setup. See the GFA tracking management guide.

Search Ads API access

The Search Ads API manages ads and reports. It is not a conversion ingestion API. Apply in Tools > API Usage Management; Naver then issues an access license and secret key. It covers some products, including site-search ads. Apply through the Naver Ads console; see the Search Ads API documentation.

Use these adapter names. Naver does not define environment-variable names.

NAVER_ADS_TAG_ID       # public na_account_id, also called the Naver common key
NAVER_ADS_API_KEY      # Search Ads API access license
NAVER_ADS_SECRET_KEY   # Search Ads API secret key
NAVER_ADS_CUSTOMER_ID  # numeric advertiser Customer ID

The API uses https://api.searchad.naver.com. Sign each request with HMAC-SHA256 over {timestamp}.{HTTP_METHOD}.{request_uri}. Send the Base64 signature in X-Signature, plus X-Timestamp in Unix milliseconds, X-API-KEY, and X-Customer. See the official sample.

Client-side tag and conversion script

Load the official wcslog.js on every page that needs tracking. Use HTTPS. Set the common key and cookie domain before wcs_do() or wcs.trans().

<script src="https://wcs.naver.net/wcslog.js"></script>
<script>
if (window.wcs) {
  if (!wcs_add) var wcs_add = {};
  wcs_add["wa"] = "<NA_ACCOUNT_ID>";
  wcs.inflow("example.com");
  wcs_do();
}
</script>

<NA_ACCOUNT_ID> is na_account_id, also called the Naver common key. It is not a pixel ID. Store it in the public NAVER_ADS_TAG_ID build setting. The wcs.trans guide defines this setup.

Fire the conversion only after the user action completes. For a paid order, fire it only after the payment provider confirms the charge.

var _conv = {
  type: "purchase",
  id: "<ORDER_ID>",
  value: "50000",
  items: [{
    id: "<PRODUCT_ID>",
    name: "<PRODUCT_NAME>",
    quantity: 1,
    payAmount: 50000
  }]
};
wcs.trans(_conv);

type is required for every conversion. purchase also requires value. Use the advertiser-created id for the action, such as an order number. For an item, id, name, quantity, and total payAmount are the useful fields. The event specification caps reported purchase values at 1 billion.

Server-side conversion API: none published

Naver's public conversion contract is browser wcs.trans(). The test guide shows POST https://wcs.naver.com/b, but does not document a server API.

The public Search Ads API documents ad management and reporting. It documents no conversion upload, conversion identity fields, or server idempotency. Therefore:

• Do not invent a Naver CAPI endpoint or bearer token.
• Do not send raw hub events to wcs.naver.com/b from a webhook.
• Do not create NAVER_ADS_CAPI_TOKEN.
• Keep the payment webhook as business truth in ad-conversion-hub.
• Dispatch Naver conversion events from the confirmed browser flow, then reconcile them with the Search Ads report.

Naver's web event docs define no identity hash fields. Do not send hub identity fields to this script. Apply the hub consent gate before loading or firing. The hub still requires measurement consent and does not require a click ID.

Canonical event mapping

The adapter translates the hub taxonomy at the edge:

Naver also defines add_to_cart, schedule, add_to_wishlist, subscribe, view_product, and ten custom types. subscribe means consent to receive regular information, not necessarily a paid subscription. See the event table.

Deduplication

Naver publishes no client/server deduplication contract because it publishes no server conversion twin. The public event guide defines _conv.id as the advertiser's action ID, but the guide does not say it reconciles requests. Use hub event_id as _conv.id for traceability, not as a claimed deduplication field.

Do not install both wcs.cnv and wcs.trans for one event. After a wcs.trans event, Naver can permanently filter the matching old wcs.cnv event. This is a script-version rule, not event-ID deduplication. See the migration guide.

Click parameter and attribution lifetime

Naver appends the case-sensitive query parameter NaPm to the landing URL. Its value contains fields such as ci (click identifier) and tr (sa for Search Ads or gfa for Performance Display Ads). Preserve the complete raw NaPm value. Do not decode and rebuild it.

wcs.inflow("example.com") lets the script create and read the Naver tracking cookies. For a Search Ads click, the official assistant expects NA_SA, NVADID, and NA_CO. A GFA click uses NA_DA, NVADID, and NA_CO. The official assistant guide documents these names and the NaPm fields.

The conversion attribution window is separate from the browser cookie expiry. For Search Ads, the current default is 15 days and the setting is 7–20 days. Naver counts a direct conversion within 30 minutes of the click. It counts an indirect conversion after 30 minutes and within the configured window. A conversion can therefore appear after a campaign stops. See the official conversion-window help.

UNVERIFIED: Naver's public web tracking docs show that the assistant can display each cookie's expiry, but they do not publish one fixed NaPm or cookie TTL. Do not replace the configured attribution window with a guessed cookie lifetime.

Persist the first and latest raw NaPm values in first-party state only when the product needs its own attribution record. Preserve the parameter through every redirect. Let Naver's script manage its vendor cookies. The URL must not gain a second ?, and a #anchor must not come before NaPm. Naver states that redirects that drop, double-encode, or decode NaPm break attribution. See the official troubleshooting guide.

Quirks that cause real failures

• wcs.trans must run after the common setup and PV code. Running the conversion block first can break tracking.
• Only reportable event types appear in conversion reports. begin_checkout and view_product logs do not become report metrics; lead does. Check the table.
• Search Ads can show a conversion after the campaign stops. Check the window before treating this as a phantom event.
• The Search Ads report can remain empty until installation review completes. The official process says a passed review enables reports from the next day.
• Naver's current attribution models include last-click and data-driven attribution. Do not compare the two metrics as if they were the same count.

Verification

Use three proofs:

1. Request proof: run a click-to-conversion test and confirm the wcs.naver.com request. See the official test guide.
2. Platform proof: query signed GET /stats metrics such as ccnt and convAmt, or create an AD_CONVERSION report. See the conversion report notice.
3. Business proof: compare the report with payment-provider succeeded charges. A browser request or API 200 alone does not prove attribution.

Use the HMAC headers above. Store status, transaction ID, report date, event type, and redacted errors in the hub. Retry only signed report reads after 5xx or timeout errors. Never retry through the undocumented collector.

Common pitfalls

• Treating NAVER_ADS_TAG_ID as a Meta-style pixel ID. It is the na_account_id common key issued by conversion tracking.
• Firing only when NaPm exists. Organic and direct conversions still belong in the payment and product records, even when Naver cannot attribute them.
• Losing NaPm during a mobile redirect or changing its encoding.
• Using a second ? or placing a URL fragment before the Naver parameter.
• Installing the old wcs.cnv script beside wcs.trans.
• Firing purchase before a confirmed charge, or firing it again on refresh.
• Expecting a server webhook to repair a blocked browser tag. Naver has no documented public server conversion upload path.
• Reading an empty same-day conversion report as proof of failure. Check review state, reporting delay, attribution window, and the correct report date.

Security

Keep NAVER_ADS_SECRET_KEY server-side. Keep API credentials out of client bundles. Never log HMAC inputs, signatures, raw NaPm, cookie values, or URLs that contain them. Load only https://wcs.naver.net/wcslog.js and apply the hub consent gate. Keep raw click and identity data inside the server boundary.

Pairing

Use ad-conversion-hub for canonical events, consent, event IDs, retry isolation, and payment reconciliation.