Audiências
`audiences->list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `listContacts`, `addContact`, `addContacts`, `importContacts`, `removeContact` e `removeContacts`.
Todos os métodos
$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;Uma audiência é uma lista de contactos com nome neste espaço de trabalho. Todos os contactos estão na audiência predefinida incorporada desde o momento em que existem, e builtin é o que identifica essa linha. As restantes são suas para criar, preencher e apagar. Baseie a lógica em builtin e não no nome, que qualquer pessoa pode alterar.
Uma chamada sobre uma audiência recebe o seu id como primeiro argumento, e removeContact recebe o endereço como segundo. Os filtros e as opções são argumentos nomeados em camelCase (audienceIds:, offsetMinutes:), enquanto um corpo de pedido é um único array cujas chaves mantêm os nomes da API (emails, contacts). Uma resposta é um array com chaves no camelCase da API, por isso $audience['contactCount'] lê a contagem.
Envie para uma ou mais audiências com $client->broadcasts->send, na página Difusões. Pôr um contacto numa audiência é uma escrita na audiência e não no contacto, por isso audiences:write é o único âmbito verificado. importContacts é a exceção. Cria contactos, por isso também precisa de contacts:write.
addContact aceita um endereço que já é um contacto e recusa um que não o seja, com 422 contact_not_found, lançado como ValidationException. Guarde-o primeiro com $client->contacts->create. Adicionar alguém duas vezes responde com a associação que já existe, com o seu addedAt original, pelo que é seguro repetir a chamada, e o cliente repete-a depois de uma falha de rede.
A audiência predefinida pode ser renomeada e descrita como qualquer outra, mas não pode ser eliminada nem perder membros. Ambas as operações são recusadas com 409 audience_immutable, lançado como ConflictException com isConflict() a true. Elimine o contacto quando a intenção é que o contacto desapareça.
Resposta: uma audiência
list devolve uma página destas como uma OpenEmail\Result\Page, com items, hasMore e nextCursor, com a audiência predefinida primeiro e as restantes da mais recente para a mais antiga. Uma página contém 25, a menos que limit: peça até 100. listAll devolve todas as audiências num único array, e iterate devolve um Generator que entrega uma audiência de cada vez. get, create e update devolvem cada um uma audiência. listContacts devolve, em vez disso, uma página de contactos, os próprios contactos com a data em que cada um entrou em vez de registos de associação, com listAllContacts e iterateContacts ao lado.
idstring- O identificador duradouro: `aud_` seguido de 24 caracteres hexadecimais. Os nomes não são únicos, pelo que é este o valor a guardar na configuração armazenada.
namestring- Os espaços nas extremidades são removidos na escrita; de 1 a 120 caracteres. Duas audiências podem ter o mesmo nome, porque uma audiência é referenciada pelo seu id.
descriptionstring or null- Texto livre para quem ler a lista mais tarde. É null quando ninguém escreveu nada, e `'description' => null` em `update` limpa-o.
builtinstring or null- `default` em exatamente uma linha por espaço de trabalho, a audiência que contém todos os contactos, e null em todas as audiências que alguém criou. Compare-o com `'default'` em vez de verificar se é null, para que uma audiência incorporada acrescentada mais tarde não seja confundida com a audiência predefinida.
contactCountint- Quantos contactos existem na audiência, contados no momento da leitura em vez de guardados em cache. Duas leituras, uma antes e outra depois de um `contacts->create`, diferem em um.
lastContactAtstring or null- ISO 8601 UTC, quando o contacto que entrou mais recentemente entrou nesta audiência. É null enquanto a audiência estiver vazia.
createdAtstring- ISO 8601 UTC, quando a audiência foi criada. Determina a ordem da lista a seguir à predefinida.
updatedAtstring- ISO 8601 UTC, atualizado por uma mudança de nome ou de descrição. As alterações de membros não o afetam.
Parâmetros: audiences->listContacts
limitint- Quantos contactos por página, um número inteiro de 1 a 200, 50 por omissão.
cursorstring- O `nextCursor` da página anterior, enviado com os mesmos `q:`, `source:`, `sort:` e `statuses:`. Um cursor que designa um contacto que não está nesta audiência dá um 400 `invalid_cursor`, lançado como `InvalidRequestException`.
qstring- Pesquisa o nome e o endereço, até 200 caracteres. Quando nada coincide exatamente na primeira página, são devolvidas grafias próximas, e as páginas seguintes continuam a pesquisar da mesma forma.
sourcestring- `manual` para os contactos que alguém guardou de propósito, `auto` para os que o editor de mensagens da aplicação registou. Omita-o para toda a audiência.
sortstring- `last-heard-newest` (por omissão) e `last-heard-oldest` seguem `lastSeenAt`, e os contactos a quem nunca foi enviado correio ficam no fim no primeiro e no início no segundo. `added-newest` e `added-oldest` seguem a data em que cada contacto entrou nesta audiência, e `name` ignora maiúsculas e ordena um contacto sem nome pelo endereço.
statusesstring or array- `['subscribed']` mantém os membros que não cancelaram a subscrição e `['unsubscribed']` os que cancelaram. Omita-o, passe um array vazio ou indique os dois para obter todos na audiência. `OpenEmail\Constants\AudienceMemberStatuses` contém os valores, e o cliente envia-os unidos por vírgulas como parâmetro de consulta `status`.
Resposta: um contacto numa audiência
listContacts devolve uma OpenEmail\Result\Page de arrays de contacto, e listAllContacts e iterateContacts percorrem todas as páginas com os mesmos argumentos nomeados. Cada linha é um contacto com a forma que contacts->list devolve, cujos campos estão na página Contactos, com mais dois. Percorrer todas as páginas é a forma de exportar uma audiência.
addedAtstring- ISO 8601 UTC, quando o contacto entrou nesta audiência. Retirar um contacto e voltar a adicioná-lo recomeça a contagem.
unsubscribedAtstring or null- ISO 8601 UTC, quando o contacto cancelou a subscrição de uma difusão enviada para esta audiência, ou null enquanto tem subscrição. Um contacto sem subscrição continua na audiência, e as difusões para ela ignoram-no. Retirá-lo e voltar a adicioná-lo dá-lhe subscrição de novo.
Adicionar e remover em massa
addContacts e removeContacts recebem um array cujo emails é uma lista de 1 a 200 endereços, e alteram uma audiência num só pedido. addContacts nunca cria um contacto. Um endereço que não o é volta em missing, e importContacts é a chamada que os cria. Ambas são seguras de repetir, por isso o cliente repete-as depois de uma falha de rede, e uma repetição indica as mesmas pessoas como já tratadas em vez de falhar.
Adicionar à audiência predefinida responde added a 0, porque todos os contactos já lá estão, e removeContacts sobre ela é recusado com 409 audience_immutable. Retirar alguém de uma audiência deixa-o no livro de endereços, na audiência predefinida e nas suas outras audiências.
audienceIdstring- A audiência que a chamada alterou, em ambos os resultados.
addedint- No resultado de `addContacts`: as novas associações que esta chamada criou.
unchangedint- No resultado de `addContacts`: contactos que já estavam na audiência. Nada foi escrito para eles.
removedint- No resultado de `removeContacts`: as associações que esta chamada retirou.
notInAudiencearray- No resultado de `removeContacts`: contactos que não estavam na audiência, pelo que nada lhes aconteceu.
missingarray- Em ambos: os endereços que não são contactos neste espaço de trabalho, em minúsculas e sem repetições.
Importar
importContacts é a importação CSV da página da audiência. Recebe um array cujo contacts é uma lista de 1 a 500 arrays, cada um com um email e um name opcional. Cada endereço bem formado torna-se um contacto se ainda não o for, e todos vão parar à audiência. Envie uma lista mais longa em várias chamadas. Requer audiences:write e contacts:write, e uma chave a que falte algum deles é recusada com 403 insufficient_scope, com isScopeMissing() a true na exceção.
Um endereço que já é contacto é reutilizado e mantém o nome, e um name aqui só preenche um que estava vazio. Um contacto novo é guardado como manual e também entra na audiência predefinida, e um endereço que foi apagado do livro volta. Repetir as mesmas linhas não cria nada duas vezes, por isso o cliente repete a chamada depois de uma falha de rede.
audienceIdstring- A audiência para onde foram as linhas.
createdint- Contactos novos que esta chamada guardou.
addedint- Novas associações nesta audiência, contando contactos que já existiam e ainda não estavam nela.
skippedint- Linhas que não foram importadas porque o endereço estava mal formado.
invalidarray- Os endereços mal formados, exatamente como foram enviados.
Esvaziar
empty($id) retira todos os contactos de uma audiência num só pedido e devolve a audiência tal como ficou, com contactCount a 0, mais removed, o número de associações retiradas. A audiência mantém o id, o nome e a descrição, e cada contacto continua no livro de endereços e nas suas outras audiências.
Não pode ser anulado e nada regista quem estava na lista, por isso percorra primeiro listAllContacts se a puder querer de volta. A audiência predefinida não pode ser esvaziada, e a chamada é recusada com 409 audience_immutable. O cliente não repete empty depois de uma falha de rede, porque uma segunda chamada tem sucesso com removed a 0. Se uma resposta se perdeu, leia a audiência com get.
Crescimento
growth lê quantos contactos entraram em cada audiência num período que termina agora, e quantos cancelaram a subscrição dentro dele, por dia, hora ou minuto. É o gráfico da página de audiências. Aceita argumentos nomeados, requer audiences:read e devolve um array.
$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;}Uma audiência regista quando alguém entrou e nunca quando saiu, por isso cada valor conta as pessoas que continuam hoje na lista, pela data em que entraram, e uma linha nunca desce. Um contacto que entrou e depois saiu não está em nenhum dos valores.
Parâmetros
audienceIdsstring or array- Até 50 ids de audiência, como uma lista ou uma string separada por vírgulas, enviados unidos por vírgulas. Omita-o, ou passe um array vazio, para todas as audiências. Um id que não é uma audiência deste espaço de trabalho dá um 404 `audience_not_found`, e mais de 50 dá um 422.
daysint- Até onde o período recua, de 1 a 1095. É 30 quando não é dado nem `days:` nem `minutes:`.
minutesint- O período em minutos, de 1 a 1576800, para um período inferior a um dia. Prevalece sobre `days:` quando ambos são dados.
grainstring- O tamanho de cada intervalo: `day` (por omissão), `hour` ou `minute`.
offsetMinutesint- O desvio de quem consulta em relação a UTC em minutos, de -840 a 840, para que os intervalos diários e horários comecem no seu limite local. 0 por omissão. `intdiv((int) date('Z'), 60)` é o desvio do fuso que o PHP tem configurado.
Resposta
sincestring- ISO 8601 UTC, o início do primeiro intervalo.
untilstring- ISO 8601 UTC, o momento da leitura.
totalsarray- `contacts` conta cada pessoa uma vez, em quantas listas estiver, e `memberships` soma as listas, pelo que uma pessoa conta uma vez por cada lista lida que a contém. `added` soma as entradas no período, `lists` é quantas audiências foram lidas, e `busiest` é o intervalo com mais entradas, ou null. `subscribed` conta cada pessoa ainda subscrita a pelo menos uma das audiências lidas, e `unsubscribed` soma os cancelamentos de subscrição dentro do período.
seriesarray- Uma entrada por audiência, da maior para a menor e depois por nome: `id`, `name`, `builtin`, `total` membros atuais, `subscribed` (os que continuam subscritos), `before` (os que entraram antes de `since`), `added` (os que entraram dentro do período), `unsubscribed` (os que cancelaram a subscrição dentro dele) e `buckets`, do mais antigo para o mais recente, cada um um array com `bucket`, `added` e `unsubscribed`. Aqui `builtin` é `true` na audiência predefinida e `false` nas restantes, e não a string que o array de uma audiência traz. Só são listados os intervalos com alguma entrada ou cancelamento, com chaves `YYYY-MM-DD`, `YYYY-MM-DDTHH` ou `YYYY-MM-DDTHH:MM` na hora local do desvio.