WP Manifestindependent plugin directory
manifest / unclassified / tiktok-pixel-events-api

TikTok Pixel & Events API for WooCommerce

Enterprise-grade dual-tracking for WooCommerce: browser-side TikTok Pixel + server-side Events API (v1.3) with SHA-256 PII hashing, deduplication, ttclid capture, failed-event retry queue, and connection testing.

by kiunye · github.com/kiunye/tiktok-pixel-events-api · website

★ 0stars

Install

Download source zip No release zip yet

This is the repository archive. It installs, but the folder name will carry the branch suffix and updates will not flow.

Install straight from GitHub with WP-CLI:

wp plugin install https://github.com/kiunye/tiktok-pixel-events-api/archive/refs/heads/master.zip
No built-in updater. New versions won't appear under Dashboard → Updates. Install new releases yourself, or let Git Updater track the repository.
Readme github.com/kiunye/tiktok-pixel-events-api ↗

Enterprise-grade dual-tracking for WooCommerce: browser-side TikTok Pixel + server-side Events API with deduplication, ttclid capture, and a DB-backed retry queue.

Description

TikTok Pixel & Events API for WooCommerce implements TikTok's recommended dual-tracking architecture — combining the browser-side Pixel JavaScript with the server-side Events API (v1.3) — to capture the maximum number of conversions, even from visitors running ad blockers.

Tracked Events

● AddToCart — fires when a product is added to the WooCommerce cart (browser + server). ● InitiateCheckout — fires when a customer lands on the checkout page (browser + server). ● Purchase — fires when an order is completed (browser + server).

Key Features

● Dual-channel tracking — browser Pixel and server-side Events API run in parallel. ● Automatic deduplication — a shared event_id is generated once and used in both channels. TikTok counts each conversion exactly once. ● SHA-256 PII hashing — email, phone number, and external ID are hashed before transmission, per TikTok's spec and GDPR best practice. ● ttclid capture — reads the TikTok click ID from landing page URLs, stores it in a first-party cookie, and includes it in server-side payloads for improved ad attribution. ● Failed-event retry queue — a custom database table persists failed API dispatches. A WP-Cron job retries hourly with exponential backoff (1h → 4h → 24h). Zero conversion data loss on transient network errors. ● Connection tester — one-click AJAX button in the admin verifies credentials live against the TikTok API. ● WP REST API endpoint — /wp-json/tpea/v1/event and /wp-json/tpea/v1/status for headless integrations. ● WooCommerce HPOS compatible — fully compatible with WooCommerce High-Performance Order Storage. ● Object caching — settings are stored in the WordPress object cache (Redis/Memcached compatible). ● Multisite compatible — proper network-wide cleanup on uninstall.

Security

● All PII hashed with SHA-256 before leaving your server. ● Nonce verification on all admin form submissions and AJAX handlers. ● Capability checks (manage_woocommerce) on every admin action and REST endpoint. ● Sanitised, validated, and escaped input and output throughout. ● Prepared SQL statements everywhere direct DB access is required.

Installation

  1. Upload the plugin folder to /wp-content/plugins/.
  2. Activate the plugin through the Plugins menu in WordPress.
  3. Navigate to WooCommerce → TikTok Pixel.
  4. Enter your Pixel ID and Events API Access Token from TikTok Ads Manager.
  5. Click Test Connection to verify credentials.
  6. Remove the Test Event Code before going live.

How to get your credentials

  1. Log in to TikTok Ads Manager.
  2. Navigate to Assets → Events → Website (Events Manager).
  3. Select your Pixel (or create one with Manually install pixel code + Developer Mode).
  4. Copy the Pixel ID from the overview panel.
  5. Click Settings → Generate Access Token to create your Events API token.

Frequently Asked Questions

Do I need to use both the Pixel and the Events API?

No, but TikTok strongly recommends it. Running both channels and using deduplication captures events that ad blockers would otherwise suppress, improving your campaign data by an estimated 15–19% (TikTok, 2025).

Is PII (email, phone) transmitted to TikTok in plain text?

No. All personally identifiable information is SHA-256 hashed before leaving your server. The original values are never transmitted.

What happens if the Events API call fails?

The full payload is written to a custom database table and retried hourly by a WP-Cron job, using exponential backoff. Events are retried up to 3 times (1h → 4h → 24h), then permanently marked failed. All failures are visible in the Event Queue tab and logged to WooCommerce → Status → Logs under the tpea source.

Is this compatible with WooCommerce HPOS (High-Performance Order Storage)?

Yes. The plugin declares full HPOS compatibility and uses WooCommerce's order API exclusively (never raw post meta queries) for order data.

Can I use this with a headless WooCommerce setup?

Yes. The REST API endpoint POST /wp-json/tpea/v1/event accepts an event name and optional order ID, allowing external systems to trigger server-side events programmatically.

Where are errors logged?

In WooCommerce → Status → Logs, filtered by source tpea. Enable WP_DEBUG in wp-config.php to see successful dispatch entries too.

Changelog

1.0.0

● Initial release. ● Browser-side Pixel with AddToCart, InitiateCheckout, and Purchase. ● Server-side Events API (v1.3) with SHA-256 PII hashing. ● Automatic deduplication via shared event_id. ● ttclid capture and cookie storage. ● DB-backed failed-event retry queue with exponential backoff. ● AJAX connection tester. ● WP REST API endpoints (/event, /status). ● Diagnostics tab with environment checks. ● HPOS and multisite compatibility.

Upgrade Notice

1.0.0

Initial release.