# Confirmed Meta Purchase — বাংলা নির্দেশনা

## কীভাবে কাজ করবে

কাস্টমার অর্ডার দিলে Purchase যাবে না। অর্ডার পেজের **Order actions → Confirm & Send Meta Purchase** চালালে CAPI দিয়ে আপনার একই Meta Pixel/Dataset-এ Purchase যাবে। এই অ্যাকশন অর্ডারের payment/fulfillment status পরিবর্তন করে না। তাই সাধারণভাবে এই অ্যাকশন ব্যবহার করুন।

বিকল্পভাবে, অ্যাডমিন ম্যানুয়ালি **Confirmed (Meta)** স্ট্যাটাস সিলেক্ট করে Update করলেও Purchase queue হবে। এটি আলাদা custom status; আপনার courier, stock, email বা fulfillment integration এই status চিনতে না-ও পারে। এটি নিজে payment complete বা stock reduction চালায় না।

স্বয়ংক্রিয় Processing/Completed status কোনো Purchase চালু করে না। এই নিয়ম সব payment method-এর অর্ডারে প্রযোজ্য, শুধু COD নয়।

**Browser Purchase পাঠানো হয় না।** পরে Confirm করার সময় কাস্টমারের browser খোলা থাকা নিশ্চিত নয়; তাই server CAPI ব্যবহার করা হয়। PageView, ViewContent, AddToCart, InitiateCheckout আগের মতো PixelYourSite থেকে চলবে। CAPI Purchase একই Dataset-এ পৌঁছাবে।

## ইনস্টলেশন

1. প্রথমে staging/test সাইটে পরীক্ষা করুন। WordPress → Plugins → Add New → Upload Plugin থেকে `confirmed-meta-purchase.zip` আপলোড করে Activate করুন। WooCommerce সক্রিয় থাকতে হবে।
2. PixelYourSite-এর WooCommerce settings-এ **Meta/Facebook Purchase** বন্ধ করুন। অন্য events বন্ধ করবেন না। Meta Events Setup Tool, GTM, theme code অথবা অন্য plugin-এ Purchase চালু থাকলে সেগুলোও বন্ধ করুন। এই plugin অন্য plugin-এর কোড পরিবর্তন করে না।
3. পুরোনো page cache, CDN এবং optimization cache clear করুন। পুরোনো cached browser JavaScript থেকে Purchase হয়ে যেতে পারে। আগে queue হওয়া PixelYourSite server events শেষ না হওয়া পর্যন্ত migration শেষ হয়েছে ধরে নেবেন না।
4. **WooCommerce → Confirmed Meta Purchase** খুলুন। PixelYourSite-এ ব্যবহৃত একই Pixel/Dataset ID এবং Meta CAPI access token দিন। Token এখানে বা public chat-এ পাঠানোর দরকার নেই; নিজের WordPress settings-এ বসান।
5. Graph API version-এর default `v23.0`। Meta আপনার integration-এর জন্য অন্য supported version নির্ধারণ করলে সেটি দিন। Test Events থেকে পাওয়া test code দিয়ে প্রথমে পরীক্ষা করুন।
6. Consent নির্বাচন করুন। Default **WP Consent API**: API পাওয়া না গেলে বা marketing permission না থাকলে Purchase বন্ধ থাকবে। আপনার consent plugin-কে API-এর সঙ্গে যুক্ত থাকতে হবে। **Merchant-managed permission** শুধু তখনই ব্যবহার করুন যখন checkout-এ আপনার নিজের permission ব্যবস্থা আছে। এই plugin consent banner তৈরি করে না।
7. Setup confirmation এবং Enable checkbox নির্বাচন করে Save করুন। উপরে **ENABLED** দেখাচ্ছে নিশ্চিত করুন। Required fields অসম্পূর্ণ থাকলে plugin disabled থাকবে এবং PYS event suppression চালু হবে না।

## দৈনন্দিন ব্যবহার

1. কাস্টমারের সঙ্গে কথা বলে অর্ডার নিশ্চিত করুন।
2. WooCommerce order edit page-এ Order actions থেকে **Confirm & Send Meta Purchase** চালান।
3. Order notes-এ queued এবং পরে **Purchase accepted by Meta** দেখুন। এই acceptance মানে Meta event গ্রহণ করেছে; বিজ্ঞাপনের attribution বা Ads Manager reporting নিশ্চিত হয়েছে এমন নয়।
4. **WooCommerce → Status → Scheduled Actions**-এ `cmp_send_purchase` search করে queue দেখুন। Hosting-এ WordPress cron/Action Scheduler চলতে হবে; delivery কয়েক মিনিট পরে হতে পারে।
5. Error হলে Order notes-এর HTTP/Meta error code দেখে token/settings ঠিক করুন; তারপর **Retry Meta Purchase (same event)** ব্যবহার করুন।

## ডুপ্লিকেট ও cancellation

- প্রতিটি confirmation event-এর ID, timestamp, value, currency এবং destination স্থির করে রাখা হয়। Retry-তে এগুলো বদলায় না। সফল delivery-র marker ও database lock parallel/repeated send প্রতিরোধ করে।
- Transient network/429/server error-এ সীমিত retry আছে। সব মিলিয়ে সর্বোচ্চ ৬টি delivery attempt, confirmation থেকে ২৪ ঘণ্টার মধ্যে। এর বাইরে manual retry-ও নতুন event বানাবে না। বাহ্যিক API timeout হলে প্রকৃত delivery অবস্থা অস্পষ্ট হতে পারে; তাই শতভাগ network-level exactly-once নিশ্চয়তা দাবি করা হয় না।
- Cancelled, Failed, Refunded বা draft order confirm করা যায় না। Queue চলার আগেই status অনুপযুক্ত হলে event বন্ধ থাকে। Pending/On-hold-এ ফেরত দিলে আগের confirmation revoke হয়; আবার নিশ্চিত করতে হলে অ্যাকশন চালান।
- Meta-তে event পৌঁছানোর পরে Cancel/Refund করলে সেই Purchase মুছে যায় না। Send ও cancel একই মুহূর্তে হলে ইতোমধ্যে পাঠানো request ফিরিয়ে নেওয়া যায় না।
- Enable করার আগের অর্ডার import করা হয় না, কারণ আগের plugin থেকে এগুলোর Purchase হয়ে থাকতে পারে। Admin/API-তে তৈরি অর্ডারও স্বয়ংক্রিয়ভাবে eligible নয়; classic বা block checkout-এর capture প্রয়োজন।
- Test mode-এ পাঠানো order production-এ replay করা হয় না। Test code মুছে production test-এর জন্য নতুন order করুন। Confirm করার পরে Pixel ID বা test code বদলালে queued retry বন্ধ থাকে; original configuration ফিরিয়ে দিতে হবে।

## Live করার আগে যাচাই

1. Test code দিয়ে নতুন COD order: Purchase থাকবে না; অন্য Pixel events থাকবে।
2. Confirm করুন: Meta Test Events-এ একটি **Server Purchase** ও সঠিক amount/currency দেখুন।
3. আবার Confirm/Retry, thank-you page refresh: নতুন Purchase হবে না।
4. নতুন unconfirmed order Cancel করুন: Purchase হবে না।
5. Consent deny করে নতুন order: Confirm করলেও Purchase হবে না।
6. Classic/Block checkout যেটি ব্যবহার করেন সেটি, আপনার cache/CMP/courier integration এবং HPOS configuration পরীক্ষা করুন।
7. Test code মুছে Save করুন। নতুন ছোট production order দিয়ে tracking যাচাই করুন।

## গোপনীয়তা ও configuration

Email/phone SHA-256 hash করে পাঠানো হয়; Bangladesh-এর 01 দিয়ে শুরু ১১ সংখ্যার phone-এ 88 যোগ হয়। অন্য দেশের phone international prefix দিয়ে দিন। Customer-এর order IP/user-agent এবং checkout-এ consent থাকা অবস্থার `_fbp`/`_fbc` পাঠানো হয়; admin browser-এর তথ্য ব্যবহার হয় না। Ad attribution cookie না থাকলে matching দুর্বল হতে পারে। Value হলো WooCommerce order total, shipping/tax-সহ; product catalog matching এই সংস্করণে নেই।

Database-এ token সংরক্ষিত হলে সেটি encrypted নয়; administrator/database access সুরক্ষিত রাখুন। বিকল্পভাবে `wp-config.php`-এ:

```php
define('CMP_META_ACCESS_TOKEN', 'YOUR_TOKEN');
```

Constant database token-এর চেয়ে অগ্রাধিকার পাবে। Settings page saved token দেখায় না। Order notes-এ token, email/phone বা raw Meta response লেখা হয় না।

Consent integration-এর জন্য developer filter `cmp_marketing_consent($allowed, $order)` checkout-এ ব্যবহার করতে পারেন। পরে consent প্রত্যাহার হলে `cmp_can_send_purchase($allowed, $order)` দিয়ে queued event বন্ধ করুন। Consent withdrawal নিজে এই plugin খুঁজে বের করে না।

এই plugin-এর `_cmp_*` order metadata-তে consent, cookie, event snapshot ও delivery record থাকে। Order deletion/retention policy-এর সঙ্গে এগুলোও পরিচালনা করুন। Plugin deactivate/delete করলে records ইচ্ছাকৃতভাবে রাখা হয়, যাতে reinstall-এ duplicate না হয়। Orders মুছলে WooCommerce সংশ্লিষ্ট order metadata-ও মুছে দেয়।

## যাচাইয়ের সীমা

সংস্করণ 1.0.1-এ PHP 8.3.30, WordPress 7.1.3, WooCommerce 11.2.1 ও MySQL 8.4.3 দিয়ে লোকাল পরীক্ষা করা হয়েছে। ৪৫টি standalone check এবং HPOS/legacy order storage-এ ৩২টি করে integration check পাস করেছে। আসল database, WooCommerce hooks, Action Scheduler retry, WordPress nonce/capability এবং দুই database connection-এর lock পরীক্ষা অন্তর্ভুক্ত। PixelYourSite Free **11.4.3**-এর actual event classes দিয়েও filtering পরীক্ষা হয়েছে।

এই পরীক্ষায় Meta response অনুকরণ করা হয়েছে; বাইরের Meta API-তে কোনো event পাঠানো হয়নি। Browser দিয়ে পূর্ণ checkout, আপনার theme/cache/CMP/courier এবং live Meta delivery এখনও যাচাই করা হয়নি। ১০৯টি check পাস করা সব পরিস্থিতিতে শতভাগ নিশ্চয়তা নয়। Live activation-এর আগে উপরের checklist সম্পন্ন করুন।