PHP
تتبع الفتح والنقر
`emails->getTracking` ومساحة الأسماء `tracking` كلها.
رسالة واحدة
$report = $client->emails->getTracking('msg_3f9a1c07d2b84e6a9c5b1f20'); echo $report['openCount'], ' opens from ', count($report['recipients']), ' recipients', PHP_EOL; foreach ($report['links'] as $link) { echo $link['url'], ' ', $link['clickCount'], PHP_EOL;}الرسالة التي لم تُتتبّع قط ترمي NotFoundException تكون قيمة isNotFound() فيه true، لا تقريرًا فارغًا. فـ «لم نسجّل شيئًا» و«لم يفتحها أحد» جوابان مختلفان ويجب ألا يتقاسما استجابة واحدة. والرسالة المرسلة بمفتاح اختبار لا تُتتبّع أبدًا، فهي ترميه دائمًا.
عبر صندوق البريد
$unopened = $client->tracking->list(opened: false, days: 7, limit: 100);$stats = $client->tracking->getStats(days: 30, offsetMinutes: intdiv((int) date('Z'), 60));$report = $client->tracking->get('msg_3f9a1c07d2b84e6a9c5b1f20');$opens = $client->tracking->listOpens('msg_3f9a1c07d2b84e6a9c5b1f20', includeMachine: true);$clicks = $client->tracking->listClicks('msg_3f9a1c07d2b84e6a9c5b1f20'); echo count($unopened), ' unopened, ', $stats['openRate'], '% opened', PHP_EOL;echo count($opens), ' opens and ', count($clicks), ' clicks on ', $report['id'], PHP_EOL;يعيد list وlistOpens وlistClicks صفحة OpenEmail\Result\Page واحدة، ويمر listAll وiterate وlistAllOpens وiterateOpens وlistAllClicks وiterateClicks على كل الصفحات نيابةً عنك. ويأخذ get وlistOpens وlistClicks إما معرّف الإرسال msg_… وإما معرّف سجل التتبّع نفسه tmsg_….
مساحة أسماء مستقلة لا توابع على emails، والسبب هو التغطية: فـ emails يسرد سجلات الإرسال، وهي لا توجد إلا للبريد الذي عالجته هذه الواجهة. والمحرِّر وأدوات MCP والمساعد جميعها ترسل دون سجل، فالتقرير المبني على emails سيكون تقريرًا عن حركة API الخاصة بك لا عن صندوق البريد.
قراءة الأرقام بأمانة
| الزوج | ما الذي يعنيه |
|---|---|
| opens وclicks | ما طُبّق: أي ما إذا كانت الرسالة قد خرجت ببكسل أو بروابط مُعاد كتابتها. |
| opened وclicked | ما الذي حدث. |
| openCount | الزيارات المحتسَبة. تُستبعَد أدوات الفحص ووكلاء الخصوصية. |
| openCountRaw | كل زيارة. الاستشهاد بهذا الرقم كمقياس للتفاعل هو ما يجعل معدل الفتح يتجاوز 100%. |
| attributable | ما إذا كان بالإمكان أصلًا نسب عملية قراءة إلى مستلم بعينه. |
النسب الواردة من tracking->getStats محسوبة على الرسائل المتتبَّعة، لا على كل ما أُرسل. ولولا ذلك لبدا صندوق بريد يتتبّع رسالة واحدة من كل عشر وكأنه انهار. وopenRate وclickRate نسب مئوية مقرّبة إلى منزلة عشرية واحدة، مثل 42.5، لا كسور بين 0 و1.
المعاملات: tracking->list
openedbool- تختار القيمة `true` الرسائل التي سُجّلت لها عملية فتح محتسَبة واحدة على الأقل، وتختار `false` الرسائل المتتبَّعة التي لم تُسجَّل لها أي عملية. ولا يُعدّ أيٌّ منهما قيمة افتراضية، كما أن `false` لا تعني قط البريد غير المتتبَّع، فهو لا يظهر في هذه القائمة إطلاقًا.
clickedbool- المرشّح نفسه لكن للنقرات المحتسَبة، ويُطبَّق باستقلال عن `opened`. ويمكن تمرير كليهما معًا، وعندئذٍ يجب أن تستوفي الرسائل الشرطين معًا.
daysint- عدد الأيام التي يُنظر فيها إلى الوراء اعتبارًا من الآن، من 1 إلى 365 وقيمته الافتراضية 30، وأي قيمة خارج هذا المدى تعطي 422. تُقاس النافذة بوقت إنشاء سجل التتبّع، ولا تُدرج إلا السجلات التي خرج إرسالها فعليًا.
minutesint- النافذة بالدقائق بدلًا من ذلك، من 1 إلى 527040، وتغلب على `days` حين يُضبط الاثنان. والنافذة الأقصر من يوم تحتاج إلى `grain` أدق.
grainstring- `minute` أو `hour` أو `day`، والافتراضي `day`. لا يفعل سوى تقريب بداية النافذة إلى الأدنى، كي تطابق هذه القائمة `getStats` المقروء بالدقة نفسها، ولا يغيّر شيئًا في شكل الاستجابة.
limitint- عدد التقارير في الصفحة، من 1 إلى 200 وقيمته الافتراضية 50، من الأحدث إلى الأقدم. أعد `nextCursor` الخاص بالصفحة بوصفه `cursor:`، مع المرشِّحات نفسها، للصفحة التالية، أو دع `listAll` و`iterate` يمرّان على النافذة كلها.
cursorstring- `nextCursor` من الصفحة السابقة، وهو معرّف `tmsg_`.
apiKeystring- يسرد بهذا المفتاح بدل مفتاح العميل.
الاستجابة: تقرير التتبّع
يعيد emails->getTracking وtracking->get تقريرًا واحدًا في صورة مصفوفة مفاتيحها بصيغة camelCase، ويعيد tracking->list صفحة منها.
objectstring- دائمًا `tracking` على تقرير جُلب بذاته، عبر `tracking->get` أو `tracking->list` أو `emails->getTracking`. والتقرير نفسه حين يأتي متداخلًا بوصفه `tracking` على رسالة من `emails->get` يصل دون هذا المفتاح، لأنه هناك جزء من تلك الرسالة لا شيء جُلب بذاته.
idstring- معرّف سجل التتبّع نفسه، `tmsg_…`. وهو ما يعتمد عليه `listOpens` و`listClicks` كمفتاح، والمعرّف `msg_…` الممرَّر إليهما يُبحث عنه أولًا على هذا الأساس.
sendIdstring or null- عملية الإرسال `msg_…` التي يرتبط بها هذا التقرير، وnull حيث لم يُكتب أي سجل إرسال. فالمحرِّر و`sendEmail` في MCP والمساعد جميعها ترسل دون سجل. والتتبّع يشمل صندوق البريد، لا حركة API وحدها.
threadIdstring or null- يُملأ بعد الإرسال كي تتمكن واجهة القراءة من العثور على الرسالة مجددًا، وقيمته null حيث لم يُبلِّغ المشغّل بشيء. وهو ليس حاملًا للبنية: السجل الذي يحمله بقيمة null يظل محتسبًا.
messageIdstring or null- معرّف Message-ID وفق RFC 5322، لا معرّفنا نحن. ويُملأ هو أيضًا بعد الإرسال، وقيمته null حيث لم يُعِد النقل شيئًا يملؤه به.
subjectstring or null- الموضوع كما كان وقت الإرسال. null على رسالة سُجّلت دون موضوع.
fromstring- عنوان الإرسال، منسوخًا على السجل بدل ضمّه من عملية الإرسال. فالتقارير تُقرأ بعد وقت طويل، وعنوان صُحّح أو أُزيل منذ ذلك الحين كان سيعيد كتابة التاريخ لولا ذلك.
sourcestring- الواجهة التي أرسلتها: `composer` أو `api` أو `mcp` أو `ai` أو `queue`. وقد تظهر واجهة لا تسمّيها هذه الحزمة بعد، فعامل القيمة المجهولة كمعلومة لا كخطأ.
sentAtstring or null- متى انطلقت الرسالة، كلحظة ISO 8601. null على سجل لم يكتمل إرساله قط. ويستبعد `tracking->list` هذه السجلات، أما `get` فلا.
opensbool- ما إذا كانت بكسل قد طُبِّقت على هذه الرسالة. هذا ما جرى فعلًا، لا ما يقوله إعداد الحساب الآن.
clicksbool- ما إذا كانت روابط هذه الرسالة قد أُعيدت كتابتها. false حين لا يحمل المتن روابط، لأنه لم يتغيّر شيء عندئذ، وسجل يدّعي خلاف ذلك لا يمكن التوفيق بينه وبين البايتات.
openedbool- ما إذا كانت قد سُجّلت أي عملية فتح محتسَبة عبر النسخ. اقرأها مقابل `opens`: فغياب البيانات لأنه لم يُجمع منها شيء حقيقةٌ مختلفة عن ألا يكون أحد قد قرأ الرسالة.
clickedbool- ما إذا كانت قد سُجّلت أي نقرة محتسَبة. وهي دليل أقوى من عملية الفتح، لأن حجب الصور أكثر شيوعًا بكثير من ترك الروابط دون اتّباع.
attributablebool- ما إذا كان بالإمكان نسب كل عملية قراءة هنا إلى مستلم بعينه. تصبح `false` في اللحظة التي تُظهر فيها نسخة غير منسوبة نشاطًا محتسَبًا، وهي حالة تعدّد المستلمين حيث يذهب متن واحد إلى القائمة كلها برمز واحد، فتحقّق منها قبل أن تكتب «لم يفتح Bob هذه الرسالة».
openCountint- عمليات الفتح التي يُرجَّح أن إنسانًا هو من تسبّب بها، مجموعةً عبر النسخ. تُستبعَد زيارات الآلات، وتُدمج التكرارات خلال ثلاثين ثانية في واحدة، ولذلك فهذا هو الرقم الذي يُعرض على القارئ.
clickCountint- النقرات المحتسَبة، مجموعةً عبر النسخ. وتُزال التكرارات لكل رابط لا لكل رسالة، فاتّباع رابطين مختلفين بفارق ثوانٍ يُعدّ نقرتين.
openCountRawint- كل جلب للبكسل، بما في ذلك أدوات الفحص ووكلاء الخصوصية. و`openCountRaw` ناقص `openCount` هو عدد ما نُحّي جانبًا، أي عمليات الجلب الآلية والتكرارات خلال ثلاثين ثانية معًا، وهو الدليل الوحيد المتاح على أن الترشيح جرى أصلًا.
clickCountRawint- كل زيارة لرابط أُعيدت كتابته، بما في ذلك زيارات الآلات والتكرارات.
firstOpenAtstring or null- أول فتح محسوب عبر النسخ، وnull ما دام لا يوجد أي منها. والزيارات الآلية لا تحرّكه أبدًا.
lastOpenAtstring or null- أحدث فتح محتسب عبر النسخ، وقيمته null ما دام لا يوجد أي فتح.
firstClickAtstring or null- أقدم نقرة محتسبة عبر النسخ، وقيمتها null ما دام لا توجد أي نقرة.
lastClickAtstring or null- أحدث نقرة محتسبة عبر النسخ، وقيمتها null ما دام لا توجد أي نقرة.
recipientsarray- مدخل واحد لكل نسخة متتبَّعة: مدخل لكل مستلم حيث يسمح النقل باختلاف البايتات من شخص لآخر، ومدخل واحد مشترك حيث لا يسمح بذلك. ويُسقَط المدخل المشترك ما لم تصله فعليًا أي إصابة، فلا يجلس صف “شخص ما” الذي لم يُمس قط إلى جانب أسماء حقيقية.
linksarray- كل رابط أُعيدت كتابته في هذه الرسالة، مرتَّبًا بحسب موضعه في المتن. وتكون فارغة حيث لم يُعَد كتابة أي رابط: رسالة أُرسلت و`clicks` مُعطّلة، أو رسالة لم يحمل متنها أي رابط أصلًا.
كل عنصر في recipients
emailstring or null- الجهة التي ذهبت إليها هذه النسخة، بأحرف صغيرة وكما كانت وقت الإرسال. تكون null تمامًا عندما تكون `attributed` بقيمة false.
kindstring or null- `to` أو `cc` أو `bcc`: الترويسة التي ظهر فيها العنوان، كي يُقرأ التقرير كما قُرئت الرسالة. null على النسخة المشتركة، التي لا تخص عنوانًا بعينه.
attributedbool- ما إذا كان هذا الصف يسمّي شخصًا. اقرأه قبل `email`: القيمة false تعني النسخة المشتركة، وتُدرَج فور وصول أي إصابة إليها، وإسناد اسم إلى تلك الإصابة، حتى في رسالة ذات مستلم واحد، يختلق الحقيقة الوحيدة التي تعجز الآلية عن توفيرها.
openCountint- الفتحات المحتسبة على هذه النسخة وحدها، وفق الاستثناءات نفسها المطبَّقة على إجمالي الرسالة: تُسقَط الزيارات الآلية، وتُدمَج التكرارات خلال ثلاثين ثانية في واحدة.
clickCountint- النقرات المحتسبة على هذه النسخة وحدها، بعد إزالة التكرار لكل رابط لا لكل نسخة.
firstOpenAtstring or null- أقدم فتح محتسب على هذه النسخة، وقيمته null ما دام لا يوجد أي فتح.
lastOpenAtstring or null- أحدث فتح محتسب على هذه النسخة، وقيمته null ما دام لا يوجد أي فتح.
firstClickAtstring or null- أقدم نقرة محتسبة على هذه النسخة، وقيمتها null ما دام لا توجد أي نقرة.
lastClickAtstring or null- أحدث نقرة محتسبة على هذه النسخة، وقيمتها null ما دام لا توجد أي نقرة.
كل عنصر في links
idstring- معرّف الرابط نفسه، `lnk_…`. وهو القيمة التي يسمّيها `linkId` في صف النقرة، فيمكن مطابقة زيارة من `listClicks` بالعنصر المقابل هنا.
urlstring- الوجهة الفعلية للرابط، كما كانت في الرسالة قبل إعادة الكتابة. ويحوّل المُوجِّه المعرّف إلى هذه القيمة ثم يرسل الزائر إليها.
labelstring or null- نص الارتباط كما ظهر في الرسالة، أو null حيث لم يكن للرابط نص، كصورة أو عنوان URL مجرد. وهو موجود كي يقول التقرير «رابط التسعير» بدل اقتباس عنوان URL يحمل ثلاثة معاملات تتبّع، وهو لا يحل محل `url` أبدًا.
clickCountint- الزيارات المحتسبة لهذا الرابط، مجموعةً عبر النسخ. وهي نافذة الثلاثين ثانية نفسها لكل رابط المطبَّقة على `clickCount` في الرسالة.
clickCountRawint- كل زيارة لهذا الرابط، بما فيها الزيارات الآلية والتكرارات.