گروه‌های مخاطب
`audiences.list`، `get`، `create`، `update`، `delete`، `empty`، `growth`، `list_contacts`، `add_contact`، `add_contacts`، `import_contacts`، `remove_contact` و `remove_contacts`.
همهٔ متدها
audiences = client.audiences.list_alleveryone = audiences.find { |audience| audience[:builtin] == "default" } 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.add_contact(list[:id], email: "[email protected]") bulk = client.audiences.add_contacts(list[:id], emails: ["[email protected]", "[email protected]"]) imported = client.audiences.import_contacts( list[:id], contacts: [{email: "[email protected]", name: "Katherine Johnson"}]) members = client.audiences.list_all_contacts(list[:id], q: "grace", sort: "added-newest", limit: 200) growth = client.audiences.growth(audience_ids: [list[:id]], days: 30) client.audiences.update(list[:id], name: "Release notes")client.audiences.remove_contact(list[:id], "[email protected]")client.audiences.remove_contacts(list[:id], emails: ["[email protected]"])client.audiences.empty(list[:id])client.audiences.delete(list[:id]) puts everyone[:contactCount] if everyoneputs bulk[:missing], imported[:created], members.size, growth.dig(:totals, :added)یک گروه مخاطب فهرستی نام‌دار از مخاطبان این فضای کاری است. هر مخاطب از همان لحظهٔ ساخته شدنش در گروه پیش‌فرضِ درون‌ساخت است، و builtin همان چیزی است که آن ردیف را مشخص می‌کند. بقیه را خودتان می‌سازید، پر می‌کنید و حذف می‌کنید. به‌جای نام، که هرکسی می‌تواند عوضش کند، روی builtin شاخه بزنید.
فراخوانی روی یک گروه، شناسهٔ آن را به‌عنوان آرگومان نخست می‌گیرد، و remove_contact نشانی را به‌عنوان آرگومان دوم. بقیه همه کلیدواژه‌های Ruby هستند، و بدنهٔ درخواست را می‌توان به‌صورت یک Hash هم داد. گزینه‌های growth و list_contacts به شکل snake_case هستند (audience_ids:، offset_minutes:)، در حالی که فیلدهای بدنه نام‌های API را نگه می‌دارند (emails:، contacts:). پاسخ یک Hash با کلیدهای Symbol به شکل camelCase در API است، پس audience[:contactCount] تعداد را می‌خواند.
با client.broadcasts.send برای یک یا چند گروه مخاطب بفرستید، در صفحهٔ «ارسال‌های گروهی». گذاشتن مخاطب در یک گروه، نوشتن روی گروه است نه روی مخاطب، پس audiences:write تنها اسکوپی است که بررسی می‌شود. import_contacts استثناست. مخاطب می‌سازد، پس به contacts:write هم نیاز دارد.
add_contact نشانی‌ای را می‌گیرد که از پیش مخاطب است و نشانی‌ای را که نیست با 422 contact_not_found رد می‌کند، که به‌صورت OpenEmail::ValidationError raise می‌شود. نخست آن را با client.contacts.create ذخیره کنید. افزودن دوبارهٔ یک نفر با همان عضویتی که از پیش هست پاسخ می‌دهد، با همان addedAt اصلی، پس تکرار این فراخوانی بی‌خطر است، و gem پس از شکست شبکه دوباره امتحانش می‌کند.
گروه پیش‌فرض را می‌توان مانند هر گروه دیگری تغییر نام داد و توصیف کرد، اما نه می‌توان حذفش کرد و نه از آن کم کرد. هر دو با 409 audience_immutable رد می‌شوند، که به‌صورت OpenEmail::ConflictError با conflict? برابر true raise می‌شود. وقتی می‌خواهید مخاطبی برود، خود مخاطب را حذف کنید.
پاسخ: یک گروه مخاطب
list یک صفحه از این‌ها را به‌صورت یک OpenEmail::Page با items، has_more? و next_cursor برمی‌گرداند، با گروه پیش‌فرض در ابتدا و بقیه به ترتیب تازه‌ترین. هر صفحه 25 مورد دارد، مگر آنکه limit: تا 100 بخواهد. list_all همهٔ صفحه‌ها را در یک Array برمی‌گرداند، و iterate هر بار یک گروه را به یک بلاک yield می‌کند، یا بدون بلاک یک Enumerator برمی‌گرداند. get، create و update هرکدام یک گروه را برمی‌گردانند. list_contacts به‌جای آن صفحه‌ای از مخاطبان برمی‌گرداند، یعنی خود مخاطبان با تاریخ پیوستن هرکدام، نه رکوردهای عضویت، و list_all_contacts و iterate_contacts کنار آن هستند.
idString- دستگیرهٔ ماندگار، `aud_` و پس از آن 24 نویسهٔ hex. نام‌ها یکتا نیستند، پس همین است که باید در پیکربندی ذخیره‌شده بیاید.
nameString- هنگام نوشتن فاصله‌های اضافی حذف می‌شود، از 1 تا 120 نویسه. دو audience می‌توانند یک نام داشته باشند، چون audience با id خود آدرس‌دهی می‌شود.
descriptionString or nil- متن آزاد برای کسی که بعداً فهرست را می‌خواند. وقتی کسی چیزی ننوشته باشد nil است، و `description: nil` در `update` آن را پاک می‌کند.
builtinString or nil- `default` دقیقاً روی یک ردیف در هر فضای کاری، همان گروهی که همهٔ مخاطبان را نگه می‌دارد، و روی هر گروهی که کسی ساخته باشد nil. آن را با `"default"` مقایسه کنید نه اینکه nil بودنش را بیازمایید، تا گروه درون‌ساختی که بعدها اضافه شود با گروه پیش‌فرض اشتباه گرفته نشود.
contactCountInteger- تعداد مخاطبان درون audience، که در لحظهٔ خواندن شمرده می‌شود نه از حافظهٔ نهان. دو خواندن در دو سوی یک `contacts.create` به‌اندازهٔ یک با هم اختلاف دارند.
lastContactAtString or nil- ISO 8601 به وقت UTC، زمانی که تازه‌ترین مخاطب به این گروه پیوست. تا وقتی گروه خالی است nil است.
createdAtString- ISO 8601 به وقت UTC، زمان ساخته شدن گروه. ترتیب فهرست را پس از گروه پیش‌فرض تعیین می‌کند.
updatedAtString- ISO 8601 به وقت UTC، که با تغییر نام یا تغییر توصیف جلو می‌رود. تغییر عضویت‌ها آن را دست نمی‌زند.
پارامترها: audiences.list_contacts
limitInteger- شمار مخاطبان در هر صفحه، عددی صحیح از 1 تا 200، با پیش‌فرض 50.
cursorString- `next_cursor` صفحهٔ قبل، که با همان `q:`، `source:`، `sort:` و `statuses:` فرستاده می‌شود. cursorی که به مخاطبی بیرون از این گروه اشاره کند یک 400 `invalid_cursor` است که به‌صورت `OpenEmail::InvalidRequestError` raise می‌شود.
qString- در نام و نشانی جست‌وجو می‌کند، تا ۲۰۰ نویسه. اگر در صفحهٔ نخست هیچ چیز دقیقاً جور نشود، به‌جایش نوشتارهای نزدیک برگردانده می‌شوند، و صفحه‌های بعدی به همان شیوه جست‌وجو را ادامه می‌دهند.
sourceString- `manual` برای مخاطبانی که کسی عمداً ذخیره کرده، `auto` برای آن‌هایی که کامپوزر برنامه ثبت کرده است. برای همهٔ اعضای گروه آن را ننویسید.
sortString- `last-heard-newest` (پیش‌فرض) و `last-heard-oldest` بر پایهٔ `lastSeenAt` هستند، و مخاطبانی که هرگز برایشان ایمیلی نرفته در اولی آخر و در دومی اول می‌آیند. `added-newest` و `added-oldest` بر پایهٔ زمان پیوستن هر مخاطب به این گروه‌اند، و `name` بزرگی و کوچکی حروف را نادیده می‌گیرد و مخاطب بی‌نام را بر پایهٔ نشانی‌اش مرتب می‌کند.
statusesArray<String>- `["subscribed"]` اعضایی را که لغو اشتراک نکرده‌اند نگه می‌دارد و `["unsubscribed"]` آن‌هایی را که کرده‌اند. برای همهٔ اعضای گروه آن را ننویسید، یک Array خالی بدهید، یا هر دو را نام ببرید. `OpenEmail::AUDIENCE_MEMBER_STATUSES` این مقدارها را دارد، و gem آن‌ها را با کاما به هم وصل‌شده به‌عنوان پارامتر کوئری `status` می‌فرستد.
پاسخ: مخاطبی در یک گروه
list_contacts یک OpenEmail::Page از Hashهای مخاطب برمی‌گرداند، و list_all_contacts و iterate_contacts با همان کلیدواژه‌ها همهٔ صفحه‌ها را می‌پیمایند. هر ردیف مخاطبی است به همان شکلی که contacts.list برمی‌گرداند، که فیلدهایش در صفحهٔ «مخاطبان» آمده، با دو فیلد بیشتر. پیمایش همهٔ صفحه‌ها راه خروجی گرفتن از یک گروه است.
addedAtString- ISO 8601 به وقت UTC، زمانی که مخاطب به این گروه پیوسته است. بیرون آوردن مخاطب و افزودن دوباره‌اش آن را از نو آغاز می‌کند.
unsubscribedAtString or nil- ISO 8601 به وقت UTC، زمانی که مخاطب از یک ارسال گروهی به این گروه لغو اشتراک کرد، یا nil تا وقتی مشترک است. مخاطبِ لغواشتراک‌کرده در گروه می‌ماند، و ارسال‌های گروهی به آن گروه از او رد می‌شوند. بیرون آوردن و افزودن دوباره‌اش، او را از نو مشترک می‌کند.
افزودن و برداشتن گروهی
add_contacts و remove_contacts، emails: را می‌گیرند، یک Array از 1 تا 200 نشانی، و یک گروه را با یک درخواست تغییر می‌دهند. add_contacts هرگز مخاطب نمی‌سازد. نشانی‌ای که مخاطب نیست در missing برمی‌گردد، و import_contacts فراخوانی‌ای است که آن‌ها را می‌سازد. تکرار هر دو بی‌خطر است، پس gem پس از شکست شبکه دوباره امتحانشان می‌کند، و تلاش دوباره همان افراد را انجام‌شده گزارش می‌کند به‌جای آنکه شکست بخورد.
افزودن به گروه پیش‌فرض با added: 0 پاسخ می‌دهد، چون همهٔ مخاطبان از پیش در آن‌اند، و remove_contacts روی آن با 409 audience_immutable رد می‌شود. بیرون آوردن کسی از یک گروه، او را در دفترچهٔ نشانی‌ها، در گروه پیش‌فرض و در گروه‌های دیگرش باقی می‌گذارد.
audienceIdString- گروهی که فراخوانی تغییرش داده، در هر دو نتیجه.
addedInteger- در نتیجهٔ `add_contacts`: عضویت‌های تازه‌ای که این فراخوانی ساخته است.
unchangedInteger- در نتیجهٔ `add_contacts`: مخاطبانی که از پیش در گروه بوده‌اند. چیزی برایشان نوشته نشد.
removedInteger- در نتیجهٔ `remove_contacts`: عضویت‌هایی که این فراخوانی برداشته است.
notInAudienceArray<String>- در نتیجهٔ `remove_contacts`: مخاطبانی که در گروه نبوده‌اند، پس اتفاقی برایشان نیفتاد.
missingArray<String>- در هر دو: نشانی‌هایی که در این فضای کاری مخاطب نیستند، به حروف کوچک و بی‌تکرار.
درون‌بری
import_contacts همان ورود CSV در صفحهٔ گروه مخاطب است. contacts: را می‌گیرد، یک Array از 1 تا 500 Hash، هرکدام با یک email و یک name اختیاری. هر نشانی درست‌ساخت اگر هنوز مخاطب نیست مخاطب می‌شود، و همه به گروه می‌رسند. فهرست بلندتر را در چند فراخوانی بفرستید. به audiences:write و contacts:write نیاز دارد، و کلیدی که هرکدام را نداشته باشد با 403 insufficient_scope رد می‌شود، که scope_missing? روی آن خطا true است.
نشانی‌ای که از پیش مخاطب است دوباره به کار می‌رود و نامش را نگه می‌دارد، و name در اینجا تنها نامی خالی را پر می‌کند. مخاطب تازه با manual ذخیره می‌شود و به گروه پیش‌فرض هم می‌پیوندد، و نشانی‌ای که از دفترچه حذف شده برمی‌گردد. فرستادن دوبارهٔ همان ردیف‌ها چیزی را دو بار نمی‌سازد، پس gem پس از شکست شبکه این فراخوانی را دوباره امتحان می‌کند.
audienceIdString- گروهی که ردیف‌ها به آن رفته‌اند.
createdInteger- مخاطبان تازه‌ای که این فراخوانی ذخیره کرده است.
addedInteger- عضویت‌های تازه در این گروه، شامل مخاطبانی که از پیش وجود داشتند و هنوز در آن نبودند.
skippedInteger- ردیف‌هایی که به دلیل نادرست بودن نشانی درون‌بری نشدند.
invalidArray<String>- نشانی‌های نادرست، دقیقاً همان‌طور که فرستاده شده‌اند.
خالی کردن
empty(id) با یک درخواست همهٔ مخاطبان را از یک گروه بیرون می‌آورد و گروه را به شکل کنونی‌اش برمی‌گرداند، با contactCount برابر 0، به‌علاوهٔ removed، یعنی شمار عضویت‌های برداشته‌شده. گروه شناسه، نام و توضیحش را نگه می‌دارد، و هر مخاطب در دفترچهٔ نشانی‌ها و در گروه‌های دیگرش می‌ماند.
برگشت‌پذیر نیست و هیچ چیزی ثبت نمی‌کند چه کسانی در فهرست بوده‌اند، پس اگر ممکن است آن را دوباره بخواهید، نخست list_all_contacts را بپیمایید. گروه پیش‌فرض را نمی‌توان خالی کرد، و فراخوانی با 409 audience_immutable رد می‌شود. gem پس از شکست شبکه empty را دوباره امتحان نمی‌کند، چون فراخوانی دوم با removed: 0 موفق می‌شود. اگر پاسخی گم شد، گروه را با get بخوانید.
رشد
growth می‌خواند که در بازه‌ای که اکنون پایان می‌یابد چند مخاطب به هر گروه پیوسته‌اند و چند نفر در همان بازه لغو اشتراک کرده‌اند، به تفکیک روز، ساعت یا دقیقه. این همان نمودار صفحهٔ گروه‌های مخاطب است. کلیدواژه می‌گیرد، به audiences:read نیاز دارد و یک Hash برمی‌گرداند.
growth = client.audiences.growth( audience_ids: ["aud_9f2c4b7e1a0d63d84c5f2e7b"], days: 90, grain: "day", offset_minutes: Time.now.utc_offset / 60) puts "#{growth.dig(:totals, :added)} joins since #{growth[:since]}" growth[:series].each do |series| puts "#{series[:name]}: #{series[:before]} before the window, #{series[:total]} now"endگروه مخاطب ثبت می‌کند کسی کی پیوسته و هرگز ثبت نمی‌کند کی رفته، پس هر عدد کسانی را می‌شمارد که امروز هنوز در فهرست‌اند، بر پایهٔ تاریخ پیوستنشان، و هیچ خطی پایین نمی‌آید. مخاطبی که پیوسته و بعد رفته در هیچ‌کدام از عددها نیست.
پارامترها
audience_idsArray<String>- تا 50 شناسهٔ گروه مخاطب، که با کاما به هم وصل‌شده فرستاده می‌شوند. برای همهٔ گروه‌ها آن را ننویسید یا یک Array خالی بدهید. شناسه‌ای که گروه مخاطبی در این فضای کاری نیست یک 404 `audience_not_found` است، و بیش از 50 یک 422.
daysInteger- بازه تا چه اندازه به عقب می‌رود، 1 تا 1095. وقتی نه `days:` داده شود و نه `minutes:`، 30 است.
minutesInteger- بازه برحسب دقیقه، 1 تا 1576800، برای بازه‌ای کوتاه‌تر از یک روز. وقتی هر دو داده شوند، بر `days:` مقدم است.
grainString- اندازهٔ هر بخش: `day` (پیش‌فرض)، `hour` یا `minute`.
offset_minutesInteger- اختلاف ساعت بیننده با UTC برحسب دقیقه، از منفی 840 تا 840، تا بازه‌های روزانه و ساعتی از مرز محلی او آغاز شوند. پیش‌فرض 0. `Time.now.utc_offset / 60` اختلاف ساعت دستگاهی است که کد روی آن اجرا می‌شود.
پاسخ
sinceString- ISO 8601 به وقت UTC، آغاز نخستین بازه.
untilString- ISO 8601 به وقت UTC، لحظهٔ خواندن.
totalsHash- `contacts` هر کس را یک بار می‌شمارد، در هر چند فهرست که باشد، و `memberships` فهرست‌ها را جمع می‌زند، پس هر کس به ازای هر فهرست خوانده‌شده‌ای که او را در بر دارد یک بار شمرده می‌شود. `added` پیوستن‌های درون بازه را جمع می‌زند، `lists` شمار گروه‌های خوانده‌شده است، و `busiest` بازه‌ای است که بیشترین پیوستن را داشته، یا nil. `subscribed` هر کسی را می‌شمارد که هنوز دست‌کم در یکی از گروه‌های خوانده‌شده مشترک است، و `unsubscribed` لغو اشتراک‌های درون بازه را جمع می‌زند.
seriesArray<Hash>- یک مدخل برای هر گروه، از بزرگ‌ترین و سپس بر اساس نام: `id`، `name`، `builtin`، `total` اعضای کنونی، `subscribed` (کسانی که هنوز مشترک‌اند)، `before` (کسانی که پیش از `since` پیوسته‌اند)، `added` (کسانی که درون بازه پیوسته‌اند)، `unsubscribed` (کسانی که درون بازه لغو اشتراک کرده‌اند) و `buckets`، قدیمی‌ترین اول، هرکدام یک Hash با `bucket`، `added` و `unsubscribed`. اینجا `builtin` روی گروه پیش‌فرض `true` و روی بقیه `false` است، نه Stringی که Hash یک گروه دارد. تنها بازه‌هایی که پیوستن یا لغو اشتراکی در آن‌ها بوده فهرست می‌شوند، با کلیدهای `YYYY-MM-DD`، `YYYY-MM-DDTHH` یا `YYYY-MM-DDTHH:MM` به وقت محلیِ آن اختلاف ساعت.