오디언스
`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으로 분기하세요.
오디언스 하나에 대한 호출은 그 id를 첫 번째 인자로 받으며, remove_contact는 주소를 두 번째 인자로 받습니다. 그 밖의 것은 모두 Ruby 키워드 인자이며, 요청 본문은 Hash 하나로 전달할 수도 있습니다. growth와 list_contacts의 옵션은 snake_case(audience_ids:, offset_minutes:)이지만, 본문의 필드는 API의 이름(emails:, contacts:)을 그대로 씁니다. 응답은 API의 camelCase로 된 Symbol 키를 가진 Hash이므로, audience[:contactCount]로 개수를 읽습니다.
하나 이상의 오디언스로 보내려면 브로드캐스트 페이지에 있는 client.broadcasts.send를 쓰세요. 연락처를 오디언스에 넣는 것은 연락처가 아니라 오디언스에 대한 쓰기이므로 확인하는 스코프는 audiences:write뿐입니다. 예외는 import_contacts로, 연락처를 만들기 때문에 contacts:write도 필요합니다.
add_contact는 이미 연락처인 주소를 받고, 그렇지 않은 주소는 OpenEmail::ValidationError로 발생하는 422 contact_not_found로 거부합니다. 먼저 client.contacts.create로 저장하세요. 같은 사람을 두 번 추가하면 이미 존재하는 멤버십이 원래의 addedAt과 함께 반환되므로, 이 호출은 안전하게 재시도할 수 있고 gem은 네트워크 장애 후에 이를 재시도합니다.
기본 오디언스도 다른 오디언스처럼 이름과 설명을 바꿀 수 있지만, 삭제할 수 없고 구성원을 덜어 낼 수도 없습니다. 둘 다 409 audience_immutable로 거부되며, conflict?가 true인 OpenEmail::ConflictError로 발생합니다. 연락처를 없애려면 연락처를 삭제하세요.
응답: 오디언스
list는 이것들의 한 페이지를 items, has_more?, next_cursor를 가진 OpenEmail::Page로 반환하며, 기본 오디언스가 맨 앞이고 나머지는 최신순입니다. 한 페이지에는 25개가 담기며, limit:으로 최대 100개까지 요청할 수 있습니다. list_all은 모든 페이지를 하나의 Array로 반환하고, iterate는 오디언스를 하나씩 블록에 yield하거나 블록이 없으면 Enumerator를 반환합니다. get, create, update는 각각 오디언스 하나를 반환합니다. list_contacts는 대신 연락처의 페이지를 반환하는데, 멤버십 레코드가 아니라 각자 들어온 날짜가 붙은 연락처 자체이며, 그 옆에 list_all_contacts와 iterate_contacts가 있습니다.
idString- 영구적인 핸들로, `aud_` 뒤에 16진수 24자가 붙습니다. 이름은 유일하지 않으므로, 저장된 설정에 들어가야 할 것은 이 값입니다.
nameString- 저장 시 앞뒤 공백이 제거되며 1자에서 120자까지입니다. 오디언스는 id로 지정하므로 두 오디언스가 같은 이름을 가질 수 있습니다.
descriptionString or nil- 나중에 목록을 보는 사람을 위한 자유 텍스트입니다. 아무도 쓰지 않았으면 nil이고, `update`에서 `description: nil`을 주면 지워집니다.
builtinString or nil- 워크스페이스마다 정확히 한 행, 즉 모든 연락처를 담는 오디언스에서는 `default`이고, 누군가 만든 모든 오디언스에서는 nil입니다. 나중에 추가되는 내장 오디언스를 기본 오디언스로 착각하지 않도록, nil인지 검사하지 말고 `"default"`와 비교하세요.
contactCountInteger- 오디언스에 속한 연락처 수로, 캐시된 값이 아니라 읽는 시점에 셉니다. `contacts.create` 앞뒤로 두 번 읽으면 값이 1만큼 차이 납니다.
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:`와 함께 보냅니다. 이 오디언스에 없는 연락처를 가리키는 커서는 `OpenEmail::InvalidRequestError`로 발생하는 400 `invalid_cursor`가 됩니다.
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`에 있으며, gem은 이를 쉼표로 이어 `status` 쿼리 파라미터로 보냅니다.
응답: 오디언스 안의 연락처
list_contacts는 연락처 Hash의 OpenEmail::Page를 반환하고, list_all_contacts와 iterate_contacts는 같은 키워드 인자로 모든 페이지를 훑습니다. 각 행은 contacts.list가 반환하는 형태의 연락처이며(필드는 연락처 페이지에 있습니다), 여기서는 필드가 두 개 더 있습니다. 모든 페이지를 훑는 것이 오디언스를 내보내는 방법입니다.
addedAtString- ISO 8601 UTC, 연락처가 이 오디언스에 들어온 시점입니다. 연락처를 뺐다가 다시 추가하면 새로 시작합니다.
unsubscribedAtString or nil- ISO 8601 UTC, 연락처가 이 오디언스로 보낸 브로드캐스트에서 구독을 해지한 시각이며, 구독 중이면 nil입니다. 구독을 해지한 연락처는 오디언스에 남고, 그 오디언스로의 브로드캐스트는 그 연락처를 건너뜁니다. 뺐다가 다시 넣으면 새로 구독 상태가 됩니다.
일괄 추가와 제거
add_contacts와 remove_contacts는 1~200개의 주소를 담은 Array인 emails:를 받아 한 번의 요청으로 한 오디언스를 바꿉니다. 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 가져오기입니다. 1~500개의 Hash로 된 Array인 contacts:를 받으며, 각 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를 더해 반환합니다. 오디언스는 id, 이름, 설명을 유지하고, 각 연락처는 주소록과 다른 오디언스에 그대로 남습니다.
되돌릴 수 없고 누가 목록에 있었는지 어디에도 기록되지 않으므로, 나중에 되돌리고 싶을 수 있다면 먼저 list_all_contacts로 훑어 두세요. 기본 오디언스는 비울 수 없으며, 그 호출은 409 audience_immutable로 거부됩니다. 두 번째 호출은 removed: 0으로 성공하므로, gem은 네트워크 장애 후에 empty를 재시도하지 않습니다. 응답을 잃었다면 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>- 오디언스 id 최대 50개로, 쉼표로 이어서 보냅니다. 모든 오디언스를 보려면 생략하거나 빈 Array를 전달하세요. 이 워크스페이스의 오디언스가 아닌 id는 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`로, 각각 `bucket`, `added`, `unsubscribed`를 가진 Hash입니다. 여기서 `builtin`은 기본 오디언스에서 `true`, 나머지에서 `false`이며, 오디언스 Hash가 담는 String이 아닙니다. 참여나 구독 해지가 있었던 구간만 나열되며, 키는 오프셋의 현지 시각 기준 `YYYY-MM-DD`, `YYYY-MM-DDTHH`, `YYYY-MM-DDTHH:MM`입니다.