Pinterest Tag
The Pinterest Tag
forwards browser conversions to Pinterest Ads Manager for ad optimization,
retargeting, and audience building. This destination wraps the standard
Pinterest Tag snippet (loaded from s.pinimg.com/ct/core.js); there is no npm
SDK for the browser tag. Mapped events become
window.pintrk('track', eventName, { ..., event_id }) calls, with optional
pintrk('set', ...) for enhanced matching.
Pinterest Tag is a web destination in the walkerOS flow:
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your Pinterest Tag ID (numeric string, e.g. "2612345678901"). Found in Pinterest Ads Manager under Conversions → Pinterest Tag. Passed to pintrk("load", tagId). | |
pageview | boolean | Fire pintrk("page") once in init after core.js loads. Default true (matches Pinterest's base code convention). Set false when walkerOS sources already emit page view events and you would otherwise get a duplicate initial fire. | |
identify | any | walkerOS mapping value resolving to enhanced matching fields: { em?: string, external_id?: string }. em is auto-hashed by the Pinterest JS tag — do not hash before passing. Passed to pintrk("load", tagId, data) on init and pintrk("set", data) when the resolved value changes. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event identity override. Resolves to { em?, external_id? } and fires pintrk("set", data) when the resolved value differs from the current state. |
Examples
Default forward
Without a mapping the walker event name is forwarded as-is to pintrk track with an event_id for dedup.
Identify only
A user update fires pintrk set for enhanced matching without a track call via mapping skip.
Checkout
A completed order fires Pinterest checkout with value, order_id, currency, and a nested line_items array.
Page visit
A mapping renames the walker event to the Pinterest standard pagevisit event for conversion tracking.
Add to cart
A product add fires Pinterest addtocart with value, currency, and a single-item line_items array.
View content
A product view fires Pinterest viewcontent with value, currency, product_id, and product_name.
Search
A site search fires Pinterest search with the search_query field resolved from event data.
Lead with matching
A user login fires pintrk set for enhanced matching and then a lead conversion track call.
Standard event taxonomy
Pinterest expects lowercase concatenated event names. The destination never
auto-maps. Every conversion event needs an explicit mapping.name.
| walkerOS event | Pinterest event | Notes |
|---|---|---|
page view | pagevisit | Fired automatically by pintrk('page') on init unless settings.pageview: false. |
product view | viewcontent | Single product. Use value, currency, product_id, product_name. |
product add | addtocart | Single product. Wrap in a line_items array if you also want item-level data. |
order complete | checkout | Multi-product. Use mapping.data.line_items.loop to iterate event.nested. |
site search | search | Use search_query field. |
user login | lead | Optional lead_type. Combine with settings.identify for enhanced matching. |
user signup | signup | Same identify pattern as lead. |
| (custom) | custom | Send Pinterest's custom event for non-standard conversions. |
Enhanced matching
Pinterest's web tag accepts two enhanced matching fields, both auto-hashed by the JS tag with SHA-256:
| Field | Source | Notes |
|---|---|---|
em | data.email / user.email / etc. | Pinterest auto-hashes. Pass raw email, do NOT pre-hash. |
external_id | data.id / user.id | Stable user identifier. Auto-hashed by Pinterest. |
The destination strictly limits to these two fields. CAPI-only fields (ph,
fn, ln, address, country, ip, ua) belong to the future server
destination and are intentionally not accepted here.
Identity is diffed against the destination's runtime state, and pintrk('set', ...) only fires when the resolved identity actually changes. The
destination-level settings.identify is resolved lazily on the first event
(init has no event to bind to), so pintrk('load', tagId) is called without
an identity object.
Consent
Pinterest is an advertising platform. The walkerOS consent key is
marketing (not analytics):
The walkerOS config.consent gate blocks unconsented events from reaching
the destination in the first place. Pinterest has no opt_in/opt_out SDK
API, so the destination implements consent revocation as a runtime
suppression flag:
on('consent')readsconfig.consentto determine which keys to check.- If any required key resolves to
false, the destination flips_state.consentGranted = falseand silently suppresses all subsequentpintrk('track', ...)calls. - If consent is later re-granted (all required keys
true), the flag flips back and tracking resumes.
The Pinterest Tag itself stays loaded throughout. Only the walkerOS bridge goes silent.
The destination fires pintrk('page') once on init by default to match
Pinterest's base code convention. Set settings.pageview: false if your
walkerOS sources already emit page view events that you map to pagevisit,
which prevents a duplicate initial fire.
Future: Conversions API
A server-side Pinterest Conversions API destination is planned as a follow-up,
matching the Meta / TikTok / LinkedIn web+server split. It will share the
event_id field with this web destination for cross-channel deduplication.