Ruby

Audiências

`audiences.list`, `get`, `create`, `update`, `delete`, `empty`, `growth`, `list_contacts`, `add_contact`, `add_contacts`, `import_contacts`, `remove_contact` e `remove_contacts`.

Todos os métodos

audiences.rb

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)

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 remove_contact recebe o endereço como segundo. Tudo o resto é um argumento nomeado de Ruby, e um corpo de pedido também pode ser passado como um único Hash. As opções de growth e list_contacts estão em snake_case (audience_ids:, offset_minutes:), enquanto os campos de um corpo mantêm os nomes da API (emails:, contacts:). Uma resposta é um Hash com chaves Symbol 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. import_contacts é a exceção. Cria contactos, por isso também precisa de contacts:write.

add_contact aceita um endereço que já é um contacto e recusa um que não o seja, com 422 contact_not_found, lançado como OpenEmail::ValidationError. 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 a gem 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 OpenEmail::ConflictError com conflict? 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::Page, com items, has_more? e next_cursor, 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. list_all devolve todas as páginas num único Array, e iterate passa uma audiência de cada vez a um bloco, ou devolve um Enumerator sem bloco. get, create e update devolvem cada um uma audiência. list_contacts 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 list_all_contacts e iterate_contacts 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 nil: Texto livre para quem ler a lista mais tarde. É nil quando ninguém escreveu nada, e `description: nil` em `update` limpa-o.
builtinString or nil: `default` em exatamente uma linha por espaço de trabalho, a audiência que contém todos os contactos, e nil em todas as audiências que alguém criou. Compare-o com `"default"` em vez de verificar se é nil, para que uma audiência incorporada acrescentada mais tarde não seja confundida com a audiência predefinida.
contactCountInteger: 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 nil: ISO 8601 UTC, quando o contacto que entrou mais recentemente entrou nesta audiência. É nil 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.list_contacts

limitInteger: Quantos contactos por página, um número inteiro de 1 a 200, 50 por omissão.
cursorString: O `next_cursor` 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 `OpenEmail::InvalidRequestError`.
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.
statusesArray<String>: `["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::AUDIENCE_MEMBER_STATUSES` contém os valores, e a gem envia-os unidos por vírgulas como parâmetro de consulta `status`.

Resposta: um contacto numa audiência

list_contacts devolve uma OpenEmail::Page de Hashes de contacto, e list_all_contacts e iterate_contacts 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 nil: ISO 8601 UTC, quando o contacto cancelou a subscrição de uma difusão enviada para esta audiência, ou nil 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

add_contacts e remove_contacts recebem emails:, um Array de 1 a 200 endereços, e alteram uma audiência num só pedido. add_contacts nunca cria um contacto. Um endereço que não o é volta em missing, e import_contacts é a chamada que os cria. Ambas são seguras de repetir, por isso a gem 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: 0, porque todos os contactos já lá estão, e remove_contacts 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.
addedInteger: No resultado de `add_contacts`: as novas associações que esta chamada criou.
unchangedInteger: No resultado de `add_contacts`: contactos que já estavam na audiência. Nada foi escrito para eles.
removedInteger: No resultado de `remove_contacts`: as associações que esta chamada retirou.
notInAudienceArray<String>: No resultado de `remove_contacts`: contactos que não estavam na audiência, pelo que nada lhes aconteceu.
missingArray<String>: Em ambos: os endereços que não são contactos neste espaço de trabalho, em minúsculas e sem repetições.

Importar

import_contacts é a importação CSV da página da audiência. Recebe contacts:, um Array de 1 a 500 Hashes, 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 scope_missing? a true no erro.

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 a gem repete a chamada depois de uma falha de rede.

audienceIdString: A audiência para onde foram as linhas.
createdInteger: Contactos novos que esta chamada guardou.
addedInteger: Novas associações nesta audiência, contando contactos que já existiam e ainda não estavam nela.
skippedInteger: Linhas que não foram importadas porque o endereço estava mal formado.
invalidArray<String>: 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 list_all_contacts se a puder querer de volta. A audiência predefinida não pode ser esvaziada, e a chamada é recusada com 409 audience_immutable. A gem não repete empty depois de uma falha de rede, porque uma segunda chamada tem sucesso com removed: 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 Hash.

audience_growth.rb

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

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

audience_idsArray<String>: Até 50 ids de audiência, 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.
daysInteger: Até onde o período recua, de 1 a 1095. É 30 quando não é dado nem `days:` nem `minutes:`.
minutesInteger: 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`.
offset_minutesInteger: 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. `Time.now.utc_offset / 60` é o desvio da máquina onde o código corre.

Resposta

sinceString: ISO 8601 UTC, o início do primeiro intervalo.
untilString: ISO 8601 UTC, o momento da leitura.
totalsHash: `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 nil. `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<Hash>: 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 Hash com `bucket`, `added` e `unsubscribed`. Aqui `builtin` é `true` na audiência predefinida e `false` nas restantes, e não a String que o Hash 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.