Pinterest Conversions Server & API

This package simplifies the integration of Pinterest's Conversion API for tracking conversion events. It includes tools server-side event tracking (Pinterest Conversion API).

Installation

npm install pinterest-conversions-server

Features

• Pinterest Conversion API: Server-side event tracking using the Pinterest API.
• Express Server Integration: Easily set up an API server for handling conversion events.
• Test Environment Support: Send test events for validation.

Usage

1. Import and Initialize

import {
  PinterestConversionsServer,
  PinterestConversionsAPI,
} from "pinterest-conversions-server";

3. Pinterest Conversions API (Server-Side)

a. Initialize the API Client

const conversionsAPI = new PinterestConversionsAPI("<ACCESS_TOKEN>");

b. Track an Event

const data = {
  event_name: "custom",
  action_source: "web",
  event_time: Math.floor(Date.now() / 1000),
  event_id: "eventId001",
  user_data: {
    external_id: ["<hashed_external_id>"],
    em: ["<hashed_email>"],
    client_user_agent: "user-agent",
    client_ip_address: "123.45.67.89",
  },
};

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

c. Send Test Events

const testResponse = await conversionsAPI.trackEventTest(
  "<ADVERTISER_ID>",
  data
);
console.log(testResponse);

4. Pinterest Conversions Server

a. Start the Server

new PinterestConversionsServer(
  "<ACCESS_TOKEN>",
  "<ADVERTISER_ID>"
).startPinterestApiServer(3000);

b. API Endpoints

• POST /track-event

  • Body:

    {
      "advertiser_id": "<ADVERTISER_ID>",
      "event_data": { ...eventPayload }
    }

• POST /track-event-test

  • Body: Same as /track-event but validates test events.

Example Implementation Outside the Package

import { PinterestConversionsServer } from "pinterest-conversions-server";

const TOKEN = "<ACCESS_TOKEN>";
const ADVERTISER = "<ADVERTISER_ID>";

new PinterestConversionsServer(TOKEN, ADVERTISER).startPinterestApiServer(3001);

Interfaces

PinterestEvent

interface PinterestEvent {
  event_name: string;
  action_source: string;
  event_time: number;
  event_id?: string;
  user_data: Record<string, string | number | boolean | Array<string>>;
}

TrackEventResponse

interface TrackEventResponse {
  status?: number;
  [key: string]: any;
}

TrackEventRequest

interface TrackEventRequest {
  advertiser_id: string;
  event_data: PinterestEvent;
}

Development

Testing

• Run the server and test API endpoints using Postman or similar tools.
• Use mock data for advertiser_id and event_data.

Example Data

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

Notes

• Ensure all sensitive data is hashed as required by Pinterest API.
• The server includes CORS support. Adjust allowed origins as needed for security.

License

MIT