Integrate third-party tracking tools
Before beginning any integration, we recommend familiarizing yourself with the sending conversion events in the Pinterest API.
Google Tag Manager server-side tagging
You can connect your Google Tag Manager account with your server side Conversions API Tag to find out how much Pinterest influences traffic to your store and sales of your products.
Prerequisites
Before proceeding with this integration, we recommend that you:
- Get familiar with Google's Server-Side Tagging and Custom Tag Template.
- Get familiar with how to deploy a server container using your preferred cloud provider. For default Google Cloud Platform deployment, you can refer to Google's guidance.
- Deploy a Google Analytics account, since it should be used to send events.
Integration overview
In order to fire events from a website to our Conversions API (aka server-side GTM), we should set up both a Web Container and a Server Container inside Google Tag Manager (GTM) as is shown here:
Event Types
| GA4 Event Type/Name | Pinterest Event Type/Name | Description |
|---|---|---|
add_to_cart | add_to_cart | Record when items are added to shopping carts. |
purchase | checkout | Record completed transactions. |
| NA | custom | Use this event name to track a special event that you want to include in your conversion
reporting. |
generate_lead | lead | Record interest in product or service. |
page_view | page_visit | Record views of primary pages, such as product pages and article pages. |
search | search | Record searches on your website. |
sign_up | signup | Record sign ups for your products or services. |
view_item_list | view_category | Record views of category pages. |
| NA | watch_video | Record video views. |
You can send GA4 event type and Pinterest will match the event with the equivalent on the Pinterest side according to the above table.
You can send GA4 event type and Pinterest will match the event with the equivalent on the Pinterest side according to the above table.
GA4 Tag
On the Web Container side, we recommend the use of the Google Analytics - GA4 Event Tag to send data to our Conversions API Tag.
We recommend the use of Google Analytics - GA4 Event Tag, however you can also use Universal Analytics Tag.
We recommend the use of Google Analytics - GA4 Event Tag, however you can also use Universal Analytics Tag.
See this official documentation from the Google team for more information.
Below is the payload and its structure expected by the Server Container and the Conversions API Tag for a sample event.
Conversions API Event Parameters
| Pinterest Conversions API event parameter | Description | Sample value | Is it Required? |
|---|---|---|---|
| action_source | Source indicating where the conversion event occurred.
This can be one of the below values:
| app_android | Y, it will be populated with: web, app_android, app_ios or offline |
| event_time | Unix timestamp (in UTC) in seconds when this event occurred.
The event time cannot be in the future of when Pinterest receives the request | 1552333999 | Y
If not provided, it will be populated with the Server Connection Time:
Math.round((new Date()).getTime() / 1000)) |
| event_id | A unique id string that identifies this event and can be used for deduping between events pushed via both the Pinterest API for Conversions and events sent via the Pinterest Tag. | event10101 | N |
| event_source_url | URL of the web conversion event. | http://sample.test.com | N |
| opt_out | Indicates if the user has opted out from web, or offline, it defines whether the user has opted out of tracking for targeted advertising. If opting_out is set to true from or the app id for app_ios, it defines whether they have been limited in Ad Tracking for their iOS device, or opted out of Ads Personalization on their Android device, respectively. | true or false | N |
| partner_name | The third party partner name responsible to send the event to the Pinterest API for Conversions on behalf of the advertiser. Only send this field if Pinterest has directly requested to include this field. | sample_partner_name | N |
| user_data.email_address | User's email addresses, in lowercase. Used for matching. It must be hashed using sha256. | example@domain.com | Y |
| user_data.phone_number | User's phone numbers, only digits w/ country code, area code, and number. It must be hashed using sha256. | 12345678901 | N |
| user_data.gender | User's gender, in lowercase. Either "f" or "m". It must be hashed using sha256. | f | N |
| user_data.date_of_birth | Users date of birthday, given as year, month, and day, must be hashed using sha256. | 19901229 | N |
| user_data.first_name | User's first name, in lowercase. If is must be hashed using sha256. | miko | N |
| user_data.last_name | User's last name, in lowercase. It must be hashed using sha256. | martin | N |
| user_data.address.city | User's city, in lowercase. It must be hashed using sha256. | sanfrancisco | N |
| user_data.address.region | User's subdivision, given as a two-letter code in lowercase. It must be hashed using sha256. | ca | N |
| user_data.address.postal_code | User's postal code. It must be hashed using sha256. | 94123 | N |
| user_data.address.country | Two-character ISO-3166 country code identifying the user's country, in lowercase. It must be hashed using sha256. | us | N |
| user_data.external_id | A unique ID from the advertiser that identifies this user in their space, e.g. loyalty membership ID, user email sign up events. It may improve match quality. It must be hashed using sha256 (such as ROAS/CPA). It must be hashed using sha256. | 123456 | N |
| user_data.click_id | The unique identifier stored in, ptk cookie on your domain or &epik= query parameter in the URL. Web fingerprint key to measure attributions.
It may improve reporting performance such as ROAS/CPA. | bNjYyMDUxODBkMGM2NTM5ZjM3N2JhYjRlNWQwY... | N |
| user_data.hashed_maids | User's "Google Advertising ID (GAID)" or "Apple's Identifier for Advertisers" (IDFA). Used for matching. It must be hashed using sha256. | WmNkYmUzMzYwNzUzNmZmM2RkYTg4ODk2YjNh... | N |
| user_data.client_ip_address | The user's IP address, which can be either in IPv4 or IPv6 format. | 164.45.789.123 | Y
If not provided, Google Analytics IP will be used
ga_ip_override |
| user_data.user_agent | The user agent string of the user's web browser. | Test/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.114 Safari/537.36 | Y
If not provided, Google Analytics
UA will be used
ga_ip_override |
| currency | The ISO-4217 currency code. If not provided, the advertiser's stored currency will be used. | USD | N |
| value | Total value of the event. Accepted as a string in the request, it will be parsed into a float. E.g., for purchase events the total value items in a checkout event, the total basket value, including tax, shipping, etc. | 420.99 | N |
| content_name | The name of the page or product associated with the event. | pinterest-themed-clothing | N |
| content_category | The category of the content associated with the event. | shirts | N |
| content_brand | The category of the content associated with the event. | pinsject-brand | N |
| content_ids | The category of the content associated with the event. | ["id_1","id_2"] | N |
| contents | A list of JSON objects containing information about products, such as price and quantity. | [{"id": "1234", "item_price": "1.00", "quantity": "2.00","quantity": "4.00","quantity": "1.00"}] | N |
| num_items | Number of products purchased in the event, for example, the total number of items purchased in a checkout event. | 5 | N |
| order_id | The order ID. | order_id | N |
| search_string | The search string related to the user conversion event. | shoes | N |
| opt_out_type | Flags if different privacy flags in user logs that opted out from sharing personal information. Values should be comma separated. | LDP | N |
| app_id | The app id of the web conversion event. | app_id_test | N |
| app_name | Name of the app. | app_name_test | N |
| app_version | Version of the app. | app_version_test | N |
| device_brand | Brand of the user's device. | device_brand_test | N |
| device_carrier | User device's mobile carrier. | device_carrier_test | N |
| device_model | Model of the user device. | device_model_test | N |
| device_type | Type of the user device. | device_type_test | N |
| os_version | Version of the device operating system. | os_version_test | N |
| wifi | Whether the event occurred when the user device was connected to wifi. | true or false | N |
| language | Two-character ISO-639-1 language code indicating the user's language. | en | N |
The Conversions API requires at least one of these:
email_addresshashed_maids- or pair+
client_ip_addressclient_user_agent
These params also support single string format, for instance:
- could be sent as
user_data.address.first_nameor["mirko"]mirko- and the array format is mandatory if you send more that one value (such as such as)
["mirko","jerber"]
If these values are not hashed, they will be hashed automatically on the server side by the Conversions API Tag.
If these values are not hashed, they will be hashed automatically on the server side by the Conversions API Tag.
Create the Conversions API Tag
- Go to Server Container and select Tags.
- Select Tag Configuration.
- Select New.
- Create the Conversions API Tag.
Customize the Conversions API Tag
Provide the customized data according to your specific requirements. Customized data includes:
- Advertiser ID: This is your.
ad_account_id - API Access Token: This is the access token you generated to use with the Conversions API.
- For details, see Getting your conversion access token and advertiser ID.
- Event Name: set the event name you want to send to the Conversions API. You can either inherit it from what you defined in Web container (client) or define a new Pinterest standard event name by selecting 'Override client'.
- Event Data: If 'Override client data' is checked, then you can override any parameter you defined on the Web container (client) or set new values for any parameter, even though you didn't define it on the Web container side (client). You should use the same value formats shown in Table One (above).
- Test Mode: If 'Send as a test-request' is checked, then the events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly. Be sure to uncheck 'Send as a test-request' when you want to have your events recorded.
- Logs Settings: You can define if you want to log some results in the console 'Log to console' while in preview or developing/testing mode. Use 'Do not log' when in production.
Customize the Trigger Configuration for the Conversions API Tag
Define the trigger(s) as shown and then save the Tag.
Was this page helpful?