گروه‌های مخاطب
`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 برمی‌گرداند که هر بار یک گروه را yield می‌کند. get، create و update هرکدام یک گروه را برمی‌گردانند. listContacts به‌جای آن صفحه‌ای از مخاطبان برمی‌گرداند، یعنی خود مخاطبان با تاریخ پیوستن هرکدام، نه رکوردهای عضویت، و listAllContacts و iterateContacts کنار آن هستند.
idstring- دستگیرهٔ ماندگار، `aud_` و پس از آن 24 نویسهٔ hex. نام‌ها یکتا نیستند، پس همین است که باید در پیکربندی ذخیره‌شده بیاید.
namestring- هنگام نوشتن فاصله‌های اضافی حذف می‌شود، از 1 تا 120 نویسه. دو audience می‌توانند یک نام داشته باشند، چون audience با id خود آدرس‌دهی می‌شود.
descriptionstring or null- متن آزاد برای کسی که بعداً فهرست را می‌خواند. وقتی کسی چیزی ننوشته باشد null است، و `'description' => null` در `update` آن را پاک می‌کند.
builtinstring or null- `default` دقیقاً روی یک ردیف در هر فضای کاری، همان گروهی که همهٔ مخاطبان را نگه می‌دارد، و روی هر گروهی که کسی ساخته باشد null. آن را با `'default'` مقایسه کنید نه اینکه null بودنش را بیازمایید، تا گروه درون‌ساختی که بعدها اضافه شود با گروه پیش‌فرض اشتباه گرفته نشود.
contactCountint- تعداد مخاطبان درون audience، که در لحظهٔ خواندن شمرده می‌شود نه از حافظهٔ نهان. دو خواندن در دو سوی یک `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:` فرستاده می‌شود. cursorی که به مخاطبی بیرون از این گروه اشاره کند یک 400 `invalid_cursor` است که به‌صورت `InvalidRequestException` پرتاب می‌شود.
qstring- در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.
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 فراخوانی‌ای است که آن‌ها را می‌سازد. تکرار هر دو بی‌خطر است، پس کلاینت پس از شکست شبکه دوباره امتحانشان می‌کند، و تلاش دوباره همان افراد را انجام‌شده گزارش می‌کند به‌جای آنکه شکست بخورد.
افزودن به گروه پیش‌فرض با added برابر 0 پاسخ می‌دهد، چون همهٔ مخاطبان از پیش در آن‌اند، و 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. وقتی نه `days:` داده شود و نه `minutes:`، 30 است.
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` به وقت محلیِ آن اختلاف ساعت.