دستاویزات

براؤزر میں ایک اسکرپٹ، سرور سے ایک API کال۔ لائیو ہونے کے لیے جو کچھ چاہیے، ایک ہی پیج پر۔

کوئیک اسٹارٹ

براؤزر کے لیے آپ کو اپنی پبلک کی (pk_...) اور سرور کے لیے اپنی سیکرٹ کی (sk_...) درکار ہے۔ دونوں ڈیش بورڈ میں Sites and keys کے تحت موجود ہیں۔

1. اسکرپٹ لگائیں

یہ ٹیگ ان پیجز پر لگائیں جہاں صارفین سائن اپ، لاگ اِن، آفرز پر کلک یا کیش آؤٹ کی درخواست کرتے ہیں۔ یہ خود کو یہاں سے initialise کرتا ہے: data-key

<script src="https://cashoutguard.com/v1/agent.js" data-key="pk_live_YOUR_PUBLIC_KEY" async></script>

2. collect کریں اور request_id اپنے سرور کو بھیجیں

اہم لمحے پر ایونٹ کے نام کے ساتھ collect() کال کریں۔ یہ اس ویلیو پر resolve ہوتا ہے: { request_id, visitor_id }

const { request_id } = await CashoutGuard.collect({ event: 'cashout' });

collect() کبھی reject نہیں ہوتا۔ ناکامی کی صورت میں (بلاک، آف لائن، ٹائم آؤٹ) یہ request_id: null اور ایک ایرر اسٹرنگ کے ساتھ resolve ہوتا ہے۔ فارم پھر بھی بھیجیں اور فیصلہ اپنے سرور پر چھوڑ دیں۔

3. اپنے سرور سے فیصلہ مانگیں

ایونٹ کو /v1/evaluate پر POST کریں، اور اپنی سیکرٹ کی اس ہیڈر میں رکھیں: Authorization: Bearer sk_live_...

سیکرٹ کی کبھی بھی براؤزر کوڈ یا موبائل ایپ میں نہ رکھیں۔ صرف آپ کا سرور ہی /v1/evaluate کال کرے۔

Evaluate ریکوئسٹ

POST https://cashoutguard.com/v1/evaluate ایک اکاؤنٹ کے ایک ایونٹ کو اسکور کرتا ہے، اسے اس کی ڈیوائس، نیٹ ورک اور پے آؤٹ ایڈریس سے جوڑتا ہے، اور فیصلہ واپس کرتا ہے۔ JSON بھیجیں۔

ریسپانس

ریسپانس کی ساخت ہمیشہ ایک جیسی ہوتی ہے۔ جو فیلڈز لاگو نہ ہوں وہ null ہوتی ہیں۔

• score 0 سے 100 تک ہوتا ہے۔ وجوہات اس طرح جوڑی جاتی ہیں کہ کئی درمیانے سگنلز مل کر بڑھتے ہیں مگر 100 سے آگے نہیں جاتے۔
• reasons ہر فعال سگنل کی فہرست دیتا ہے، سب سے مضبوط پہلے، اس کے وزن، تفصیلات اور براہِ راست دکھانے کے قابل سادہ انگریزی لیبل کے ساتھ۔
• device.confidence بتاتا ہے کہ ڈیوائس کتنی منفرد لگتی ہے۔ فنگر پرنٹس اسپوف ہو سکتے ہیں، اس لیے ہم کبھی سو فیصد یقین کا دعویٰ نہیں کرتے۔
• linked_accounts ان دوسرے اکاؤنٹس کی فہرست دیتا ہے جو اس اکاؤنٹ کے ساتھ ڈیوائس، پے آؤٹ ایڈریس یا ای میل شیئر کرتے ہیں۔
• cashout صرف cashout ایونٹس کے لیے سیٹ ہوتا ہے اور آپ کی ریویو قطار میں اسٹیٹس بتاتا ہے۔

فیصلے اور ایکشنز

decision پر نہیں، action فیلڈ پر عمل کریں۔ نیچے دی گئی حدیں ڈیفالٹ ہیں اور ڈیش بورڈ میں ہر سائٹ کے لیے بدلی جا سکتی ہیں۔

شیڈو موڈ میں action ہمیشہ allow ہوتا ہے، اس لیے enforce سے پہلے یہی کوڈ بے فکری سے لائیو کیا جا سکتا ہے۔ enforce پر جانے سے آپ کے کوڈ میں کچھ نہیں بدلتا۔

ایونٹ کی اقسام

جو ایونٹس آپ کے پاس ہیں وہ بھیجیں۔ سائن اپ اور کیش آؤٹ سب سے اہم ہیں؛ کنورژنز سے آفر کی رفتار کے چیکس چلتے ہیں۔

آفر والز اور پوسٹ بیکس

آفر وال کنورژنز پوسٹ بیک کے ذریعے سرور سے سرور، بغیر براؤزر کے آتی ہیں۔ CashoutGuard ہر کنورژن کو اس کلک سے جوڑتا ہے جس سے وہ شروع ہوئی، اس لیے اس کا اسکور اسی کلک کی ڈیوائس اور نیٹ ورک سے بنتا ہے۔

1. جب صارف کوئی آفر کھولے

براؤزر میں کلیکٹ کریں اور آفر اور اپنی کلک ID کے ساتھ offer_click بھیجیں۔

2. جب پوسٹ بیک آئے

اپنے پوسٹ بیک ہینڈلر سے اسی account_id اور click_id کے ساتھ conversion بھیجیں۔ request_id کی ضرورت نہیں۔ اگر آفر وال صارف کا IP دے تو وہ بھی بھیجیں۔

کنورژنز کی جانچ ہوتی ہے: آفر کے لیے بہت تیزی سے مکمل ہونا، بغیر کلک کے کنورژن، کلک اور کنورژن مختلف ممالک سے، اکاؤنٹ کے عام دن سے کہیں زیادہ کمائی، اور ڈپلیکیٹ ٹرانزیکشن IDs۔

آفر وال نیٹ ورکس

اگر آپ کئی پبلشرز والا نیٹ ورک چلاتے ہیں تو پبلشر سمیت اکاؤنٹ IDs بھیجیں اور Sites میں "آفر وال نیٹ ورک موڈ" آن کریں۔ پھر اکاؤنٹس صرف ایک ہی پبلشر کے اندر جڑتے ہیں، کیونکہ ایک شخص کا کئی پبلشرز کی سائٹس استعمال کرنا معمول ہے۔ فارمیٹ: publisher_id:user_id

آفر کیٹلاگ

POST /v1/offers آپ کی آفرز کے نام بھیجتا ہے (ہر کال میں 1,000 تک)۔ پرانے اور نئے ایونٹس اصل نام دکھائیں گے، چاہے ان میں صرف ID ہو۔

ریزن کوڈز

یہ کوڈز reasons[].code میں آتے ہیں۔ متن اپنے ماڈریٹرز کو دکھائیں؛ اپنی لاجک میں کوڈ استعمال کریں۔

وزن noisy-OR سے جوڑے جاتے ہیں: score = 100 x (1 - product of (1 - weight/100))۔ 40 کے دو سگنلز 64 دیتے ہیں، 80 نہیں۔ بلاک لسٹ میچ ہمیشہ 100 دیتا ہے۔

Webhooks

ڈیش بورڈ میں ویب ہک URL سیٹ کریں۔ block اسکور والے ہر ایونٹ (event.blocked)، کسی اکاؤنٹ کے block ہونے (account.blocked) اور آپ کی ٹیم کے کیش آؤٹ فیصلے (cashout.decided) پر ہم POST بھیجتے ہیں۔ جو ٹائپ استعمال نہ کریں انہیں نظر انداز کریں۔

ہر ریکوئسٹ آپ کے webhook سیکرٹ سے سائن ہوتی ہے۔ raw باڈی کا hex HMAC-SHA256 اس ہیڈر میں ہوتا ہے: X-CashoutGuard-Signature

کسی بھی 2xx اسٹیٹس کے ساتھ جواب دیں۔ ناکام ڈیلیوریز 5 بار تک دوبارہ بھیجی جاتی ہیں: 10 سیکنڈ، 1 منٹ، 5 منٹ اور 15 منٹ بعد۔

اکاؤنٹ اسٹیٹس

GET /v1/accounts/{account_id} کوئی ایونٹ بنائے بغیر اکاؤنٹ کا موجودہ رسک ویو واپس کرتا ہے۔

POST /v1/accounts/{account_id}/status آپ کے اپنے ماڈریشن ٹولز کو اکاؤنٹ کا اسٹیٹس بدلنے دیتا ہے۔

• active: معمول کی اسکورنگ۔
• allowlisted: اسکورز review کی حد سے نیچے محدود رہتے ہیں۔ بھروسہ مند صارفین اور اسٹاف کے لیے۔
• blocked: ہر ایونٹ اسکور 100 کے ساتھ block واپس کرتا ہے۔

ریورسلز اور درستگی

POST /v1/outcomes بتاتا ہے کہ اسکور کے بعد کنورژنز کا کیا ہوا: آفر وال یا ایڈورٹائزر نے ریورس کیا (chargeback) یا درست قرار دیا۔ ہم آپ کے ids ملا کر Accuracy صفحے پر آپ کی ٹریفک پر انجن ناپتے ہیں۔

بغیر کوڈ کے: Accuracy صفحے پر اپنی آفر والز کی ماہانہ ریورسل فائل (CSV یا Excel) اپ لوڈ کریں۔ id کالم ہم خود ڈھونڈ لیتے ہیں۔

PHP، Node.js، Python، Android

کسی SDK کی ضرورت نہیں۔ مختصر ٹائم آؤٹ کے ساتھ ایک سادہ HTTP کال کافی ہے۔ کیش آؤٹ کی مکمل مثال:

• cashoutguard.php: PHP 7.4+، ایک فائل، Composer نہیں۔ بس require کریں۔
• composer require cashoutguard/cashoutguard-php: وہی PHP کلائنٹ README کے ساتھ، آپ کے vendor فولڈر کے لیے۔
• npm install @cashoutguard/node: Node 18+، TypeScript ٹائپس کے ساتھ۔
• cashoutguard-wordpress.zip: WordPress پلگ اِن: ہر صفحے پر براؤزر اسکرپٹ، سائن اپ اور لاگ اِن کا اسکور، اور کیش آؤٹ، آفر وال کنورژنز اور ریورسلز کے لیے ہُکس۔

ایررز اور حدود

Fail open: اگر کال ٹائم آؤٹ ہو یا ایرر آئے تو ایکشن کی اجازت دیں اور اسے لاگ کریں۔ ہماری سروس بند ہونے سے آپ کے صارفین کبھی نہ رکیں۔