Аудитории
`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. Сначала сохраните его через client.contacts.create. Повторное добавление того же человека отвечает уже существующим членством с исходным addedAt, поэтому вызов безопасно повторять, и гем повторяет его после сетевого сбоя.
Аудиторию по умолчанию можно переименовать и описать, как любую другую, но её нельзя удалить и из неё нельзя убирать контакты. И то и другое отклоняется с 409 audience_immutable, выбрасываемым как OpenEmail::ConflictError с conflict?, равным true. Если нужно убрать сам контакт, удалите контакт.
Ответ: аудитория
list возвращает одну страницу аудиторий как OpenEmail::Page с items, has_more? и next_cursor: сначала аудиторию по умолчанию, а остальные от новых к старым. Страница содержит 25 аудиторий, если limit: не запросит до 100. list_all возвращает все страницы одним Array, а iterate передаёт аудитории по одной в блок или без блока возвращает Enumerator. get, create и update возвращают по одной аудитории. list_contacts вместо этого возвращает страницу контактов: сами контакты с датой вступления каждого, а не записи о членстве, а рядом с ним есть list_all_contacts и iterate_contacts.
idString- Долговечная ручка: `aud_` и следом 24 шестнадцатеричных символа. Имена не уникальны, так что в сохранённой конфигурации место именно этому.
nameString- Обрезается при записи, от 1 до 120 символов. Две аудитории могут носить одно имя, потому что к аудитории обращаются по её идентификатору.
descriptionString or nil- Произвольный текст для того, кто будет читать список позже. nil, если никто ничего не написал, а `description: nil` в `update` его очищает.
builtinString or nil- `default` ровно у одной строки в каждом рабочем пространстве, у аудитории, в которой состоят все контакты, и nil у каждой аудитории, созданной кем-то. Сравнивайте его с `"default"`, а не проверяйте на nil, чтобы встроенную аудиторию, добавленную позже, не приняли за аудиторию по умолчанию.
contactCountInteger- Сколько контактов в аудитории, посчитано в момент чтения, а не взято из кэша. Два чтения по обе стороны от `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:`. Курсор, который называет контакт не из этой аудитории, даёт 400 `invalid_cursor`, выбрасываемый как `OpenEmail::InvalidRequestError`.
qString- Ищет по имени и адресу, до 200 символов. Если на первой странице ничто не совпадает точно, вместо этого возвращаются близкие написания, и следующие страницы продолжают искать так же.
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` содержит значения, и гем отправляет их через запятую как параметр запроса `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. Оба безопасно повторять, поэтому гем повторяет их после сетевого сбоя, а повтор сообщает о тех же людях как об уже обработанных, а не завершается ошибкой.
Добавление в аудиторию по умолчанию отвечает 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 и тоже вступает в аудиторию по умолчанию, а адрес, удалённый из книги, возвращается. Повторная передача тех же строк ничего не создаёт дважды, поэтому гем повторяет вызов после сетевого сбоя.
audienceIdString- Аудитория, в которую попали строки.
createdInteger- Новые контакты, сохранённые этим вызовом.
addedInteger- Новые членства в этой аудитории, включая контакты, которые уже существовали и ещё не были в ней.
skippedInteger- Строки, которые не были импортированы, потому что адрес был некорректным.
invalidArray<String>- Некорректные адреса ровно в том виде, в каком они были отправлены.
Очистка
empty(id) одним запросом убирает все контакты из одной аудитории и возвращает аудиторию в её текущем виде с contactCount, равным 0, плюс removed, число убранных членств. Аудитория сохраняет идентификатор, имя и описание, а каждый контакт остаётся в адресной книге и в других своих аудиториях.
Это нельзя отменить, и нигде не записывается, кто был в списке, поэтому, если список может понадобиться снова, сначала обойдите list_all_contacts. Аудиторию по умолчанию нельзя очистить, и такой вызов отклоняется с 409 audience_immutable. Гем не повторяет 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. Равно 30, если не задано ни `days:`, ни `minutes:`.
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` в местном времени по смещению.