Pinterest Conversion API Managed Component

Find out more about Managed Components here for inspiration and motivation details.

🚀 Quickstart local dev environment

1. Make sure you're running node version >=17.
2. Install dependencies with npm i
3. Run unit test watcher with npm run test:dev

⚙️ Tool Settings

Settings are used to configure the tool in a Component Manager config file

Ad Account ID string required

ad_account_id: The Pinterest Ad Account ID serves as the unique identifier for your Pinterest Ad Account. It must be 18 characters or fewer. You can locate it when generating a Conversion API Token, displayed on the same screen. Learn more.

Conversion Token string required

conversion_token: The Pinterest conversion token is required to access the Coversion API endpoint and can be generated through Ads Manager. Review the Conversions Guide for more details.

⚙️ Fields Description

Fields are properties that can/must be sent with certain events.

Required Fields

Event Name string required

event_name Pinterest's Event Name property should be holding the event name. In this implementation, the event name will be set to 'page_visit' for a pageview event type. In case of 'event' event type, Pinterest is allowing a limited set of events: 'custom', 'lead','search', 'signup', 'view_category' and 'watch_video'. You should make sure to use these exact naming conventions as values of payload.name. This MC will automatically assign the value into event_name when you do so. For 'ecommerce' event types, see ecommerce section below. For example, in WebCM, webcm.track('event', {name: 'signup'}) will result in sending event_name: 'signup' to Pinterest.

Action Source string required

action_source Pinterest's Action Source is indicating the source where the conversion event occurred. This MC sets it to web by deafault, unless payload.action_source is holding a different value. Pinterest allows one of the following values: app_android, app_ios, web, offline.

Event ID string required

event_id Pinterest's Event ID is a unique id string that identifies a certain event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. This MC is looking for values under payload.event_id or payload.ecommerce.event_id and if it cannot find one, it generates a random ID.

Client IP Address string required

client_ip_address Pinterest's Client IP Address is the user's IP address, which can be either in IPv4 or IPv6 format. This MC is automatically extracting it from the Client, unless payload.client_ip_address is sent, in which case it will override the original value. Note, It is required that you send at least one of em hashed_maids, or pair client_ip_address + client_user_agent.

Client User Agent string required

client_user_agent Pinterest's Client User Agent is the user agent string of the user's web browser. This MC is automatically extracting it from the Client, unless payload.client_user_agent is sent, in which case it will override the original value. Note, It is required that you send at least one of em hashed_maids, or pair client_ip_address + client_user_agent.

Optional Fields

Event Source Url string optional

event_source_url Pinterest's Event Source Url is the URL of the web conversion event. Automatically generated by this MC but can be overriden by passing a value in payload.event_source_url.

Opt Out boolean optional

opt_out When 'action_source' is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when 'action_source' is app_android or app_ios, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device. This MC sets the value to False, unless the value of payload.opt_out is set to true.

Partner Name string optional

partner_name The third party artner name responsible to send the event to Conversions API on behalf of the advertiser. The naming convention is "ss-partnername" lowercase. E.g ‘ss-webcm’.

App ID string optional

app_id The app store app ID.

App Name string optional

app_name The name of the app.

App Version string optional

app_version The version of the app.

Device Brand string optional

device_brand The brand of the user device.

Device Model string optional

device_model The model of the user device.

Operating System Version string optional

os_version The version of the device operating system.

Language string optional

language The Language property holds the two-character ISO-639-1 language code indicating the user's language. This MC extracts the value automatically from the client, If you pass payload.language, it will override the value assigned by the MC.

Wifi boolean optional

wifi The wifi property holds information of wifi usage. It should be set to true if the event occured when the user device was connected to wifi.

Email string optional

em Sha256 hashes of lowercase version of user's email addresses. This MC hashes the string included in payload.em automatically.

Hashed Maids string optional

hashed_maids Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. This MC hashes the string included in payload.hashed_maids automatically.

Phone string optional

ph Sha256 hashes of user's phone numbers, only digits with country code, area code, and number. Remove any symbols, letters, spaces and leading zeros. This MC hashes the string included in payload.ph automatically.

Gender string optional

ge Sha256 hashes of user's gender, in lowercase. Either "f" or "m" or "n" for non-binary gender. This MC hashes the string included in payload.ge automatically.

Birthday string optional

bd Sha256 hashes of user's date of birthday, given as year, month, and day. This MC hashes the string included in payload.bd automatically.

Last Name string optional

ln Sha256 hashes of user's last name, in lowercase. This MC hashes the string included in payload.ln automatically.

First Name string optional

fn Sha256 hashes of user's first name, in lowercase. This MC hashes the string included in payload.fn automatically.

City string optional

ct Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. This MC hashes the string included in payload.ct automatically.

State string optional

st Sha256 hashes of user's state, given as a two-letter code in lowercase. This MC hashes the string included in payload.st automatically.

Zipcode string optional

zp Sha256 hashes of user's zipcode, only digits. User residency zipcode. This MC hashes the string included in payload.zp automatically.

Country string optional

country Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase. This MC hashes the string included in payload.country automatically.

External ID string optional

external_id Sha256 hashes of the unique id from the advertiser that identifies a user in their space, e.g. user id, loyalty id, etc. This MC hashes the string included in payload.external_id automatically.

Click ID string optional

click_id The unique identifier stored in _epik cookie on your domain or &epik= query parameter in the URL. This MC hashes the string included in payload.click_id automatically.

Opt Out Type string optional

opt_out_type Flags for different privacy rights laws to opt out users of sharing personal information. Values should be comma separated. Please follow Pinterest's Help Center and dev site for specific opt_out_type set up.

Named Partner string optional

np Named partner. Not required, this is for Pinterest internal use only. Please do not use this unless specifically guided by the Pinterest team.

Ecommerce

Pinterest allows sending the following types of ecommerce properties: currency, value, content_ids, content_name, content_category, content_brand, contents (which is an array of object, each one holding contents.id, contents.price and contents.quantity) num_items, and order_id. You can see their definitions here, under data > custom data section.

Pinterest is accepting the two ecommerce events: add_to_cart and checkout. This MC therefore, supports the following types of Ecommerce events:

1. Product Added
2. Order Completed

You should use exactly these naming conventions and send them as the name property for ecommerce to work. Together with each one, you can send the following properties:

1. revenue, total or value (the MC will first look for revenue and if not found, total, and then value) and will send it via the Pinterest value parameter.
2. products - an array of products and their details, will be map to the relevant parameters that start with content_ or the contents array.
3. quantity, will be mapped to Pinterest's num_items. If quantity is not specified the MC will look for the quantity of each product object inside products, and will add them.

So for example, in WebCM the following snippet:

webcm.track('ecommerce', {
  name: 'Order Completed',
  order_id: '1234',
  total: 30.0,
  revenue: 25.0,
  shipping: 3,
  tax: 2,
  coupon: 'winter-sale',
  currency: 'USD',
  products: [
    {
      product_id: '1111product',
      sku: '1234',
      name: 'Shorts',
      price: 10,
      quantity: 2,
      category: 'shorts',
    },
    {
      product_id: '2222product',
      sku: '5678',
      name: 'T-shirt',
      price: 5,
      quantity: 2,
      category: 'T-shirts',
    },
  ],
})

Will result in sending these Event Properties:

• value: 25.0
• quantity: 4
• contents: [{id: '1111product',item_price: 10,quantity: 2},{id: '2222product', item_price: 5, quantity: 2}]

📝 License

Licensed under the Apache License.

💜 Thanks

Thanks to everyone contributing in any manner for this repo and to everyone working on Open Source in general.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!