Add Pinterest Analytics API support

[saraichinwag]

Summary

Add Pinterest analytics capabilities to enable traffic analysis from Pinterest data alongside GA4, Bing, and GSC.

Current State

• Pinterest integration exists with OAuth2 auth, pin publishing, and basic read operations
• Current OAuth scopes: boards:read,pins:write
• CLI commands: pins, pin, boards, board-pins, sync-boards, status
• No analytics endpoints exposed

Pinterest API v5 Analytics Endpoints

Pinterest provides these analytics endpoints:

1. User Analytics: GET /v5/user_account/analytics

   • Metrics: impressions, saves, pin_clicks, outbound_clicks, video_views
   • Can filter by date range, pin format, etc.

2. Pin Analytics: GET /v5/pins/{pin_id}/analytics

   • Per-pin performance metrics
   • Impressions, saves, clicks over time

3. Board Analytics: GET /v5/boards/{board_id}/analytics

   • Aggregate metrics for a board
   • Top pins by various metrics

Required Changes

1. Add Analytics Scope

Update PinterestAuth.php:

const SCOPES = 'boards:read,pins:write,user_accounts:read';

Note: This requires re-authorization from users who already authenticated.

2. Create PinterestAnalyticsAbility

New file: inc/Abilities/Pinterest/PinterestAnalyticsAbility.php

Actions:

• user_analytics — Get aggregate user analytics with date range
• pin_analytics — Get analytics for a specific pin
• board_analytics — Get analytics for a specific board
• top_pins — Get top performing pins by metric (impressions, saves, clicks)

3. Add CLI Commands

Extend PinterestCommand.php:

• wp datamachine-socials pinterest analytics --days=28 --metric=impressions
• wp datamachine-socials pinterest top-pins --limit=20 --metric=saves

4. Integrate with DM Analytics CLI (Optional)

Consider adding wp datamachine analytics pinterest namespace to match the existing ga, bing, and gsc analytics commands in the core Data Machine plugin.

Use Case

The Sarai Chinwag site runs a Traffic Analysis flow every 3 days. Pinterest sends 49% of all traffic but currently we have no Pinterest analytics data in those reports. Adding this would enable:

• Identifying top-performing pins by impressions/saves/clicks
• Tracking Pinterest traffic trends over time
• Correlating Pinterest performance with GA4 landing page data
• Finding pins that could be promoted or updated

Related

• saraichinwag.com agent ping Flow 40 (Traffic Analysis) currently pulls GA4, Bing, and GSC data — Pinterest would complete the picture