=== Ultrafan ===
Contributors: @ultrafan
Tags: affiliate, tracking, conversion, woocommerce, marketing
Requires at least: 6.2
Tested up to: 7.0
Requires PHP: 7.4
Stable tag: 1.30.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Connects WooCommerce to the Ultrafan affiliate network - handles clicks, conversion pixels, COD payments, refunds, and sends reconciliation reports.

== Description ==

**Ultrafan** is the official WooCommerce integration for the [Ultrafan](https://ultrafan.world) affiliate network. It automates the full affiliate lifecycle inside your WooCommerce store without requiring any JavaScript snippets or external tag managers.

= Key Features =

* **Click tracking** — Captures `transaction_id`, `network_id`, `offer_id`, and all UTM parameters from affiliate landing URLs. Parameters are stored in first-party cookies so attribution survives the entire checkout journey.
* **Conversion pixel** — Fires `POST /conversion` to the Ultrafan server the moment an order is placed, with full order details (amount, currency, items, payment method).
* **COD settlement** — When a cash-on-delivery order's invoice is marked paid, the plugin fires `POST /conversion/settle` automatically.
* **Refund & cancellation webhooks** — On credit-memo creation or order cancellation the plugin notifies Ultrafan in real time (`POST /conversion/refund`).
* **Periodic reconciliation** — A configurable cron job (default: Monday 02:00) batches paid orders and refunds into a signed `POST /reconcile` report. A **Run Now** button in WP Admin lets you send ad-hoc reports for any date range.
* **Admin transparency** — A dedicated **Ultrafan → Reconciliation** menu in WP Admin shows every reconciliation run with status, record count, HTTP response, and the exact date range covered.
* **HPOS compatible** — Fully compatible with WooCommerce High-Performance Order Storage.

= External Service =

This plugin communicates with the **Ultrafan affiliate API** operated by NewPlay Technology:

* **Service URL:** `https://affiliate.newplay.tech` (production) / `https://test-affiliate.newplay.tech` (test&development)
* **Endpoints used:** `/conversion`, `/conversion/settle`, `/conversion/refund`, `/reconcile`
* **Data sent:** affiliate transaction ID, order ID, order total, currency, payment method (normalised to a short code), base64-encoded item list, delivery cost, subtotal, and discount amount.
* **Privacy policy:** https://www.ultrafan.world/privacy-policy
* **Terms of service:** https://www.ultrafan.world/terms-conditions

No personal data (name, email, address) is included in any outbound request. The plugin uses a pre-shared API key (stored in WP options) to authenticate with the server.

== Installation ==

**From the WordPress Plugin Directory (recommended):**

1. Go to **Plugins → Add New** in your WP Admin.
2. Search for "Ultrafan".
3. Click **Install Now** then **Activate**.
4. Go to **WooCommerce → Settings → Integration → Ultrafan Affiliate** to enter your credentials.

**Manual upload:**

1. Download the plugin zip from the WordPress Plugin Directory.
2. Go to **Plugins → Add New → Upload Plugin** and upload the zip.
3. Activate and configure as above.

**Configuration:**

After activation, navigate to **WooCommerce → Settings → Integration → Ultrafan Affiliate**:

| Setting                | Description                                                                                              |
| ---------------------- | -------------------------------------------------------------------------------------------------------- |
| Merchant ID            | Your `shop_id` from the Ultrafan server. Sent as `X-Merchant-ID` on reconciliation and settlement calls. |
| Merchant Name          | Display name included in reconciliation headers.                                                         |
| API Key                | Per-merchant secret provided by NewPlay Technology. Stored encrypted.                                    |
| Enable Reconciliation  | Enables or disables the automatic reconciliation cron job.                                               |
| Cron Schedule          | Standard cron expression — default `0 2 * * 1` (Monday 02:00).                                           |

== Frequently Asked Questions ==

= What affiliate network does this plugin support? =

This plugin is built exclusively for the **Ultrafan** affiliate network operated by NewPlay Technology. It is not a generic affiliate plugin.
The support is via email help@ultrafan.world.

= What data is sent to the Ultrafan server? =

Each conversion call includes: an anonymised affiliate transaction ID, the WooCommerce order ID, grand total, currency, normalised payment method code, base64-encoded item list (SKU, name, price, quantity), delivery cost, subtotal, and discount amount. No customer name, email, or shipping address is ever transmitted.

= Is the plugin compatible with WooCommerce HPOS? =

Yes. The plugin explicitly declares compatibility with WooCommerce High-Performance Order Storage (custom order tables).

= Can I trigger a reconciliation report manually? =

Yes. Go to **WooCommerce → Ultrafan → Reconciliation**, choose a date range, and click **Run Now**.

= What payment method codes are sent? =

| Code  | Meaning                                                 |
| ----- | ------------------------------------------------------- |
| `COD` | Cash on delivery / deferred payment                     |
| `WAL` | PayPal, Apple Pay, Google Pay, or other digital wallets |
| `CRC` | Credit/debit card (Stripe, Braintree, Adyen, etc.)      |
| `DEF` | Bank transfer                                           |
| `OTR` | Any unrecognised gateway                                |

= What happens if the Ultrafan server is unreachable? =

The plugin retries failed conversion and settlement calls. Reconciliation failures are logged in the **Reconciliation Runs** admin screen and will be retried on the next cron run (unreconciled records are never lost).

= Does this plugin set cookies? =

Yes. First-party cookies (`ultrafan_transaction_id`, `ultrafan_network_id`, UTM cookies) are set for 5–30 days when a visitor lands via an affiliate link. A long-lived `affiliate_ultrafan` cookie (365 days) is also set for returning-customer attribution. All cookies use `SameSite=Lax; Secure` attributes.

== Screenshots ==

1. **Settings page** — Configure Merchant ID, API Key, cron schedule, and endpoint URLs under WooCommerce → Settings → Integration.
2. **Reconciliation Runs** — History of every reconciliation attempt with status, record count, HTTP response, and date range.
3. **Order meta** — Affiliate tracking data (transaction ID, network, UTM params, conversion/settlement status) visible on the WooCommerce order detail page.

== Cookies & localStorage ==

Cookies and localStorage parameters are GDPR compliant, as they do not contain and client data, and they are in favour of the client.
The parameters are:
- transaction_id, user id (utm_conten t), conversion id (utm_term) - ultrafan affiliate parameters
- utm_source="ultrafan", utm_medium="affiliate", utm_campaign=... (not defined, future use) - the merchant to see, that this purchase is from affiliate
- network_id = whether it is prod/stage/test/dev

== Changelog ==

= 1.30.1 =
* Added check for network id to avoid invalid captures

= 1.30.0 =
* Initial public release (aligned with other stores).
* Click tracking with first-party cookies (`transaction_id`, `network_id`, UTMs).
* Conversion webhook: `POST /conversion` with JSON body and API key authentication.
* COD settlement webhook: `POST /conversion/settle`.
* Refund and cancellation webhooks: `POST /conversion/refund`.
* Reconciliation cron: `POST /reconcile` with per-merchant API key, refund records included.
* Admin UI: Reconciliation Runs log with Run Now button.
* HPOS compatibility declaration.
* All cookies use `SameSite=Lax; Secure`.

== Upgrade Notice ==

= 1.30.0 =
Initial release — not uploaded in WordPress Plugin Directory.
