오디언스
`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으로 분기하세요.
오디언스 하나에 대한 호출은 그 id를 첫 번째 인자로 받으며, removeContact는 주소를 두 번째 인자로 받습니다. 필터와 옵션은 camelCase의 명명된 인자(audienceIds:, offsetMinutes:)이고, 요청 본문은 키가 API의 이름(emails, contacts)을 그대로 쓰는 배열 하나입니다. 응답은 API의 camelCase를 키로 하는 배열이므로, $audience['contactCount']로 개수를 읽습니다.
하나 이상의 오디언스로 보내려면 브로드캐스트 페이지에 있는 $client->broadcasts->send를 쓰세요. 연락처를 오디언스에 넣는 것은 연락처가 아니라 오디언스에 대한 쓰기이므로 확인하는 스코프는 audiences:write뿐입니다. 예외는 importContacts로, 연락처를 만들기 때문에 contacts:write도 필요합니다.
addContact는 이미 연락처인 주소를 받고, 그렇지 않은 주소는 ValidationException으로 던져지는 422 contact_not_found로 거부합니다. 먼저 $client->contacts->create로 저장하세요. 같은 사람을 두 번 추가하면 이미 존재하는 멤버십이 원래의 addedAt과 함께 반환되므로, 이 호출은 안전하게 재시도할 수 있고 클라이언트는 네트워크 장애 후에 이를 재시도합니다.
기본 오디언스도 다른 오디언스처럼 이름과 설명을 바꿀 수 있지만, 삭제할 수 없고 구성원을 덜어 낼 수도 없습니다. 둘 다 409 audience_immutable로 거부되며, isConflict()가 true인 ConflictException으로 던져집니다. 연락처를 없애려면 연락처를 삭제하세요.
응답: 오디언스
list는 이것들의 한 페이지를 items, hasMore, nextCursor를 가진 OpenEmail\Result\Page로 반환하며, 기본 오디언스가 맨 앞이고 나머지는 최신순입니다. 한 페이지에는 25개가 담기며, limit:으로 최대 100개까지 요청할 수 있습니다. listAll은 모든 오디언스를 하나의 배열로 반환하고, iterate는 오디언스를 하나씩 yield하는 Generator를 반환합니다. get, create, update는 각각 오디언스 하나를 반환합니다. listContacts는 대신 연락처의 페이지를 반환하는데, 멤버십 레코드가 아니라 각자 들어온 날짜가 붙은 연락처 자체이며, 그 옆에 listAllContacts와 iterateContacts가 있습니다.
idstring- 영구적인 핸들로, `aud_` 뒤에 16진수 24자가 붙습니다. 이름은 유일하지 않으므로, 저장된 설정에 들어가야 할 것은 이 값입니다.
namestring- 저장 시 앞뒤 공백이 제거되며 1자에서 120자까지입니다. 오디언스는 id로 지정하므로 두 오디언스가 같은 이름을 가질 수 있습니다.
descriptionstring or null- 나중에 목록을 보는 사람을 위한 자유 텍스트입니다. 아무도 쓰지 않았으면 null이고, `update`에서 `'description' => null`을 주면 지워집니다.
builtinstring or null- 워크스페이스마다 정확히 한 행, 즉 모든 연락처를 담는 오디언스에서는 `default`이고, 누군가 만든 모든 오디언스에서는 null입니다. 나중에 추가되는 내장 오디언스를 기본 오디언스로 착각하지 않도록, null인지 검사하지 말고 `'default'`와 비교하세요.
contactCountint- 오디언스에 속한 연락처 수로, 캐시된 값이 아니라 읽는 시점에 셉니다. `contacts->create` 앞뒤로 두 번 읽으면 값이 1만큼 차이 납니다.
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:`와 함께 보냅니다. 이 오디언스에 없는 연락처를 가리키는 커서는 `InvalidRequestException`으로 던져지는 400 `invalid_cursor`가 됩니다.
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입니다. 둘 다 반복해도 안전하므로 클라이언트는 네트워크 장애 후에 재시도하며, 재시도는 실패하지 않고 같은 사람들을 이미 처리된 것으로 보고합니다.
기본 오디언스에 추가하면 모든 연락처가 이미 들어 있으므로 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를 더해 반환합니다. 오디언스는 id, 이름, 설명을 유지하고, 각 연락처는 주소록과 다른 오디언스에 그대로 남습니다.
되돌릴 수 없고 누가 목록에 있었는지 어디에도 기록되지 않으므로, 나중에 되돌리고 싶을 수 있다면 먼저 listAllContacts로 훑어 두세요. 기본 오디언스는 비울 수 없으며, 그 호출은 409 audience_immutable로 거부됩니다. 두 번째 호출은 removed가 0인 채로 성공하므로, 클라이언트는 네트워크 장애 후에 empty를 재시도하지 않습니다. 응답을 잃었다면 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- 오디언스 id 최대 50개로, 리스트나 쉼표로 구분된 문자열 하나로 주며 쉼표로 이어서 보냅니다. 모든 오디언스를 보려면 생략하거나 빈 배열을 전달하세요. 이 워크스페이스의 오디언스가 아닌 id는 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입니다. PHP에 설정된 시간대의 시차는 `intdiv((int) date('Z'), 60)`입니다.
응답
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`입니다.