=== Markopolo AI ===
Contributors: cgzirim
Tags: analytics, tracking, marketing, attribution
Requires at least: 5.8
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.0.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Track WordPress events and send them to the Markopolo AI analytics platform.

== Description ==

Markopolo AI is a lightweight tracking plugin that captures key WordPress site events and sends them to the Markopolo AI analytics platform for reporting and attribution.

= Key Features =

* **Page and interaction tracking**: captures `page_view`, `click`, `form_interaction`, and `Search` events.
* **Form data capture**: can capture name, email, and phone values when they are present in forms.
* **Session tracking**: uses a UUID-based session identifier to group user activity.
* **First-party identifier**: manages a `muid` cookie for visitor identification.
* **Marketing attribution data**: can include common attribution cookies such as Facebook Pixel, TikTok, Google Analytics, and Microsoft UET cookies when present.
* **Simple configuration**: add your Tag ID from a WordPress admin settings page.
* **Lightweight front-end script**: loads only when a valid Tag ID and endpoint are configured.

= How It Works =

1. Install and activate the plugin.
2. Go to **Settings > Markopolo AIr**.
3. Enable **Enable Tracking** in plugin settings.
4. Enter your **Tag ID**.
5. Save settings.
6. The plugin loads its front-end script and sends tracked events to the Markopolo endpoint.

Tracking is off by default. The plugin does not load front-end tracking until **Enable Tracking** is enabled by an admin and a valid Tag ID is provided.

== External Services ==

This plugin relies on Markopolo AI services to provide analytics and attribution functionality.

= Service A: Event ingestion endpoint =

* **What it is used for**: Receiving browser-side analytics events for reporting and attribution.
* **Endpoint**: `https://mtag.markopolo.ai/mark`
* **When data is sent**: On tracked front-end events (for example page views, clicks, form interactions, and search events) only after admin opt-in via **Enable Tracking**, with a valid Tag ID and endpoint configured.
* **Data sent may include**: tag ID, page URL/path/title, referrer, language, timezone, viewport/screen data, session and visitor identifiers, attribution cookies when available, click metadata, and form-related values such as name/email/phone/search terms when detected.

= Service B: Settings webhook endpoint =

* **What it is used for**: Notifying Markopolo when plugin settings lifecycle events occur.
* **Endpoint**: `https://api-alpha.markopolo.ai/v1/integrations/wordpress/webhook`
* **When data is sent**:
	* Only after an admin has enabled **Enable Tracking**.
	* When Tag ID is set for the first time.
	* When Tag ID is updated.
	* When Tag ID is removed.
	* During plugin uninstall, only when tracking is enabled and a Tag ID is configured.
* **Data sent**: event name, tag ID, previous tag ID (when applicable), plugin name, site URL, and event timestamp.

= Service terms and privacy =

* Terms and legal information: https://markopolo.ai/legal
* Privacy policy: https://markopolo.ai/legal

= Event Types Tracked =

* **page_view**: fired on page load.
* **click**: fired when users interact with common clickable elements.
* **form_interaction**: fired on form change and submit events.
* **Search**: fired when a search term is detected from a search form or search URL.

= Data Collected =

Depending on the page and user interaction, the plugin may collect and send:

* Page URL, path, title, referrer, language, timezone, viewport, and screen size
* Session ID and visitor identifier (`muid`)
* Marketing attribution cookies when available
* Form values such as name, email, phone, and search terms
* Click metadata such as element text, ID, class, and coordinates

= Privacy & Consent =

This plugin tracks customer behavior including:
* Page views, clicks, searches, and form interactions
* Email addresses and phone numbers from form interactions
* Marketing cookies (Facebook Pixel, TikTok, Google Analytics)
* Session data and user identifiers

All data is sent to the Markopolo AI platform for analytics purposes. Ensure your privacy policy covers this data collection and complies with applicable privacy regulations (GDPR, CCPA, etc.).

Important: Site owners are responsible for obtaining any user consent required under applicable laws and regulations before enabling or using tracking features.

Plugin-level enablement requires admin opt-in. If **Enable Tracking** is disabled, front-end tracking and settings webhooks are disabled. Front-end tracking also requires a valid Tag ID.

= Developer Notes =

* The plugin uses a WordPress admin settings page for configuration.
* Settings are sanitized before being saved.
* Events are sent asynchronously from the front end.
* The plugin includes an uninstall routine that removes its saved settings.

== Installation ==

= Automatic Installation =

1. Upload the plugin ZIP in **Plugins > Add New > Upload Plugin**.
2. Or install it from the WordPress plugin directory if available.
3. Activate **Markopolo AI**.
4. Go to **Settings > Markopolo AI**, enable **Enable Tracking**, and enter your Tag ID.

= Manual Installation =

1. Upload the plugin folder to `/wp-content/plugins/markopolo-tracker/`.
2. Activate the plugin in the WordPress admin.
3. Open **Settings > Markopolo AI**.
4. Enable **Enable Tracking**, add your Tag ID, and save.

= After Installation =

1. Visit your site in a browser.
2. Open the browser network panel to confirm tracking requests are being sent.
3. Trigger a page view, click, form change, or search event to test the integration.

== Frequently Asked Questions ==

= Does this plugin require a Tag ID? =

Yes. The front-end tracking script only loads when **Enable Tracking** is enabled and a valid Tag ID is configured.

By design, the **Enable Tracking** setting is the explicit admin opt-in mechanism.

= Where do I get my Tag ID? =

Your Tag ID is provided by Markopolo when you create an account. It's a unique UUID that identifies your site. Contact Markopolo support if you need help finding it.

= Where are events sent? =

Events are sent to Markopolo endpoints used by the plugin:

1. Browser event endpoint: `https://mtag.markopolo.ai/mark`
2. Settings webhook endpoint: `https://api-alpha.markopolo.ai/v1/integrations/wordpress/webhook`

= Does this store personal data? =

It can store and transmit personal data such as name, email, phone, and search terms when those values are present in forms or interactions.

= Is this compatible with all themes? =

The tracking script is designed to work with standard WordPress front-end pages and common form elements.

= Will this slow down my site? =

The plugin sends events asynchronously and only loads its tracking script when it is needed.

= How do I test it? =

1. Open your site in a browser.
2. Open DevTools and go to the Network tab.
3. Trigger a page view, click, or form interaction.
4. Look for the outgoing tracking request to the Markopolo endpoint.

= Does the plugin send data on Tag ID changes or uninstall? =

Yes, with conditions. The plugin sends webhook events for Tag ID set/update/removal and plugin uninstall only after admin opt-in via **Enable Tracking**. Uninstall webhooks are only sent when tracking is enabled and a Tag ID is configured.

== Screenshots ==

1. Settings page for entering the Tag ID.
2. Example tracking request in browser DevTools.
3. Event payload with page metadata.
4. Form interaction payload with captured form fields.

== Changelog ==

= 1.0.1 =
* Rebranded plugin name from Markopolo Tracker to Markopolo AI.

= 1.0.0 =
* Initial release
* Page view tracking
* Click tracking
* Form interaction tracking
* Search tracking
* Session and visitor identifier support
* Settings page for Tag ID configuration

== Upgrade Notice ==

= 1.0.1 =
Branding update: plugin name changed to Markopolo AI.

= 1.0.0 =
Initial release of Markopolo AI.

== Support ==

For support, contact the Markopolo team through your account or via email support@markopolo.ai.
