الجماهير
`audiences->list` و`get` و`create` و`update` و`delete` و`empty` و`growth` و`listContacts` و`addContact` و`addContacts` و`importContacts` و`removeContact` و`removeContacts`.
كل الدوالّ
$everyone = null; foreach ($client->audiences->listAll() as $audience) { if ($audience['builtin'] === 'default') { $everyone = $audience; }} $list = $client->audiences->create([ 'name' => 'Product updates', 'description' => 'Customers who asked to hear about releases',]); $client->contacts->create(['email' => '[email protected]', 'name' => 'Grace Hopper']);$client->audiences->addContact($list['id'], ['email' => '[email protected]']); $bulk = $client->audiences->addContacts($list['id'], ['emails' => ['[email protected]', '[email protected]']]); $imported = $client->audiences->importContacts($list['id'], [ 'contacts' => [['email' => '[email protected]', 'name' => 'Katherine Johnson']],]); $members = $client->audiences->listAllContacts($list['id'], q: 'grace', sort: 'added-newest', limit: 200); $growth = $client->audiences->growth(audienceIds: [$list['id']], days: 30); $client->audiences->update($list['id'], ['name' => 'Release notes']);$client->audiences->removeContact($list['id'], '[email protected]');$client->audiences->removeContacts($list['id'], ['emails' => ['[email protected]']]);$client->audiences->empty($list['id']);$client->audiences->delete($list['id']); echo $everyone['contactCount'] ?? 0, ' contacts in all', PHP_EOL;echo implode(', ', $bulk['missing']), ' ', $imported['created'], ' ', count($members), ' ', $growth['totals']['added'], PHP_EOL;الجمهور قائمة مسمّاة من جهات الاتصال في مساحة العمل هذه. وكل جهة اتصال تكون في الجمهور الافتراضي المدمج منذ لحظة وجودها، وbuiltin هو ما يسمّي ذلك الصف. وما عداه لك أن تنشئه وتملأه وتحذفه. فرّع على builtin لا على الاسم الذي يستطيع أي أحد تغييره.
الاستدعاء على جمهور واحد يأخذ معرّفه كأول وسيط، ويأخذ removeContact العنوان كوسيط ثانٍ. والمرشِّحات والخيارات وسائط مسمّاة بصيغة camelCase (audienceIds: وoffsetMinutes:)، بينما متن الطلب مصفوفة واحدة تحتفظ مفاتيحها بأسماء API (emails وcontacts). والاستجابة مصفوفة مفاتيحها بصيغة camelCase الخاصة بـ API، فيقرأ $audience['contactCount'] العدد.
أرسل إلى جمهور أو أكثر عبر $client->broadcasts->send، الموضّح في صفحة البث. ووضع جهة اتصال في جمهور هو كتابة على الجمهور لا على جهة الاتصال، لذا فإن audiences:write هو النطاق الوحيد الذي يُتحقق منه. والاستثناء هو importContacts. فهو ينشئ جهات اتصال، لذا يحتاج إلى contacts:write أيضًا.
يقبل addContact عنوانًا هو جهة اتصال أصلًا ويرفض ما ليس كذلك، بالخطأ 422 contact_not_found، يُرمى في صورة ValidationException. احفظه أولًا عبر $client->contacts->create. وإضافة شخص مرتين تجيب بالعضوية القائمة أصلًا حاملةً addedAt الأصلي، فالاستدعاء آمن لإعادة المحاولة، ويعيد العميل محاولته بعد فشل في الشبكة.
يمكن إعادة تسمية الجمهور الافتراضي ووصفه كأي جمهور آخر، لكن لا يمكن حذفه ولا تقليصه. ويُرفض الأمران بالخطأ 409 audience_immutable، يُرمى في صورة ConflictException تكون قيمة isConflict() فيه true. احذف جهة الاتصال حين تقصد أن تذهب جهة الاتصال نفسها.
الاستجابة: جمهور
يعيد list صفحة واحدة منها في صورة OpenEmail\Result\Page، مع items وhasMore وnextCursor، والجمهور الافتراضي أولًا ثم الباقي من الأحدث. وتحمل الصفحة 25 ما لم يطلب limit: حتى 100. ويعيد listAll كل الجماهير في مصفوفة واحدة، ويعيد iterate كائن Generator يسلّم جمهورًا واحدًا في كل مرة. ويعيد كلٌّ من get وcreate وupdate جمهورًا واحدًا. أما listContacts فيعيد بدلًا من ذلك صفحة من جهات الاتصال، أي جهات الاتصال نفسها مع تاريخ انضمام كل منها لا سجلات عضوية، ومعه listAllContacts وiterateContacts.
idstring- المقبض الدائم، `aud_` يليه 24 حرفاً ست عشرياً. الأسماء ليست فريدة، فهذا ما ينتمي إلى الإعدادات المخزَّنة.
namestring- يُقلَّم عند الكتابة، من 1 إلى 120 حرفاً. ويجوز أن يتشارك جمهوران اسماً واحداً، لأن الجمهور يُعنوَن بمعرّفه.
descriptionstring or null- نص حر لمن يقرأ القائمة لاحقًا. ويكون null حين لم يكتب أحد شيئًا، و`'description' => null` في `update` يمسحه.
builtinstring or null- القيمة `default` على صف واحد بالضبط في كل مساحة عمل، وهو الجمهور الذي يحمل كل جهات الاتصال، وnull على كل جمهور أنشأه شخص. قارنها بـ `'default'` بدل التحقق من أنها null، كي لا يُحسب جمهور مدمج يُضاف لاحقًا على أنه الجمهور الافتراضي.
contactCountint- كم جهة اتصال في الجمهور، محسوبةً لحظة القراءة لا مأخوذة من ذاكرة مؤقتة. وقراءتان على جانبي `contacts->create` تختلفان بواحدة.
lastContactAtstring or null- بصيغة ISO 8601 بتوقيت UTC، متى انضمت آخر جهة اتصال إلى هذا الجمهور. ويكون null ما دام الجمهور فارغًا.
createdAtstring- بصيغة ISO 8601 بتوقيت UTC، متى أُنشئ الجمهور. وهو يحدد ترتيب القائمة بعد الجمهور الافتراضي.
updatedAtstring- بصيغة ISO 8601 بتوقيت UTC، ويُحدَّث بإعادة التسمية أو تغيير الوصف. ولا تمسّه تغييرات العضوية.
المعاملات: audiences->listContacts
limitint- كم جهة اتصال في كل صفحة، عدد صحيح من 1 إلى 200، والافتراضي 50.
cursorstring- `nextCursor` من الصفحة السابقة، يُرسَل مع `q:` و`source:` و`sort:` و`statuses:` نفسها. والمؤشر الذي يسمّي جهة اتصال ليست في هذا الجمهور يعطي 400 `invalid_cursor`، يُرمى في صورة `InvalidRequestException`.
qstring- يبحث في الاسم والعنوان، حتى 200 حرف. وإن لم يطابق شيء تمامًا في الصفحة الأولى، تُعاد تهجئات قريبة بدلًا من ذلك، وتواصل الصفحات التالية المطابقة بالطريقة نفسها.
sourcestring- `manual` لجهات الاتصال التي حفظها شخص عمدًا، و`auto` لتلك التي سجّلها محرّر الرسائل في التطبيق. اتركه للحصول على كل من في الجمهور.
sortstring- يتبع `last-heard-newest` (الافتراضي) و`last-heard-oldest` قيمة `lastSeenAt`، وتأتي جهات الاتصال التي لم تُراسَل قط في الآخر في الأول وفي البداية في الثاني. ويتبع `added-newest` و`added-oldest` وقت انضمام كل جهة اتصال إلى هذا الجمهور، ويتجاهل `name` حالة الأحرف ويرتّب جهة الاتصال التي بلا اسم بحسب عنوانها.
statusesstring or array- يُبقي `['subscribed']` الأعضاء الذين لم يلغوا اشتراكهم و`['unsubscribed']` الذين ألغوه. اتركه، أو مرّر مصفوفة فارغة، أو اذكر القيمتين، للحصول على كل من في الجمهور. ويحتوي `OpenEmail\Constants\AudienceMemberStatuses` على القيم، ويرسلها العميل مضمومة بفواصل بوصفها معامل الاستعلام `status`.
الاستجابة: جهة اتصال في جمهور
يعيد listContacts صفحة OpenEmail\Result\Page من مصفوفات جهات الاتصال، ويمر listAllContacts وiterateContacts على كل الصفحات بالوسائط المسمّاة نفسها. وكل صف جهة اتصال بالشكل الذي يعيده contacts->list، وحقولها مشروحة في صفحة جهات الاتصال، مع حقلين إضافيين. والمرور على كل الصفحات هو طريقة تصدير الجمهور.
addedAtstring- بصيغة ISO 8601 بتوقيت UTC، متى انضمت جهة الاتصال إلى هذا الجمهور. وإخراج جهة اتصال ثم إضافتها مجددًا يبدأ عدّها من جديد.
unsubscribedAtstring or null- بصيغة ISO 8601 بتوقيت UTC، متى ألغت جهة الاتصال اشتراكها من بث أُرسل إلى هذا الجمهور، أو null ما دامت مشتركة. وجهة الاتصال التي ألغت اشتراكها تبقى في الجمهور، ويتخطاها البث الموجّه إليه. وإخراجها ثم إضافتها مجددًا يجعلها مشتركة من جديد.
الإضافة والإزالة دفعة واحدة
يأخذ addContacts وremoveContacts مصفوفة فيها emails، وهي قائمة من 1 إلى 200 عنوان، ويغيّران جمهورًا واحدًا بطلب واحد. ولا ينشئ addContacts جهة اتصال أبدًا. فالعنوان الذي ليس جهة اتصال يعود في missing، وimportContacts هو الاستدعاء الذي ينشئها. وكلاهما آمن للتكرار، فيعيد العميل محاولتهما بعد فشل في الشبكة، وإعادة المحاولة تبلّغ عن الأشخاص أنفسهم بوصفهم منجزين أصلًا بدل أن تفشل.
الإضافة إلى الجمهور الافتراضي تجيب بقيمة 0 في added، لأن كل جهة اتصال فيه أصلًا، وremoveContacts عليه يُرفض بالخطأ 409 audience_immutable. وإخراج شخص من جمهور يُبقيه في دفتر العناوين وفي الجمهور الافتراضي وفي جماهيره الأخرى.
audienceIdstring- الجمهور الذي غيّره الاستدعاء، في النتيجتين كلتيهما.
addedint- في نتيجة `addContacts`: العضويات الجديدة التي أنشأها هذا الاستدعاء.
unchangedint- في نتيجة `addContacts`: جهات الاتصال التي كانت في الجمهور أصلًا. ولم يُكتب لها شيء.
removedint- في نتيجة `removeContacts`: العضويات التي أزالها هذا الاستدعاء.
notInAudiencearray- في نتيجة `removeContacts`: جهات الاتصال التي لم تكن في الجمهور، فلم يحدث لها شيء.
missingarray- في كلتيهما: العناوين التي ليست جهات اتصال في مساحة العمل هذه، بأحرف صغيرة ومن دون تكرار.
الاستيراد
importContacts هو استيراد CSV في صفحة الجمهور. يأخذ مصفوفة فيها contacts، وهي قائمة من 1 إلى 500 مصفوفة، لكل منها email وname اختياري. وكل عنوان سليم الصياغة يصبح جهة اتصال إن لم يكن كذلك بعد، وينتهي الجميع في الجمهور. أرسل القائمة الأطول على عدة استدعاءات. ويتطلب audiences:write وcontacts:write، والمفتاح الذي ينقصه أحدهما يُرفض بالخطأ 403 insufficient_scope، حيث تكون قيمة isScopeMissing() في الاستثناء true.
العنوان الذي هو جهة اتصال أصلًا يُعاد استخدامه ويحتفظ باسمه، وname هنا لا يملأ إلا اسمًا كان فارغًا. وتُحفظ جهة الاتصال الجديدة بوصفها manual وتنضم إلى الجمهور الافتراضي أيضًا، والعنوان الذي حُذف من دفتر العناوين يعود. وإعادة إرسال الصفوف نفسها لا تنشئ شيئًا مرتين، فيعيد العميل محاولة الاستدعاء بعد فشل في الشبكة.
audienceIdstring- الجمهور الذي ذهبت إليه الصفوف.
createdint- جهات الاتصال الجديدة التي حفظها هذا الاستدعاء.
addedint- العضويات الجديدة في هذا الجمهور، بما فيها جهات الاتصال التي كانت موجودة ولم تكن فيه بعد.
skippedint- الصفوف التي لم تُستورد لأن العنوان كان غير سليم.
invalidarray- العناوين غير السليمة، كما أُرسلت تمامًا.
الإفراغ
يُخرج empty($id) كل جهة اتصال من جمهور واحد بطلب واحد ويعيد الجمهور كما هو الآن، مع contactCount بقيمة 0، مضافًا إليه removed، أي عدد العضويات المُزالة. ويحتفظ الجمهور بمعرّفه واسمه ووصفه، وتبقى كل جهة اتصال في دفتر العناوين وفي جماهيرها الأخرى.
لا يمكن التراجع عن ذلك، ولا شيء يسجّل مَن كان في القائمة، لذا مرّ على listAllContacts أولًا إن كنت قد تريد استعادتها. ولا يمكن إفراغ الجمهور الافتراضي، ويُرفض الاستدعاء بالخطأ 409 audience_immutable. ولا يعيد العميل محاولة empty بعد فشل في الشبكة، لأن الاستدعاء الثاني ينجح مع removed بقيمة 0. وإن ضاعت استجابة، فاقرأ الجمهور عبر get.
النمو
يقرأ growth كم جهة اتصال انضمت إلى كل جمهور خلال نافذة تنتهي الآن، وكم منها ألغى اشتراكه داخلها، باليوم أو الساعة أو الدقيقة. وهو المخطط في صفحة الجماهير. يأخذ وسائط مسمّاة، ويتطلب audiences:read، ويعيد مصفوفة واحدة.
$growth = $client->audiences->growth( audienceIds: ['aud_9f2c4b7e1a0d63d84c5f2e7b'], days: 90, grain: 'day', offsetMinutes: intdiv((int) date('Z'), 60),); echo $growth['totals']['added'], ' joins since ', $growth['since'], PHP_EOL; foreach ($growth['series'] as $series) { echo $series['name'], ': ', $series['before'], ' before the window, ', $series['total'], ' now', PHP_EOL;}يسجّل الجمهور متى انضم شخص ما ولا يسجّل أبدًا متى غادر، لذا فكل رقم يعدّ الأشخاص الذين ما زالوا في القائمة اليوم بحسب تاريخ انضمامهم، ولا ينخفض أي خط أبدًا. وجهة الاتصال التي انضمت ثم غادرت لا تدخل في أي من الأرقام.
المعاملات
audienceIdsstring or array- حتى 50 معرّف جمهور، في صورة قائمة أو سلسلة نصية واحدة مفصولة بفواصل، تُرسل مضمومة بفواصل. اتركه، أو مرّر مصفوفة فارغة، للحصول على كل الجماهير. والمعرّف الذي ليس جمهورًا في مساحة العمل هذه يعطي 404 `audience_not_found`، وما يزيد على 50 يعطي 422.
daysint- إلى أي مدى تمتد النافذة إلى الوراء، من 1 إلى 1095. وتكون 30 حين لا يُعطى `days:` ولا `minutes:`.
minutesint- النافذة بالدقائق، من 1 إلى 1576800، لنافذة أقصر من يوم. وتغلب على `days:` حين يُعطى الاثنان.
grainstring- حجم كل فترة فرعية: `day` (الافتراضي) أو `hour` أو `minute`.
offsetMinutesint- إزاحة المشاهد عن UTC بالدقائق، من -840 إلى 840، كي تبدأ فواصل الأيام والساعات عند حدودها المحلية. والافتراضي 0. و`intdiv((int) date('Z'), 60)` هي إزاحة المنطقة الزمنية المضبوطة في PHP.
الاستجابة
sincestring- بصيغة ISO 8601 بتوقيت UTC، بداية الفاصل الأول.
untilstring- بصيغة ISO 8601 بتوقيت UTC، لحظة القراءة.
totalsarray- يعدّ `contacts` كل شخص مرة واحدة مهما كان عدد القوائم التي هو فيها، ويجمع `memberships` القوائم، فيُعدّ الشخص مرة عن كل قائمة مقروءة تضمه. ويجمع `added` الانضمامات في النافذة، و`lists` عدد الجماهير التي قُرئت، و`busiest` الفاصل الذي شهد أكبر عدد من الانضمامات، أو null. ويعدّ `subscribed` كل شخص ما زال مشتركًا في واحد على الأقل من الجماهير المقروءة، ويجمع `unsubscribed` إلغاءات الاشتراك داخل النافذة.
seriesarray- عنصر واحد لكل جمهور، الأكبر أولًا ثم حسب الاسم: `id` و`name` و`builtin` و`total` أي الأعضاء الآن، و`subscribed` (من ما زالوا مشتركين)، و`before` (من انضموا قبل `since`)، و`added` (من انضموا داخل النافذة)، و`unsubscribed` (من ألغوا اشتراكهم داخلها)، و`buckets` من الأقدم، وكل منها مصفوفة فيها `bucket` و`added` و`unsubscribed`. وهنا تكون قيمة `builtin` هي `true` في الجمهور الافتراضي و`false` في الباقي، لا السلسلة النصية التي تحملها مصفوفة الجمهور. ولا تُسرد إلا الفواصل التي فيها انضمام أو إلغاء اشتراك، بمفاتيح `YYYY-MM-DD` أو `YYYY-MM-DDTHH` أو `YYYY-MM-DDTHH:MM` بالتوقيت المحلي للإزاحة.