Analytics Documentation

Complete guide to setting up and using the Analytics add-on

Installation

Requirements

  • Paapi Product Search for Amazon Premium - must be installed and activated
  • WordPress 5.8 or higher
  • PHP 7.4 or higher

Setup Steps

  1. Purchase and download the Analytics add-on from your account
  2. In WordPress, go to Plugins > Add New > Upload Plugin
  3. Upload the zip file and click Install Now
  4. Click Activate
  5. The tracker script loads automatically - no configuration needed

Once activated, Analytics immediately starts tracking visitor interactions on pages that contain the [psfa_search] shortcode.

Dashboard Overview

Navigate to PaapiPlugin > Analytics in your WordPress admin to access the dashboard.

Summary Cards

The top row shows key metrics for the selected date range: total searches, total clicks, unique sessions, and the top search query.

Charts

  • Searches and Clicks Over Time - daily trend line chart
  • Top Queries - bar chart of most popular search terms
  • Top Products - bar chart of most clicked products
  • Filter Usage - breakdown of which filters visitors use

Tables

  • Queries Table - sortable list of all search queries with counts
  • Products Table - sortable list of clicked products with ASIN, title, and click count
  • Events Log - raw event stream with timestamp, type, value, and session ID

Date Range

Use the date picker at the top to filter data. Quick presets: Last 7 days, Last 30 days, Last 90 days. Or set a custom date range.

Event Types

The tracker captures 24 event types across four categories:

Search Events

  • search - search query submitted
  • search_autocomplete - autocomplete suggestion selected
  • search_no_results - search returned zero results

Product Events

  • product_click - product card clicked
  • product_impression - product entered viewport
  • buy_click - buy button clicked (affiliate link)
  • product_box_click - product box addon click
  • comparison_table_click - comparison table addon click

Filter Events

  • filter_category, filter_brand, filter_price, filter_condition, filter_merchant, filter_sort, filter_deal, filter_rating, filter_saving

Navigation Events

  • page_view, load_more, layout_change, search_clear, filter_reset, session_start

Exporting Data

Click the Export button in the dashboard toolbar to download analytics data.

  • CSV - compatible with Excel, Google Sheets, and BI tools
  • JSON - structured format for developers and automated pipelines

Exports include data for the currently selected date range. Set a custom range before exporting to get exactly the data you need.

Data Retention

A daily WP-Cron job runs automatically to:

  1. Aggregate raw events into daily summary rows
  2. Calculate top values (top query, top product) for each day
  3. Delete raw events that have been aggregated
  4. Prune aggregated data older than the retention period

The default retention period is 90 days. Export your data before it expires if you need long-term records.

Privacy

Analytics is designed to be privacy-first:

  • No cookies - does not set any cookies
  • No PII - does not collect names, emails, or any personal information
  • No IP logging - IP addresses are never stored
  • Session IDs - random UUIDs generated per browser tab, stored in sessionStorage only, discarded when the tab closes
  • First-party only - all data stays in your WordPress database, never sent to external services

This design makes the add-on compatible with GDPR, CCPA, and similar privacy regulations without requiring cookie consent banners.