Simplify Pinterest Conversion Tracking with NPM Packages

Juan Benavides Nanni; SDET II |

Pinterest conversions are critical for businesses looking to optimize their campaigns and track the performance of their advertisements. By leveraging Pinterest’s Conversion API and Conversion Tag, advertisers can gain deeper insights into user behavior and fine-tune their marketing efforts.

To make this process seamless for developers, we’ve created two NPM packages: pinterest-conversions-server and pinterest-conversions-client. These packages simplify the integration of Pinterest’s Conversion API and Conversion Tag, offering robust solutions for server-side and client-side tracking.

Why Use Pinterest Conversions?

Pinterest conversions allow businesses to:

Track valuable user actions like purchases, sign-ups, and more
Attribute these actions to specific Pinterest campaigns for better ROI analysis
Enable retargeting and audience-building based on collected event data

However, implementing these features often requires complex setup and knowledge of Pinterest’s API. Our packages help remove these barriers, making integration faster and more developer-friendly.

Goals for These Packages

Our goal is to provide developers with a streamlined way to:

Track events server-side using the Pinterest Conversion API
Set up client-side tracking with the Pinterest Conversion Tag
Validate events in test environments, helping to ensure accuracy before production deployment
Offer clean, reusable interfaces that developers can integrate into their projects with minimal effort.

Meet the Packages

1. Pinterest Conversions Server (API)

This package enables server-side event tracking using Pinterest’s Conversion API. Ideal for back-end developers, it supports advanced use cases like hashed user data and precise event attribution.

Installation

npm install pinterest-conversions-server

Features

Server-side event tracking using Pinterest API
Express server integration for handling API endpoints
Support for test events to validate implementation

a. Initialize the API Client

import { PinterestConversionsAPI } from "pinterest-conversions-server";
const conversionsAPI = new PinterestConversionsAPI("<ACCESS_TOKEN>");

b. Track an Event

const data = {
event_name: "purchase",
action_source: "web",
event_time: Math.floor(Date.now() / 1000),
user_data: {
external_id: ["<hashed_external_id>"],
em: ["<hashed_email>"],},};

const response = await conversionsAPI.trackEvent("<ADVERTISER_ID>", data);

c. Set Up an API Server

import { PinterestConversionsServer } from "pinterest-conversions-server";
new PinterestConversionsServer("<ACCESS_TOKEN>", "<ADVERTISER_ID>").startPinterestApiServer(3000);

2. Pinterest Conversions Client (Tag)

This package simplifies client-side tracking with the Pinterest Tag. It’s perfect for tracking events directly from the browser.

Installation

npm install pinterest-conversions-client

Client-side tracking via Pinterest Tag
Easy integration for web applications
Support for test events to validate data

a. Initialize the Pinterest Tag

import { PinterestTag } from "pinterest-conversions-client";
const pinterestTag = new PinterestTag("<PIXEL_ID>");b. Track an Event

pinterestTag.track("custom_event", {

product_id: "12345",
value: 100,
});

Development and Testing

Both packages are designed with testing in mind:

Use mock data to test server-side events in development environments
Validate client-side events with test mode enabled in Pinterest

Example Test Data

{
"event_name": "purchase",
"action_source": "web",
"event_time": 1609459200,
"user_data": {
"em": ["hashed_email"],
"external_id": ["hashed_id"]}

}

When using these packages, ensure all sensitive data, like email addresses, is properly hashed, and ensure that you clearly disclose and get any legally-required consent for the collection, sharing and use (including use by Pinterest) of the data you’re sharing as set forth in our Ad Data Terms. Additionally, configure CORS settings if deploying the server package in a multi-origin environment.

Both packages are open source and available under the MIT license. We welcome contributions and feedback from the developer community.

Conclusion

Tracking conversions shouldn’t be a hassle. With pinterest-conversions-server and pinterest-conversions-client, you can quickly integrate Pinterest’s powerful tracking tools into your projects. Start tracking, optimize your campaigns, and help boost your ROI with ease.

To learn more about engineering at Pinterest, check out the rest of our Engineering Blog and visit our Pinterest Labs site. To explore and apply to open roles, visit our Careers page.