=== CODlino Pixel Tracking with Meta and TikTok ===
Contributors: tahabelmezrar
Tags: woocommerce, meta pixel, tiktok pixel, conversions api, cash on delivery
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 7.4
Requires Plugins: woocommerce
Stable tag: 0.2.10
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Track WooCommerce and CODlino orders with up to 10 Meta Pixels, direct Meta Conversions API and a TikTok browser Pixel.

== Description ==

CODlino Pixel connects your WooCommerce store to your own Meta and TikTok data sources. It supports standard WooCommerce checkout and optional [CODlino COD Order Forms](https://wordpress.org/plugins/codlino-cod-order-forms/).

This is an independent plugin by Taha Belmezrar, the developer of CODlino COD Order Forms. It is not affiliated with, endorsed by, or an official product of Meta or TikTok. Those names identify the third-party services it integrates with.

* Up to 10 unique Meta Pixel IDs with separate tokens and test codes.
* Direct Meta Conversions API Purchase delivery, without an intermediary service.
* One TikTok browser Pixel; TikTok Events API is not included.
* Browser events: PageView, ViewContent, InitiateCheckout and Purchase.
* Shared Meta event IDs for browser/server deduplication.
* Independent server jobs, transient-failure retries and per-Pixel delivery status.
* Arabic, French and English dashboard with per-user language preferences.
* Responsive, RTL-aware interface and locally bundled Arabic fonts.
* WooCommerce order CRUD APIs and HPOS compatibility declaration.

Tracking is disabled by default. Marketing consent is required by default; connect your existing cookie banner before enabling tracking. No cookie banner is included.

For COD, Purchase means an accepted order, not delivery or payment. Product IDs use variation IDs; values come from order totals. No AddToCart or historical tracking.

== Installation ==

1. Install and activate WooCommerce. CODlino COD Order Forms is optional.
2. Install CODlino Pixel and open CODlino Pixel in the WordPress admin menu.
3. Enter your Meta Pixel ID and Access Token. Add other Meta Pixels if needed.
4. Optionally enter a TikTok Pixel ID and enable TikTok tracking.
5. Connect your marketing-consent banner, enable tracking and save.
6. Disable duplicate Meta/TikTok tags in other plugins or tag managers.
7. Save a Meta Test Event Code, select a Pixel and send a test PageView.
8. Test real orders on staging. Verify Meta browser/server deduplication and TikTok events with the platforms' testing tools.
9. Remove Meta Test Event Codes before production use.

== Frequently Asked Questions ==

= Is CODlino required? =
No. WooCommerce is required; CODlino order forms are an optional integration.

= How many Pixels can I add? =
One primary and nine additional Meta Pixels, plus one TikTok Pixel. All enabled destinations receive the same supported browser events. Meta server Purchase delivery requires a token for each destination and the global CAPI switch.

= How do I connect my cookie banner? =
After marketing consent, call window.CODlinoPixel?.grantConsent(). On withdrawal, call window.CODlinoPixel?.revokeConsent(). Call after the frontend script has loaded. Developers can adapt server-side consent using the codlino_pixel_consent filter.

Without the banner connection, tracking stays disabled while the consent setting is on. Disable the consent requirement only where your store configuration permits immediate tracking. Withdrawal stops subsequent plugin browser events and new order captures; previously consented queued orders can still be delivered. Configure automatic matching/events in Meta and TikTok separately as needed.

= Are tokens exposed in the browser? =
No. Tokens are saved in a non-public WordPress option and omitted from page HTML and frontend configuration. Blank token fields preserve the saved token for that same Pixel ID. Changing an ID does not transfer its old token.

= How do retries work? =
WooCommerce's Action Scheduler is used when available, otherwise WordPress Cron. Network failures, HTTP 429/5xx and transient Meta errors retry up to six times with the same event ID. Permanent failures are recorded without retries. Configure a working cron on low-traffic stores.

= Does TikTok include server tracking? =
No. This release includes TikTok browser Pixel only. It uses the current Purchase event name. Verify it with TikTok Pixel Helper and Events Manager Test Events.

= Is there a subscription or author account? =
No intermediary subscription or author account is required. You need your own Meta/TikTok accounts for the external services. This plugin does not send telemetry to its author.

== External services and privacy ==

External services are optional and must be configured by the merchant. Installing or activating this plugin alone does not initialize tracking. A test button sends synthetic data only after an administrator requests it.

= Meta Pixel and Conversions API =

Purpose: advertising measurement and conversion reporting in the merchant's Meta account.
When: browser tracking runs when configured, enabled and consented (unless immediate tracking is configured). Server Purchase events are queued after consented orders and delivered asynchronously when CAPI is enabled. A saved Test Event Code routes events to Meta's test mode.
Connections: connect.facebook.net/en_US/fbevents.js, Meta's SDK endpoints, and graph.facebook.com/{version}/{pixel-id}/events. The API version is configurable.
Data: browser requests expose IP address, user agent, page information and event data to Meta. Server Purchase data includes time, event ID, order ID, currency, total, product IDs/quantities, customer IP/user agent and fbp/fbc cookies when available. Email, phone and billing country are normalized and SHA-256 hashed for matching where available. Hashing is not anonymization. Moroccan local mobile numbers are normalized to 212; ambiguous local numbers outside Morocco are omitted. Server events use the store home URL, not the secret confirmation URL.
Service: https://developers.facebook.com/docs/marketing-api/conversions-api/
Terms: https://www.facebook.com/legal/technology_terms
Privacy: https://www.facebook.com/privacy/policy/

= TikTok Pixel =

Purpose: website event measurement and advertising conversion reporting in the merchant's TikTok account.
When: only when TikTok is configured, enabled and consented (unless immediate tracking is configured).
Connections: analytics.tiktok.com/i18n/pixel/events.js and the SDK's TikTok service endpoints.
Data: browser IP/user agent, page and referrer information, TikTok cookies/identifiers where permitted, event names, product identifiers/quantities, currency and value. This plugin does not explicitly send customer email/phone to TikTok; additional SDK collection depends on the merchant's TikTok settings.
Service: https://ads.tiktok.com/help/article/tiktok-pixel
Terms: https://ads.tiktok.com/i18n/official/policy/business-products-terms
Privacy: https://www.tiktok.com/legal/page/row/privacy-policy/en

= Local storage and retention =

WordPress stores settings, tokens and language preferences. WooCommerce orders retain event IDs/times, destination IDs, consent at capture, attribution cookies/browser context and delivery status, subject to the merchant's order retention policy. The consent cookie lasts 180 days; browser sessionStorage holds duplicate-event markers. Diagnostics contain delivery status, not full payloads or tokens.

Deactivation and deletion preserve configuration and order metadata. Before removal, clear saved tokens using each token-removal control or remove additional Pixel rows and save. Merchants manage WooCommerce retention and any copies held by the external platforms.

= Optional currency conversion (Frankfurter) =

Store/order currency is read automatically. Supported Meta browser currencies such as USD, EUR, SAR, QAR and AED remain unchanged. Unsupported currencies such as MAD require conversion for monetary tracking. Enable Allow automatic exchange rates and choose USD or EUR as the fallback; save and refresh the rate before testing. Conversion affects tracking only, never store/order prices. Each order keeps one rate/value snapshot shared by browser/server and retries. Without a valid rate, Purchase waits instead of sending invalid or relabeled money. Older orders with a previously sent server event are not revalued for browser tracking.

Frankfurter requests occur only after the merchant opts in, for currency pairs requiring conversion. The server requests api.frankfurter.dev/v2/rate/{base}/{quote}, sending currency codes and ordinary server HTTP information, not customer/order data or tokens. Rates are cached for 24 hours and expire after 48 hours; the reference observation must be no older than seven days. These are reference rates, not bank settlement quotes. Service, terms and privacy details: https://frankfurter.dev/ (FAQ and provider terms). No account or API key is required.

== Included assets and source ==

Readable PHP/JS/CSS/SVG source is included; no build step. Fonts and icons are local. Arabic uses Janna if already supplied by the site/system, otherwise bundled Tajawal (Copyright 2018 Boutros International, SIL Open Font License 1.1; see assets/fonts/tajawal/OFL.txt). The plugin does not bundle Janna.

== Screenshots ==

1. Meta Pixel and Conversions API connection settings.
2. Tracking, consent and optional currency conversion settings.
3. Arabic dashboard and language selection.
4. Included Arabic setup guide.

== Changelog ==

= 0.2.10 =
Preserve full attribution click identifiers without truncation and omit invalid placeholder identifiers.

= 0.2.9 =
Added an Arabic A-to-Z setup guide inside the dashboard and clearer emerald colors, fields and buttons. Tracking behavior is preserved.
